root / doc / hooks.sgml @ 78f66a17
History | View | Annotate | Download (23.7 kB)
1 | a8083063 | Iustin Pop | <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ |
---|---|---|---|
2 | a8083063 | Iustin Pop | ]> |
3 | a8083063 | Iustin Pop | <article class="specification"> |
4 | a8083063 | Iustin Pop | <articleinfo> |
5 | a8083063 | Iustin Pop | <title>Ganeti customisation using hooks</title> |
6 | a8083063 | Iustin Pop | </articleinfo> |
7 | a8083063 | Iustin Pop | <para>Documents ganeti version 1.2</para> |
8 | a8083063 | Iustin Pop | <section> |
9 | a8083063 | Iustin Pop | <title>Introduction</title> |
10 | a8083063 | Iustin Pop | |
11 | a8083063 | Iustin Pop | <para> |
12 | a8083063 | Iustin Pop | In order to allow customisation of operations, ganeti will run |
13 | a8083063 | Iustin Pop | scripts under <filename |
14 | a8083063 | Iustin Pop | class="directory">/etc/ganeti/hooks</filename> based on certain |
15 | a8083063 | Iustin Pop | rules. |
16 | a8083063 | Iustin Pop | </para> |
17 | a8083063 | Iustin Pop | |
18 | a8083063 | Iustin Pop | <para>This is similar to the <filename |
19 | a8083063 | Iustin Pop | class="directory">/etc/network/</filename> structure present in |
20 | a8083063 | Iustin Pop | Debian for network interface handling.</para> |
21 | a8083063 | Iustin Pop | |
22 | a8083063 | Iustin Pop | </section> |
23 | a8083063 | Iustin Pop | |
24 | a8083063 | Iustin Pop | <section> |
25 | a8083063 | Iustin Pop | <title>Organisation</title> |
26 | a8083063 | Iustin Pop | |
27 | a8083063 | Iustin Pop | <para>For every operation, two sets of scripts are run: |
28 | a8083063 | Iustin Pop | |
29 | a8083063 | Iustin Pop | <itemizedlist> |
30 | a8083063 | Iustin Pop | <listitem> |
31 | a8083063 | Iustin Pop | <simpara>pre phase (for authorization/checking)</simpara> |
32 | a8083063 | Iustin Pop | </listitem> |
33 | a8083063 | Iustin Pop | <listitem> |
34 | a8083063 | Iustin Pop | <simpara>post phase (for logging)</simpara> |
35 | a8083063 | Iustin Pop | </listitem> |
36 | a8083063 | Iustin Pop | </itemizedlist> |
37 | a8083063 | Iustin Pop | </para> |
38 | a8083063 | Iustin Pop | |
39 | a8083063 | Iustin Pop | <para>Also, for each operation, the scripts are run on one or |
40 | a8083063 | Iustin Pop | more nodes, depending on the operation type.</para> |
41 | a8083063 | Iustin Pop | |
42 | a8083063 | Iustin Pop | <para>Note that, even though we call them scripts, we are |
43 | a8083063 | Iustin Pop | actually talking about any executable.</para> |
44 | a8083063 | Iustin Pop | |
45 | a8083063 | Iustin Pop | <section> |
46 | a8083063 | Iustin Pop | <title><emphasis>pre</emphasis> scripts</title> |
47 | a8083063 | Iustin Pop | |
48 | a8083063 | Iustin Pop | <para>The <emphasis>pre</emphasis> scripts have a definite |
49 | a8083063 | Iustin Pop | target: to check that the operation is allowed given the |
50 | a8083063 | Iustin Pop | site-specific constraints. You could have, for example, a rule |
51 | a8083063 | Iustin Pop | that says every new instance is required to exists in a |
52 | a8083063 | Iustin Pop | database; to implement this, you could write a script that |
53 | a8083063 | Iustin Pop | checks the new instance parameters against your |
54 | a8083063 | Iustin Pop | database.</para> |
55 | a8083063 | Iustin Pop | |
56 | a8083063 | Iustin Pop | <para>The objective of these scripts should be their return |
57 | a8083063 | Iustin Pop | code (zero or non-zero for success and failure). However, if |
58 | a8083063 | Iustin Pop | they modify the environment in any way, they should be |
59 | a8083063 | Iustin Pop | idempotent, as failed executions could be restarted and thus |
60 | a8083063 | Iustin Pop | the script(s) run again with exactly the same |
61 | a8083063 | Iustin Pop | parameters.</para> |
62 | a8083063 | Iustin Pop | |
63 | 2395c322 | Iustin Pop | <para> |
64 | 2395c322 | Iustin Pop | Note that if a node is unreachable at the time a hooks is run, |
65 | 2395c322 | Iustin Pop | this will not be interpreted as a deny for the execution. In |
66 | 2395c322 | Iustin Pop | other words, only an actual error returned from a script will |
67 | 2395c322 | Iustin Pop | cause abort, and not an unreachable node. |
68 | 2395c322 | Iustin Pop | </para> |
69 | 2395c322 | Iustin Pop | |
70 | 2395c322 | Iustin Pop | <para> |
71 | 2395c322 | Iustin Pop | Therefore, if you want to guarantee that a hook script is run |
72 | 2395c322 | Iustin Pop | and denies an action, it's best to put it on the master node. |
73 | 2395c322 | Iustin Pop | </para> |
74 | 2395c322 | Iustin Pop | |
75 | a8083063 | Iustin Pop | </section> |
76 | a8083063 | Iustin Pop | |
77 | a8083063 | Iustin Pop | <section> |
78 | a8083063 | Iustin Pop | <title><emphasis>post</emphasis> scripts</title> |
79 | a8083063 | Iustin Pop | |
80 | a8083063 | Iustin Pop | <para>These scripts should do whatever you need as a reaction |
81 | a8083063 | Iustin Pop | to the completion of an operation. Their return code is not |
82 | a8083063 | Iustin Pop | checked (but logged), and they should not depend on the fact |
83 | a8083063 | Iustin Pop | that the <emphasis>pre</emphasis> scripts have been |
84 | a8083063 | Iustin Pop | run.</para> |
85 | a8083063 | Iustin Pop | |
86 | a8083063 | Iustin Pop | </section> |
87 | a8083063 | Iustin Pop | |
88 | a8083063 | Iustin Pop | <section> |
89 | a8083063 | Iustin Pop | <title>Naming</title> |
90 | a8083063 | Iustin Pop | |
91 | a8083063 | Iustin Pop | <para>The allowed names for the scripts consist of (similar to |
92 | a8083063 | Iustin Pop | <citerefentry> <refentrytitle>run-parts</refentrytitle> |
93 | a8083063 | Iustin Pop | <manvolnum>8</manvolnum> </citerefentry>) upper and lower |
94 | a8083063 | Iustin Pop | case, digits, underscores and hyphens. In other words, the |
95 | a8083063 | Iustin Pop | regexp |
96 | a8083063 | Iustin Pop | <computeroutput>^[a-zA-Z0-9_-]+$</computeroutput>. Also, |
97 | a8083063 | Iustin Pop | non-executable scripts will be ignored. |
98 | a8083063 | Iustin Pop | </para> |
99 | a8083063 | Iustin Pop | </section> |
100 | a8083063 | Iustin Pop | |
101 | a8083063 | Iustin Pop | <section> |
102 | a8083063 | Iustin Pop | <title>Order of execution</title> |
103 | a8083063 | Iustin Pop | |
104 | a8083063 | Iustin Pop | <para>On a single node, the scripts in a directory are run in |
105 | a8083063 | Iustin Pop | lexicographic order (more exactly, the python string |
106 | a8083063 | Iustin Pop | comparison order). It is advisable to implement the usual |
107 | a8083063 | Iustin Pop | <emphasis>NN-name</emphasis> convention where |
108 | a8083063 | Iustin Pop | <emphasis>NN</emphasis> is a two digit number.</para> |
109 | a8083063 | Iustin Pop | |
110 | a8083063 | Iustin Pop | <para>For an operation whose hooks are run on multiple nodes, |
111 | a8083063 | Iustin Pop | there is no specific ordering of nodes with regard to hooks |
112 | a8083063 | Iustin Pop | execution; you should assume that the scripts are run in |
113 | a8083063 | Iustin Pop | parallel on the target nodes (keeping on each node the above |
114 | a8083063 | Iustin Pop | specified ordering). If you need any kind of inter-node |
115 | a8083063 | Iustin Pop | synchronisation, you have to implement it yourself in the |
116 | a8083063 | Iustin Pop | scripts.</para> |
117 | a8083063 | Iustin Pop | |
118 | a8083063 | Iustin Pop | </section> |
119 | a8083063 | Iustin Pop | |
120 | a8083063 | Iustin Pop | <section> |
121 | a8083063 | Iustin Pop | <title>Execution environment</title> |
122 | a8083063 | Iustin Pop | |
123 | a8083063 | Iustin Pop | <para>The scripts will be run as follows: |
124 | a8083063 | Iustin Pop | <itemizedlist> |
125 | e3c826ec | Michael Hanselmann | <listitem> |
126 | e3c826ec | Michael Hanselmann | <simpara>no command line arguments</simpara> |
127 | e3c826ec | Michael Hanselmann | </listitem> |
128 | a8083063 | Iustin Pop | <listitem> |
129 | a8083063 | Iustin Pop | <simpara>no controlling <acronym>tty</acronym></simpara> |
130 | a8083063 | Iustin Pop | </listitem> |
131 | a8083063 | Iustin Pop | <listitem> |
132 | a8083063 | Iustin Pop | <simpara><varname>stdin</varname> is |
133 | e3c826ec | Michael Hanselmann | actually <filename>/dev/null</filename></simpara> |
134 | a8083063 | Iustin Pop | </listitem> |
135 | a8083063 | Iustin Pop | <listitem> |
136 | a8083063 | Iustin Pop | <simpara><varname>stdout</varname> and |
137 | e3c826ec | Michael Hanselmann | <varname>stderr</varname> are directed to |
138 | e3c826ec | Michael Hanselmann | files</simpara> |
139 | e3c826ec | Michael Hanselmann | </listitem> |
140 | e3c826ec | Michael Hanselmann | <listitem> |
141 | e3c826ec | Michael Hanselmann | <simpara>the <varname>PATH</varname> is reset to |
142 | e3c826ec | Michael Hanselmann | <literal>/sbin:/bin:/usr/sbin:/usr/bin</literal></simpara> |
143 | e3c826ec | Michael Hanselmann | </listitem> |
144 | e3c826ec | Michael Hanselmann | <listitem> |
145 | e3c826ec | Michael Hanselmann | <simpara>the environment is cleared, and only |
146 | e3c826ec | Michael Hanselmann | ganeti-specific variables will be left</simpara> |
147 | a8083063 | Iustin Pop | </listitem> |
148 | a8083063 | Iustin Pop | </itemizedlist> |
149 | a8083063 | Iustin Pop | |
150 | a8083063 | Iustin Pop | </para> |
151 | a8083063 | Iustin Pop | |
152 | a8083063 | Iustin Pop | <para>All informations about the cluster is passed using |
153 | a8083063 | Iustin Pop | environment variables. Different operations will have sligthly |
154 | a8083063 | Iustin Pop | different environments, but most of the variables are |
155 | a8083063 | Iustin Pop | common.</para> |
156 | a8083063 | Iustin Pop | |
157 | a8083063 | Iustin Pop | </section> |
158 | a8083063 | Iustin Pop | |
159 | a8083063 | Iustin Pop | |
160 | a8083063 | Iustin Pop | <section> |
161 | a8083063 | Iustin Pop | <title>Operation list</title> |
162 | a8083063 | Iustin Pop | <table> |
163 | a8083063 | Iustin Pop | <title>Operation list</title> |
164 | a8083063 | Iustin Pop | <tgroup cols="7"> |
165 | a8083063 | Iustin Pop | <colspec> |
166 | a8083063 | Iustin Pop | <colspec> |
167 | a8083063 | Iustin Pop | <colspec> |
168 | a8083063 | Iustin Pop | <colspec> |
169 | a8083063 | Iustin Pop | <colspec> |
170 | a8083063 | Iustin Pop | <colspec colname="prehooks"> |
171 | a8083063 | Iustin Pop | <colspec colname="posthooks"> |
172 | a8083063 | Iustin Pop | <spanspec namest="prehooks" nameend="posthooks" |
173 | a8083063 | Iustin Pop | spanname="bothhooks"> |
174 | a8083063 | Iustin Pop | <thead> |
175 | a8083063 | Iustin Pop | <row> |
176 | a8083063 | Iustin Pop | <entry>Operation ID</entry> |
177 | a8083063 | Iustin Pop | <entry>Directory prefix</entry> |
178 | a8083063 | Iustin Pop | <entry>Description</entry> |
179 | a8083063 | Iustin Pop | <entry>Command</entry> |
180 | a8083063 | Iustin Pop | <entry>Supported env. variables</entry> |
181 | a8083063 | Iustin Pop | <entry><emphasis>pre</emphasis> hooks</entry> |
182 | a8083063 | Iustin Pop | <entry><emphasis>post</emphasis> hooks</entry> |
183 | a8083063 | Iustin Pop | </row> |
184 | a8083063 | Iustin Pop | </thead> |
185 | a8083063 | Iustin Pop | <tbody> |
186 | a8083063 | Iustin Pop | <row> |
187 | a8083063 | Iustin Pop | <entry>OP_INIT_CLUSTER</entry> |
188 | a8083063 | Iustin Pop | <entry><filename class="directory">cluster-init</filename></entry> |
189 | a8083063 | Iustin Pop | <entry>Initialises the cluster</entry> |
190 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-cluster init</computeroutput></entry> |
191 | a8083063 | Iustin Pop | <entry><constant>CLUSTER</constant>, <constant>MASTER</constant></entry> |
192 | a8083063 | Iustin Pop | <entry spanname="bothhooks">master node, cluster name</entry> |
193 | a8083063 | Iustin Pop | </row> |
194 | a8083063 | Iustin Pop | <row> |
195 | a8083063 | Iustin Pop | <entry>OP_MASTER_FAILOVER</entry> |
196 | a8083063 | Iustin Pop | <entry><filename class="directory">master-failover</filename></entry> |
197 | a8083063 | Iustin Pop | <entry>Changes the master</entry> |
198 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-cluster master-failover</computeroutput></entry> |
199 | a8083063 | Iustin Pop | <entry><constant>OLD_MASTER</constant>, <constant>NEW_MASTER</constant></entry> |
200 | a8083063 | Iustin Pop | <entry>the new master</entry> |
201 | a8083063 | Iustin Pop | <entry>all nodes</entry> |
202 | a8083063 | Iustin Pop | </row> |
203 | a8083063 | Iustin Pop | <row> |
204 | a8083063 | Iustin Pop | <entry>OP_ADD_NODE</entry> |
205 | a8083063 | Iustin Pop | <entry><filename class="directory">node-add</filename></entry> |
206 | a8083063 | Iustin Pop | <entry>Adds a new node to the cluster</entry> |
207 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-node add</computeroutput></entry> |
208 | a8083063 | Iustin Pop | <entry><constant>NODE_NAME</constant>, <constant>NODE_PIP</constant>, <constant>NODE_SIP</constant></entry> |
209 | a8083063 | Iustin Pop | <entry>all existing nodes</entry> |
210 | a8083063 | Iustin Pop | <entry>all existing nodes plus the new node</entry> |
211 | a8083063 | Iustin Pop | </row> |
212 | a8083063 | Iustin Pop | <row> |
213 | a8083063 | Iustin Pop | <entry>OP_REMOVE_NODE</entry> |
214 | a8083063 | Iustin Pop | <entry><filename class="directory">node-remove</filename></entry> |
215 | a8083063 | Iustin Pop | <entry>Removes a node from the cluster</entry> |
216 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-node remove</computeroutput></entry> |
217 | a8083063 | Iustin Pop | <entry><constant>NODE_NAME</constant></entry> |
218 | a8083063 | Iustin Pop | <entry spanname="bothhooks">all existing nodes except the removed node</entry> |
219 | a8083063 | Iustin Pop | </row> |
220 | a8083063 | Iustin Pop | <row> |
221 | a8083063 | Iustin Pop | <entry>OP_INSTANCE_ADD</entry> |
222 | a8083063 | Iustin Pop | <entry><filename class="directory">instance-add</filename></entry> |
223 | a8083063 | Iustin Pop | <entry>Creates a new instance</entry> |
224 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-instance add</computeroutput></entry> |
225 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant>, <constant>DISK_TEMPLATE</constant>, <constant>MEM_SIZE</constant>, <constant>DISK_SIZE</constant>, <constant>SWAP_SIZE</constant>, <constant>VCPUS</constant>, <constant>INSTANCE_IP</constant>, <constant>INSTANCE_ADD_MODE</constant>, <constant>SRC_NODE</constant>, <constant>SRC_PATH</constant>, <constant>SRC_IMAGE</constant></entry> |
226 | a8083063 | Iustin Pop | <entry spanname="bothhooks" morerows="4">master node, primary and |
227 | a8083063 | Iustin Pop | secondary nodes</entry> |
228 | a8083063 | Iustin Pop | </row> |
229 | a8083063 | Iustin Pop | <row> |
230 | a8083063 | Iustin Pop | <entry>OP_BACKUP_EXPORT</entry> |
231 | a8083063 | Iustin Pop | <entry><filename class="directory">instance-export</filename></entry> |
232 | a8083063 | Iustin Pop | <entry>Export the instance</entry> |
233 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-backup export</computeroutput></entry> |
234 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>EXPORT_NODE</constant>, <constant>EXPORT_DO_SHUTDOWN</constant></entry> |
235 | a8083063 | Iustin Pop | </row> |
236 | a8083063 | Iustin Pop | <row> |
237 | a8083063 | Iustin Pop | <entry>OP_INSTANCE_START</entry> |
238 | a8083063 | Iustin Pop | <entry><filename class="directory">instance-start</filename></entry> |
239 | a8083063 | Iustin Pop | <entry>Starts an instance</entry> |
240 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-instance start</computeroutput></entry> |
241 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant>, <constant>FORCE</constant></entry> |
242 | a8083063 | Iustin Pop | </row> |
243 | a8083063 | Iustin Pop | <row> |
244 | a8083063 | Iustin Pop | <entry>OP_INSTANCE_SHUTDOWN</entry> |
245 | a8083063 | Iustin Pop | <entry><filename class="directory">instance-shutdown</filename></entry> |
246 | a8083063 | Iustin Pop | <entry>Stops an instance</entry> |
247 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-instance shutdown</computeroutput></entry> |
248 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant></entry> |
249 | a8083063 | Iustin Pop | </row> |
250 | a8083063 | Iustin Pop | <row> |
251 | a8083063 | Iustin Pop | <entry>OP_INSTANCE_MODIFY</entry> |
252 | a8083063 | Iustin Pop | <entry><filename class="directory">instance-modify</filename></entry> |
253 | a8083063 | Iustin Pop | <entry>Modifies the instance parameters.</entry> |
254 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-instance modify</computeroutput></entry> |
255 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>MEM_SIZE</constant>, <constant>VCPUS</constant>, <constant>INSTANCE_IP</constant></entry> |
256 | a8083063 | Iustin Pop | </row> |
257 | a8083063 | Iustin Pop | <row> |
258 | a8083063 | Iustin Pop | <entry>OP_INSTANCE_FAILOVER</entry> |
259 | a8083063 | Iustin Pop | <entry><filename class="directory">instance-failover</filename></entry> |
260 | a8083063 | Iustin Pop | <entry>Failover an instance</entry> |
261 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-instance start</computeroutput></entry> |
262 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant>, <constant>IGNORE_CONSISTENCY</constant></entry> |
263 | a8083063 | Iustin Pop | </row> |
264 | a8083063 | Iustin Pop | <row> |
265 | a8083063 | Iustin Pop | <entry>OP_INSTANCE_REMOVE</entry> |
266 | a8083063 | Iustin Pop | <entry><filename class="directory">instance-remove</filename></entry> |
267 | a8083063 | Iustin Pop | <entry>Remove an instance</entry> |
268 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-instance remove</computeroutput></entry> |
269 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant></entry> |
270 | 1d67656e | Iustin Pop | <entry spanname="bothhooks">master node</entry> |
271 | a8083063 | Iustin Pop | </row> |
272 | a8083063 | Iustin Pop | <row> |
273 | a8083063 | Iustin Pop | <entry>OP_INSTANCE_ADD_MDDRBD</entry> |
274 | a8083063 | Iustin Pop | <entry><filename class="directory">mirror-add</filename></entry> |
275 | a8083063 | Iustin Pop | <entry>Adds a mirror component</entry> |
276 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-instance add-mirror</computeroutput></entry> |
277 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>NEW_SECONDARY</constant>, <constant>DISK_NAME</constant></entry> |
278 | a8083063 | Iustin Pop | </row> |
279 | a8083063 | Iustin Pop | <row> |
280 | a8083063 | Iustin Pop | <entry>OP_INSTANCE_REMOVE_MDDRBD</entry> |
281 | a8083063 | Iustin Pop | <entry><filename class="directory">mirror-remove</filename></entry> |
282 | a8083063 | Iustin Pop | <entry>Removes a mirror component</entry> |
283 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-instance remove-mirror</computeroutput></entry> |
284 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>OLD_SECONDARY</constant>, <constant>DISK_NAME</constant>, <constant>DISK_ID</constant></entry> |
285 | a8083063 | Iustin Pop | </row> |
286 | a8083063 | Iustin Pop | <row> |
287 | a8083063 | Iustin Pop | <entry>OP_INSTANCE_REPLACE_DISKS</entry> |
288 | a8083063 | Iustin Pop | <entry><filename class="directory">mirror-replace</filename></entry> |
289 | a8083063 | Iustin Pop | <entry>Replace all mirror components</entry> |
290 | a8083063 | Iustin Pop | <entry><computeroutput>gnt-instance replace-disks</computeroutput></entry> |
291 | a8083063 | Iustin Pop | <entry><constant>INSTANCE_NAME</constant>, <constant>OLD_SECONDARY</constant>, <constant>NEW_SECONDARY</constant></entry> |
292 | a8083063 | Iustin Pop | |
293 | a8083063 | Iustin Pop | </row> |
294 | 470e7e06 | Guido Trotter | <row> |
295 | 470e7e06 | Guido Trotter | <entry>OP_CLUSTER_VERIFY</entry> |
296 | 470e7e06 | Guido Trotter | <entry><filename class="directory">cluster-verify</filename></entry> |
297 | 470e7e06 | Guido Trotter | <entry>Verifies the cluster status</entry> |
298 | 470e7e06 | Guido Trotter | <entry><computeroutput>gnt-cluster verify</computeroutput></entry> |
299 | 470e7e06 | Guido Trotter | <entry><constant>CLUSTER</constant>, <constant>MASTER</constant></entry> |
300 | 470e7e06 | Guido Trotter | <entry>NONE</entry> |
301 | 470e7e06 | Guido Trotter | <entry>all nodes</entry> |
302 | 470e7e06 | Guido Trotter | </row> |
303 | a8083063 | Iustin Pop | </tbody> |
304 | a8083063 | Iustin Pop | </tgroup> |
305 | a8083063 | Iustin Pop | </table> |
306 | a8083063 | Iustin Pop | </section> |
307 | a8083063 | Iustin Pop | |
308 | a8083063 | Iustin Pop | <section> |
309 | a8083063 | Iustin Pop | <title>Environment variables</title> |
310 | a8083063 | Iustin Pop | |
311 | a8083063 | Iustin Pop | <para>Note that all variables listed here are actually prefixed |
312 | a8083063 | Iustin Pop | with <constant>GANETI_</constant> in order to provide a |
313 | a8083063 | Iustin Pop | different namespace.</para> |
314 | a8083063 | Iustin Pop | |
315 | a8083063 | Iustin Pop | <section> |
316 | a8083063 | Iustin Pop | <title>Common variables</title> |
317 | a8083063 | Iustin Pop | |
318 | a8083063 | Iustin Pop | <para>This is the list of environment variables supported by |
319 | a8083063 | Iustin Pop | all operations:</para> |
320 | a8083063 | Iustin Pop | |
321 | a8083063 | Iustin Pop | <variablelist> |
322 | a8083063 | Iustin Pop | <varlistentry> |
323 | a8083063 | Iustin Pop | <term>HOOKS_VERSION</term> |
324 | a8083063 | Iustin Pop | <listitem> |
325 | a8083063 | Iustin Pop | <para>Documents the hooks interface version. In case this |
326 | a8083063 | Iustin Pop | doesnt match what the script expects, it should not |
327 | a8083063 | Iustin Pop | run. The documents conforms to the version |
328 | a8083063 | Iustin Pop | <literal>1</literal>.</para> |
329 | a8083063 | Iustin Pop | </listitem> |
330 | a8083063 | Iustin Pop | </varlistentry> |
331 | a8083063 | Iustin Pop | <varlistentry> |
332 | a8083063 | Iustin Pop | <term>HOOKS_PHASE</term> |
333 | a8083063 | Iustin Pop | <listitem> |
334 | a8083063 | Iustin Pop | <para>one of <constant>PRE</constant> or |
335 | a8083063 | Iustin Pop | <constant>POST</constant> denoting which phase are we |
336 | a8083063 | Iustin Pop | in.</para> |
337 | a8083063 | Iustin Pop | </listitem> |
338 | a8083063 | Iustin Pop | </varlistentry> |
339 | a8083063 | Iustin Pop | <varlistentry> |
340 | a8083063 | Iustin Pop | <term>CLUSTER</term> |
341 | a8083063 | Iustin Pop | <listitem> |
342 | a8083063 | Iustin Pop | <para>the cluster name</para> |
343 | a8083063 | Iustin Pop | </listitem> |
344 | a8083063 | Iustin Pop | </varlistentry> |
345 | a8083063 | Iustin Pop | <varlistentry> |
346 | a8083063 | Iustin Pop | <term>MASTER</term> |
347 | a8083063 | Iustin Pop | <listitem> |
348 | a8083063 | Iustin Pop | <para>the master node</para> |
349 | a8083063 | Iustin Pop | </listitem> |
350 | a8083063 | Iustin Pop | </varlistentry> |
351 | a8083063 | Iustin Pop | <varlistentry> |
352 | a8083063 | Iustin Pop | <term>OP_ID</term> |
353 | a8083063 | Iustin Pop | <listitem> |
354 | a8083063 | Iustin Pop | <para>one of the <constant>OP_*</constant> values from |
355 | a8083063 | Iustin Pop | the table of operations</para> |
356 | a8083063 | Iustin Pop | </listitem> |
357 | a8083063 | Iustin Pop | </varlistentry> |
358 | a8083063 | Iustin Pop | <varlistentry> |
359 | a8083063 | Iustin Pop | <term>OBJECT_TYPE</term> |
360 | a8083063 | Iustin Pop | <listitem> |
361 | a8083063 | Iustin Pop | <para>one of <simplelist type="inline"> |
362 | a8083063 | Iustin Pop | <member><constant>INSTANCE</constant></member> |
363 | a8083063 | Iustin Pop | <member><constant>NODE</constant></member> |
364 | a8083063 | Iustin Pop | <member><constant>CLUSTER</constant></member> |
365 | a8083063 | Iustin Pop | </simplelist>, showing the target of the operation. |
366 | a8083063 | Iustin Pop | </para> |
367 | a8083063 | Iustin Pop | </listitem> |
368 | a8083063 | Iustin Pop | </varlistentry> |
369 | a8083063 | Iustin Pop | <!-- commented out since it causes problems in our rpc |
370 | a8083063 | Iustin Pop | multi-node optimised calls |
371 | a8083063 | Iustin Pop | <varlistentry> |
372 | a8083063 | Iustin Pop | <term>HOST_NAME</term> |
373 | a8083063 | Iustin Pop | <listitem> |
374 | a8083063 | Iustin Pop | <para>The name of the node the hook is run on as known by |
375 | a8083063 | Iustin Pop | the cluster.</para> |
376 | a8083063 | Iustin Pop | </listitem> |
377 | a8083063 | Iustin Pop | </varlistentry> |
378 | a8083063 | Iustin Pop | <varlistentry> |
379 | a8083063 | Iustin Pop | <term>HOST_TYPE</term> |
380 | a8083063 | Iustin Pop | <listitem> |
381 | a8083063 | Iustin Pop | <para>one of <simplelist type="inline"> |
382 | a8083063 | Iustin Pop | <member><constant>MASTER</constant></member> |
383 | a8083063 | Iustin Pop | <member><constant>NODE</constant></member> |
384 | a8083063 | Iustin Pop | </simplelist>, showing the role of this node in the cluster. |
385 | a8083063 | Iustin Pop | </para> |
386 | a8083063 | Iustin Pop | </listitem> |
387 | a8083063 | Iustin Pop | </varlistentry> |
388 | a8083063 | Iustin Pop | --> |
389 | a8083063 | Iustin Pop | </variablelist> |
390 | a8083063 | Iustin Pop | </section> |
391 | a8083063 | Iustin Pop | |
392 | a8083063 | Iustin Pop | <section> |
393 | a8083063 | Iustin Pop | <title>Specialised variables</title> |
394 | a8083063 | Iustin Pop | |
395 | a8083063 | Iustin Pop | <para>This is the list of variables which are specific to one |
396 | a8083063 | Iustin Pop | or more operations.</para> |
397 | a8083063 | Iustin Pop | <variablelist> |
398 | a8083063 | Iustin Pop | <varlistentry> |
399 | a8083063 | Iustin Pop | <term>INSTANCE_NAME</term> |
400 | a8083063 | Iustin Pop | <listitem> |
401 | a8083063 | Iustin Pop | <para>The name of the instance which is the target of |
402 | a8083063 | Iustin Pop | the operation.</para> |
403 | a8083063 | Iustin Pop | </listitem> |
404 | a8083063 | Iustin Pop | </varlistentry> |
405 | a8083063 | Iustin Pop | <varlistentry> |
406 | a8083063 | Iustin Pop | <term>INSTANCE_DISK_TYPE</term> |
407 | a8083063 | Iustin Pop | <listitem> |
408 | a8083063 | Iustin Pop | <para>The disk type for the instance.</para> |
409 | a8083063 | Iustin Pop | </listitem> |
410 | a8083063 | Iustin Pop | </varlistentry> |
411 | a8083063 | Iustin Pop | <varlistentry> |
412 | a8083063 | Iustin Pop | <term>INSTANCE_DISK_SIZE</term> |
413 | a8083063 | Iustin Pop | <listitem> |
414 | a8083063 | Iustin Pop | <para>The (OS) disk size for the instance.</para> |
415 | a8083063 | Iustin Pop | </listitem> |
416 | a8083063 | Iustin Pop | </varlistentry> |
417 | a8083063 | Iustin Pop | <varlistentry> |
418 | a8083063 | Iustin Pop | <term>INSTANCE_OS</term> |
419 | a8083063 | Iustin Pop | <listitem> |
420 | a8083063 | Iustin Pop | <para>The name of the instance OS.</para> |
421 | a8083063 | Iustin Pop | </listitem> |
422 | a8083063 | Iustin Pop | </varlistentry> |
423 | a8083063 | Iustin Pop | <varlistentry> |
424 | a8083063 | Iustin Pop | <term>INSTANCE_PRIMARY</term> |
425 | a8083063 | Iustin Pop | <listitem> |
426 | a8083063 | Iustin Pop | <para>The name of the node which is the primary for the |
427 | a8083063 | Iustin Pop | instance.</para> |
428 | a8083063 | Iustin Pop | </listitem> |
429 | a8083063 | Iustin Pop | </varlistentry> |
430 | a8083063 | Iustin Pop | <varlistentry> |
431 | a8083063 | Iustin Pop | <term>INSTANCE_SECONDARIES</term> |
432 | a8083063 | Iustin Pop | <listitem> |
433 | a8083063 | Iustin Pop | <para>Space-separated list of secondary nodes for the |
434 | a8083063 | Iustin Pop | instance.</para> |
435 | a8083063 | Iustin Pop | </listitem> |
436 | a8083063 | Iustin Pop | </varlistentry> |
437 | a8083063 | Iustin Pop | <varlistentry> |
438 | a8083063 | Iustin Pop | <term>NODE_NAME</term> |
439 | a8083063 | Iustin Pop | <listitem> |
440 | a8083063 | Iustin Pop | <para>The target node of this operation (not the node on |
441 | a8083063 | Iustin Pop | which the hook runs).</para> |
442 | a8083063 | Iustin Pop | </listitem> |
443 | a8083063 | Iustin Pop | </varlistentry> |
444 | a8083063 | Iustin Pop | <varlistentry> |
445 | a8083063 | Iustin Pop | <term>NODE_PIP</term> |
446 | a8083063 | Iustin Pop | <listitem> |
447 | a8083063 | Iustin Pop | <para>The primary IP of the target node (the one over |
448 | a8083063 | Iustin Pop | which inter-node communication is done).</para> |
449 | a8083063 | Iustin Pop | </listitem> |
450 | a8083063 | Iustin Pop | </varlistentry> |
451 | a8083063 | Iustin Pop | <varlistentry> |
452 | a8083063 | Iustin Pop | <term>NODE_SIP</term> |
453 | a8083063 | Iustin Pop | <listitem> |
454 | a8083063 | Iustin Pop | <para>The secondary IP of the target node (the one over |
455 | a8083063 | Iustin Pop | which drbd replication is done). This can be equal to |
456 | a8083063 | Iustin Pop | the primary ip, in case the cluster is not |
457 | a8083063 | Iustin Pop | dual-homed.</para> |
458 | a8083063 | Iustin Pop | </listitem> |
459 | a8083063 | Iustin Pop | </varlistentry> |
460 | a8083063 | Iustin Pop | <varlistentry> |
461 | a8083063 | Iustin Pop | <term>OLD_MASTER</term> |
462 | a8083063 | Iustin Pop | <term>NEW_MASTER</term> |
463 | a8083063 | Iustin Pop | <listitem> |
464 | a8083063 | Iustin Pop | <para>The old, respectively the new master for the |
465 | a8083063 | Iustin Pop | master failover operation.</para> |
466 | a8083063 | Iustin Pop | </listitem> |
467 | a8083063 | Iustin Pop | </varlistentry> |
468 | a8083063 | Iustin Pop | <varlistentry> |
469 | a8083063 | Iustin Pop | <term>FORCE</term> |
470 | a8083063 | Iustin Pop | <listitem> |
471 | a8083063 | Iustin Pop | <para>This is provided by some operations when the user |
472 | a8083063 | Iustin Pop | gave this flag.</para> |
473 | a8083063 | Iustin Pop | </listitem> |
474 | a8083063 | Iustin Pop | </varlistentry> |
475 | a8083063 | Iustin Pop | <varlistentry> |
476 | a8083063 | Iustin Pop | <term>IGNORE_CONSISTENCY</term> |
477 | a8083063 | Iustin Pop | <listitem> |
478 | a8083063 | Iustin Pop | <para>The user has specified this flag. It is used when |
479 | a8083063 | Iustin Pop | failing over instances in case the primary node is |
480 | a8083063 | Iustin Pop | down.</para> |
481 | a8083063 | Iustin Pop | </listitem> |
482 | a8083063 | Iustin Pop | </varlistentry> |
483 | a8083063 | Iustin Pop | <varlistentry> |
484 | a8083063 | Iustin Pop | <term>MEM_SIZE, DISK_SIZE, SWAP_SIZE, VCPUS</term> |
485 | a8083063 | Iustin Pop | <listitem> |
486 | a8083063 | Iustin Pop | <para>The memory, disk, swap size and the number of |
487 | a8083063 | Iustin Pop | processor selected for the instance (in |
488 | a8083063 | Iustin Pop | <command>gnt-instance add</command> or |
489 | a8083063 | Iustin Pop | <command>gnt-instance modify</command>).</para> |
490 | a8083063 | Iustin Pop | </listitem> |
491 | a8083063 | Iustin Pop | </varlistentry> |
492 | a8083063 | Iustin Pop | <varlistentry> |
493 | a8083063 | Iustin Pop | <term>INSTANCE_IP</term> |
494 | a8083063 | Iustin Pop | <listitem> |
495 | a8083063 | Iustin Pop | <para>If defined, the instance IP in the |
496 | a8083063 | Iustin Pop | <command>gnt-instance add</command> and |
497 | a8083063 | Iustin Pop | <command>gnt-instance set</command> commands. If not |
498 | a8083063 | Iustin Pop | defined, it means that no IP has been defined.</para> |
499 | a8083063 | Iustin Pop | </listitem> |
500 | a8083063 | Iustin Pop | </varlistentry> |
501 | a8083063 | Iustin Pop | <varlistentry> |
502 | a8083063 | Iustin Pop | <term>DISK_TEMPLATE</term> |
503 | a8083063 | Iustin Pop | <listitem> |
504 | a8083063 | Iustin Pop | <para>The disk template type when creating the instance.</para> |
505 | a8083063 | Iustin Pop | </listitem> |
506 | a8083063 | Iustin Pop | </varlistentry> |
507 | a8083063 | Iustin Pop | <varlistentry> |
508 | a8083063 | Iustin Pop | <term>INSTANCE_ADD_MODE</term> |
509 | a8083063 | Iustin Pop | <listitem> |
510 | a8083063 | Iustin Pop | <para>The mode of the create: either |
511 | a8083063 | Iustin Pop | <constant>create</constant> for create from scratch or |
512 | a8083063 | Iustin Pop | <constant>import</constant> for restoring from an |
513 | a8083063 | Iustin Pop | exported image.</para> |
514 | a8083063 | Iustin Pop | </listitem> |
515 | a8083063 | Iustin Pop | </varlistentry> |
516 | a8083063 | Iustin Pop | <varlistentry> |
517 | a8083063 | Iustin Pop | <term>SRC_NODE, SRC_PATH, SRC_IMAGE</term> |
518 | a8083063 | Iustin Pop | <listitem> |
519 | a8083063 | Iustin Pop | <para>In case the instance has been added by import, |
520 | a8083063 | Iustin Pop | these variables are defined and point to the source |
521 | a8083063 | Iustin Pop | node, source path (the directory containing the image |
522 | a8083063 | Iustin Pop | and the config file) and the source disk image |
523 | a8083063 | Iustin Pop | file.</para> |
524 | a8083063 | Iustin Pop | </listitem> |
525 | a8083063 | Iustin Pop | </varlistentry> |
526 | a8083063 | Iustin Pop | <varlistentry> |
527 | a8083063 | Iustin Pop | <term>DISK_NAME</term> |
528 | a8083063 | Iustin Pop | <listitem> |
529 | a8083063 | Iustin Pop | <para>The disk name (either <filename>sda</filename> or |
530 | a8083063 | Iustin Pop | <filename>sdb</filename>) in mirror operations |
531 | a8083063 | Iustin Pop | (add/remove mirror).</para> |
532 | a8083063 | Iustin Pop | </listitem> |
533 | a8083063 | Iustin Pop | </varlistentry> |
534 | a8083063 | Iustin Pop | <varlistentry> |
535 | a8083063 | Iustin Pop | <term>DISK_ID</term> |
536 | a8083063 | Iustin Pop | <listitem> |
537 | a8083063 | Iustin Pop | <para>The disk id for mirror remove operations. You can |
538 | a8083063 | Iustin Pop | look this up using <command>gnt-instance |
539 | a8083063 | Iustin Pop | info</command>.</para> |
540 | a8083063 | Iustin Pop | </listitem> |
541 | a8083063 | Iustin Pop | </varlistentry> |
542 | a8083063 | Iustin Pop | <varlistentry> |
543 | a8083063 | Iustin Pop | <term>NEW_SECONDARY</term> |
544 | a8083063 | Iustin Pop | <listitem> |
545 | a8083063 | Iustin Pop | <para>The name of the node on which the new mirror |
546 | a8083063 | Iustin Pop | componet is being added. This can be the name of the |
547 | a8083063 | Iustin Pop | current secondary, if the new mirror is on the same |
548 | a8083063 | Iustin Pop | secondary.</para> |
549 | a8083063 | Iustin Pop | </listitem> |
550 | a8083063 | Iustin Pop | </varlistentry> |
551 | a8083063 | Iustin Pop | <varlistentry> |
552 | a8083063 | Iustin Pop | <term>OLD_SECONDARY</term> |
553 | a8083063 | Iustin Pop | <listitem> |
554 | a8083063 | Iustin Pop | <para>The name of the old secondary. This is used in |
555 | a8083063 | Iustin Pop | both <command>replace-disks</command> and |
556 | a8083063 | Iustin Pop | <command>remove-mirror</command>. Note that this can be |
557 | a8083063 | Iustin Pop | equal to the new secondary (only |
558 | a8083063 | Iustin Pop | <command>replace-disks</command> has both variables) if |
559 | a8083063 | Iustin Pop | the secondary node hasn't actually changed).</para> |
560 | a8083063 | Iustin Pop | </listitem> |
561 | a8083063 | Iustin Pop | </varlistentry> |
562 | a8083063 | Iustin Pop | <varlistentry> |
563 | a8083063 | Iustin Pop | <term>EXPORT_NODE</term> |
564 | a8083063 | Iustin Pop | <listitem> |
565 | a8083063 | Iustin Pop | <para>The node on which the exported image of the |
566 | a8083063 | Iustin Pop | instance was done.</para> |
567 | a8083063 | Iustin Pop | </listitem> |
568 | a8083063 | Iustin Pop | </varlistentry> |
569 | a8083063 | Iustin Pop | <varlistentry> |
570 | a8083063 | Iustin Pop | <term>EXPORT_DO_SHUTDOWN</term> |
571 | a8083063 | Iustin Pop | <listitem> |
572 | a8083063 | Iustin Pop | <para>This variable tells if the instance has been |
573 | a8083063 | Iustin Pop | shutdown or not while doing the export. In the "was |
574 | a8083063 | Iustin Pop | shutdown" case, it's likely that the filesystem is |
575 | a8083063 | Iustin Pop | consistent, whereas in the "did not shutdown" case, the |
576 | a8083063 | Iustin Pop | filesystem would need a check (journal replay or full |
577 | a8083063 | Iustin Pop | fsck) in order to guarantee consistency.</para> |
578 | a8083063 | Iustin Pop | </listitem> |
579 | a8083063 | Iustin Pop | </varlistentry> |
580 | a8083063 | Iustin Pop | </variablelist> |
581 | a8083063 | Iustin Pop | |
582 | a8083063 | Iustin Pop | </section> |
583 | a8083063 | Iustin Pop | |
584 | a8083063 | Iustin Pop | </section> |
585 | a8083063 | Iustin Pop | |
586 | a8083063 | Iustin Pop | </section> |
587 | a8083063 | Iustin Pop | </article> |