2 |
2 |
|
3 |
3 |
<!-- Fill in your name for FIRSTNAME and SURNAME. -->
|
4 |
4 |
<!-- Please adjust the date whenever revising the manpage. -->
|
5 |
|
<!ENTITY dhdate "<date>June 20, 2007</date>">
|
|
5 |
<!ENTITY dhdate "<date>February 02, 2009</date>">
|
6 |
6 |
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
|
7 |
7 |
allowed: see man(7), man(1). -->
|
8 |
8 |
<!ENTITY dhsection "<manvolnum>7</manvolnum>">
|
... | ... | |
20 |
20 |
<copyright>
|
21 |
21 |
<year>2006</year>
|
22 |
22 |
<year>2007</year>
|
|
23 |
<year>2008</year>
|
|
24 |
<year>2009</year>
|
23 |
25 |
<holder>Google Inc.</holder>
|
24 |
26 |
</copyright>
|
25 |
27 |
&dhdate;
|
... | ... | |
28 |
30 |
&dhucpackage;
|
29 |
31 |
|
30 |
32 |
&dhsection;
|
31 |
|
<refmiscinfo>ganeti 1.2</refmiscinfo>
|
|
33 |
<refmiscinfo>ganeti 2.0</refmiscinfo>
|
32 |
34 |
</refmeta>
|
33 |
35 |
<refnamediv>
|
34 |
36 |
<refname>ganeti-os-interface</refname>
|
... | ... | |
60 |
62 |
</para>
|
61 |
63 |
|
62 |
64 |
<refsect2>
|
|
65 |
<title>Common environment</title>
|
|
66 |
<para>
|
|
67 |
All commands will get their input via environment variables. A
|
|
68 |
common set of variables will be exported for all commands, and
|
|
69 |
some of them might have extra ones. Note that all counts are
|
|
70 |
zero-based.
|
|
71 |
</para>
|
|
72 |
<variablelist>
|
|
73 |
<varlistentry>
|
|
74 |
<term>OS_API_VERSION</term>
|
|
75 |
<listitem>
|
|
76 |
<simpara>The OS api version that the rest of the
|
|
77 |
environment conforms to.</simpara>
|
|
78 |
</listitem>
|
|
79 |
</varlistentry>
|
|
80 |
<varlistentry>
|
|
81 |
<term>INSTANCE_NAME</term>
|
|
82 |
<listitem>
|
|
83 |
<simpara>The instance name the script should operate
|
|
84 |
on.</simpara>
|
|
85 |
</listitem>
|
|
86 |
</varlistentry>
|
|
87 |
<varlistentry>
|
|
88 |
<term>INSTANCE_OS</term>
|
|
89 |
<listitem>
|
|
90 |
<simpara>The name os the instance's OS as Ganeti knows
|
|
91 |
it. This can simplify the OS scripts by providing the same
|
|
92 |
scripts under multiple names, and then the scripts can use
|
|
93 |
this name to alter their behaviour.</simpara>
|
|
94 |
</listitem>
|
|
95 |
</varlistentry>
|
|
96 |
<varlistentry>
|
|
97 |
<term>HYPERVISOR</term>
|
|
98 |
<listitem>
|
|
99 |
<simpara>The hypervisor of this instance.</simpara>
|
|
100 |
</listitem>
|
|
101 |
</varlistentry>
|
|
102 |
<varlistentry>
|
|
103 |
<term>DISK_COUNT</term>
|
|
104 |
<listitem>
|
|
105 |
<simpara>The number of disks the instance has. The actual
|
|
106 |
disk defitions are in a set of additional variables. The
|
|
107 |
instance's disk will be numbered from 0 to this value
|
|
108 |
minus one.</simpara>
|
|
109 |
</listitem>
|
|
110 |
</varlistentry>
|
|
111 |
<varlistentry>
|
|
112 |
<term>DISK_%N_PATH</term>
|
|
113 |
<listitem>
|
|
114 |
<simpara>The path to the storage for disk N of the
|
|
115 |
instance. This might be either a block device or a regular
|
|
116 |
file, in which case the OS scripts should use
|
|
117 |
<emphasis>losetup</emphasis> (if they need to mount
|
|
118 |
it). E.g. the first disk of the instance might be exported
|
|
119 |
as <envar>DISK_0_PATH=/dev/drbd0</envar>.</simpara>
|
|
120 |
</listitem>
|
|
121 |
</varlistentry>
|
|
122 |
<varlistentry>
|
|
123 |
<term>DISK_%N_ACCESS</term>
|
|
124 |
<listitem>
|
|
125 |
<simpara>This is how the hypervisor will export the
|
|
126 |
instance disks: either read-write (<emphasis>rw</emphasis>) or
|
|
127 |
read-only (<emphasis>ro</emphasis>).</simpara>
|
|
128 |
</listitem>
|
|
129 |
</varlistentry>
|
|
130 |
<varlistentry>
|
|
131 |
<term>DISK_%N_FRONTEND_TYPE</term>
|
|
132 |
<listitem>
|
|
133 |
<simpara>(Optional) If applicable to the current
|
|
134 |
hypervisor type: the type of the device exported by the
|
|
135 |
hypervisor. For example, the Xen HVM hypervisor can export
|
|
136 |
disks as either <emphasis>paravirtual</emphasis> or
|
|
137 |
<emphasis>ioemu</emphasis>.</simpara>
|
|
138 |
</listitem>
|
|
139 |
</varlistentry>
|
|
140 |
<varlistentry>
|
|
141 |
<term>DISK_%N_BACKEND_TYPE</term>
|
|
142 |
<listitem>
|
|
143 |
<simpara>How files are visible on the node side. This can
|
|
144 |
be either <emphasis>block</emphasis> (when using block
|
|
145 |
devices) or <emphasis>file:type</emphasis>, where
|
|
146 |
<emphasis>type</emphasis> is either
|
|
147 |
<emphasis>loop</emphasis> <emphasis>blktap</emphasis>
|
|
148 |
depending on how the hypervisor will be configured. Note
|
|
149 |
that not all backend types apply to all
|
|
150 |
hypervisors.</simpara>
|
|
151 |
</listitem>
|
|
152 |
</varlistentry>
|
|
153 |
<varlistentry>
|
|
154 |
<term>NIC_COUNT</term>
|
|
155 |
<listitem>
|
|
156 |
<simpara>Similar to the <envar>DISK_COUNT</envar>, this
|
|
157 |
represents the number of NICs of the instance.</simpara>
|
|
158 |
</listitem>
|
|
159 |
</varlistentry>
|
|
160 |
<varlistentry>
|
|
161 |
<term>NIC_%N_MAC</term>
|
|
162 |
<listitem>
|
|
163 |
<simpara>The MAC address associated with this
|
|
164 |
interface.</simpara>
|
|
165 |
</listitem>
|
|
166 |
</varlistentry>
|
|
167 |
<varlistentry>
|
|
168 |
<term>NIC_%N_IP</term>
|
|
169 |
<listitem>
|
|
170 |
<simpara>The IP address, if any, associated with the N-th
|
|
171 |
NIC of the instance.</simpara>
|
|
172 |
</listitem>
|
|
173 |
</varlistentry>
|
|
174 |
<varlistentry>
|
|
175 |
<term>NIC_%N_BRIDGE</term>
|
|
176 |
<listitem>
|
|
177 |
<simpara>The bridge to which this NIC will be attached
|
|
178 |
to.</simpara>
|
|
179 |
</listitem>
|
|
180 |
</varlistentry>
|
|
181 |
<varlistentry>
|
|
182 |
<term>NIC_%N_FRONTEND_TYPE</term>
|
|
183 |
<listitem>
|
|
184 |
<para>(Optional) If applicable, the type of the exported
|
|
185 |
NIC to the instance, this can be one of of: <simplelist
|
|
186 |
type="inline"> <member>rtl8139</member>
|
|
187 |
<member>ne2k_pci</member> <member>ne2k_isa</member>
|
|
188 |
<member>paravirtual</member> </simplelist>.
|
|
189 |
</para>
|
|
190 |
</listitem>
|
|
191 |
</varlistentry>
|
|
192 |
<varlistentry>
|
|
193 |
<term>DEBUG_LEVEL</term>
|
|
194 |
<listitem>
|
|
195 |
<simpara>If non-zero, this should cause the OS script to
|
|
196 |
generate verbose logs of its execution, for
|
|
197 |
troubleshooting purposes. Currently only
|
|
198 |
<emphasis>0</emphasis> and <emphasis>1</emphasis> are
|
|
199 |
valid values.</simpara>
|
|
200 |
</listitem>
|
|
201 |
</varlistentry>
|
|
202 |
</variablelist>
|
|
203 |
</refsect2>
|
|
204 |
|
|
205 |
<refsect2>
|
63 |
206 |
<title>create</title>
|
64 |
|
<cmdsynopsis>
|
65 |
|
<command>create</command>
|
66 |
|
<arg choice="req">-i <replaceable>instance_name</replaceable></arg>
|
67 |
|
<arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
|
68 |
|
<arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>
|
69 |
|
</cmdsynopsis>
|
70 |
207 |
|
71 |
208 |
<para>The <command>create</command> command is used for creating
|
72 |
|
a new instance from scratch.</para>
|
|
209 |
a new instance from scratch. It has no additional environment
|
|
210 |
variables bside the common ones.</para>
|
73 |
211 |
|
74 |
|
<para>The argument to the <option>-i</option> option is the FQDN
|
|
212 |
<para>The <envar>INSTANCE_NAME</envar> variable denotes the name
|
75 |
213 |
of the instance, which is guaranteed to resolve to an IP
|
76 |
214 |
address. The create script should configure the instance
|
77 |
215 |
according to this name. It can configure the IP statically or
|
78 |
216 |
not, depending on the deployment environment.</para>
|
79 |
217 |
|
80 |
|
<para>The <option>-b</option> and <option>-s</option> options
|
81 |
|
denote the block devices which will be visible in the instance
|
82 |
|
as <emphasis>sda</emphasis> and <emphasis>sdb</emphasis>. The
|
83 |
|
<emphasis>sda</emphasis> block device should be used for the
|
84 |
|
root disk (and will be passed as the root device for Linux
|
85 |
|
kernels). The <emphasis>sdb</emphasis> device should be setup
|
86 |
|
for swap usage.</para>
|
87 |
|
|
88 |
218 |
</refsect2>
|
89 |
219 |
|
90 |
220 |
<refsect2>
|
91 |
|
<title>import</title>
|
92 |
|
<cmdsynopsis>
|
93 |
|
<command>import</command>
|
94 |
|
<arg choice="req">-i <replaceable>instance_name</replaceable></arg>
|
95 |
|
<arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
|
96 |
|
<arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>
|
97 |
|
</cmdsynopsis>
|
|
221 |
<title>export</title>
|
98 |
222 |
|
99 |
223 |
<para>
|
100 |
|
The <command>import</command> command is used for restoring an
|
101 |
|
instance from a backup as done by
|
102 |
|
<command>export</command>. The arguments are the same as for
|
103 |
|
<command>create</command> and the output of the
|
104 |
|
<command>export</command> will be provided on
|
105 |
|
<acronym>stdin</acronym>.
|
|
224 |
This command is used in order to make a backup of a given disk
|
|
225 |
of the instance. The command should write to stdout a dump of
|
|
226 |
the given block device. The output of this program will be
|
|
227 |
passed during restore to the <command>import</command>
|
|
228 |
command.
|
|
229 |
</para>
|
|
230 |
|
|
231 |
<para>
|
|
232 |
The specific disk to backup is denoted by two additional
|
|
233 |
environment variables: <envar>EXPORT_INDEX</envar> which
|
|
234 |
denotes the index in the instance disks structure (and could
|
|
235 |
be used for example to skip the second disk if not needed for
|
|
236 |
backup) and <envar>EXPORT_PATH</envar> which has the same
|
|
237 |
value as <emphasis>DISK_N_PATH</emphasis> but is duplicate
|
|
238 |
here for easier usage by shell scripts (rather than parse the
|
|
239 |
DISK_... variables).
|
106 |
240 |
</para>
|
107 |
241 |
|
108 |
242 |
</refsect2>
|
109 |
243 |
|
110 |
244 |
<refsect2>
|
111 |
|
<title>export</title>
|
112 |
|
<cmdsynopsis>
|
113 |
|
<command>export</command>
|
114 |
|
<arg choice="req">-i <replaceable>instance_name</replaceable></arg>
|
115 |
|
<arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
|
116 |
|
</cmdsynopsis>
|
|
245 |
<title>import</title>
|
117 |
246 |
|
118 |
247 |
<para>
|
119 |
|
This command is used in order to make a backup of the
|
120 |
|
instance. The command should write to stdout a dump of the
|
121 |
|
given block device. The output of this program will be passed
|
122 |
|
to the <command>import</command> command.
|
|
248 |
The <command>import</command> command is used for restoring an
|
|
249 |
instance from a backup as done by
|
|
250 |
<command>export</command>. The arguments are the similar to
|
|
251 |
those passed to <command>export</command>, whose output will
|
|
252 |
be provided on <acronym>stdin</acronym>.
|
123 |
253 |
</para>
|
124 |
254 |
|
125 |
255 |
<para>
|
126 |
|
The options have the same meaning as for
|
127 |
|
<command>create</command> and <command>import</command>, with
|
128 |
|
the exception that the argument to <option>-i</option> denotes
|
129 |
|
an existing instance.
|
|
256 |
The difference in variables is that the current disk is called
|
|
257 |
by <envar>IMPORT_DEVICE</envar> and <envar>IMPORT_IDX</envar>
|
|
258 |
(instead of <emphasis>EXPORT_</emphasis>).
|
130 |
259 |
</para>
|
131 |
260 |
|
132 |
261 |
</refsect2>
|
133 |
262 |
|
134 |
263 |
<refsect2>
|
135 |
264 |
<title>rename</title>
|
136 |
|
<cmdsynopsis>
|
137 |
|
<command>rename</command>
|
138 |
|
<arg choice="req">-o <replaceable>old_name</replaceable></arg>
|
139 |
|
<arg choice="req">-n <replaceable>new_name</replaceable></arg>
|
140 |
|
<arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
|
141 |
|
<arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>
|
142 |
|
</cmdsynopsis>
|
143 |
265 |
|
144 |
266 |
<para>
|
145 |
267 |
This command is used in order to perform a rename at the
|
... | ... | |
157 |
279 |
instance.
|
158 |
280 |
</para>
|
159 |
281 |
|
|
282 |
<para>The script will be passed one additional environment
|
|
283 |
variable called <envar>OLD_INSTANCE_NAME</envar> which holds the
|
|
284 |
old instance name. The <envar>INSTANCE_NAME</envar> variable
|
|
285 |
holds the new instance name.</para>
|
|
286 |
|
160 |
287 |
<para>
|
161 |
288 |
A very simple rename script should at least change the
|
162 |
289 |
hostname and IP address of the instance, leaving the
|
... | ... | |
168 |
295 |
<title>ganeti_api_version</title>
|
169 |
296 |
<para>
|
170 |
297 |
The <filename>ganeti_api_version</filename> file is a plain
|
171 |
|
text file containing the version of the guest OS api that this
|
172 |
|
OS definition complies with. The version documented by this
|
173 |
|
man page is 5, so this file must contain the number 5 followed
|
174 |
|
by a newline.
|
|
298 |
text file containing the version(s) of the guest OS api that
|
|
299 |
this OS definition complies with, one per line. The version
|
|
300 |
documented by this man page is 10, so this file must contain
|
|
301 |
the number 10 followed by a newline if only this version is
|
|
302 |
supported. A script compatible with both Ganeti 1.2 and Ganeti
|
|
303 |
2.0 should contain the most recent version first (i.e. 10),
|
|
304 |
followed by the old version(s) (in this case, 5).
|
175 |
305 |
</para>
|
176 |
306 |
</refsect2>
|
177 |
307 |
|
... | ... | |
183 |
313 |
<refsect2>
|
184 |
314 |
<title>Common behaviour</title>
|
185 |
315 |
|
186 |
|
<para>All the scripts should display an usage message when called with a wrong number of arguments or when the first argument is <option>-h</option> or <option>--help</option>.</para>
|
|
316 |
<para>All the scripts should display an usage message when
|
|
317 |
called with a wrong number of arguments or when the first
|
|
318 |
argument is <option>-h</option> or
|
|
319 |
<option>--help</option>.</para>
|
187 |
320 |
|
188 |
321 |
</refsect2>
|
189 |
322 |
|
190 |
323 |
<refsect2>
|
191 |
324 |
<title>Upgrading from old versions</title>
|
192 |
325 |
<refsect3>
|
|
326 |
<title>Version 5 to 10</title>
|
|
327 |
|
|
328 |
<para>
|
|
329 |
The method os passing data has changed from command line
|
|
330 |
options to environment variables, so scripts should be
|
|
331 |
modified to use these. For an example of how this can be
|
|
332 |
done in a way compatible with both versions, feel free to
|
|
333 |
look at the debootstrap instance's
|
|
334 |
<filename>common.sh</filename> auxiliary script.
|
|
335 |
</para>
|
|
336 |
|
|
337 |
<para>
|
|
338 |
Also, instances can have now a variable number of disks, not
|
|
339 |
only two, and a variable number of NICs (instead of fixed
|
|
340 |
one), so the scripts should deal with this. The biggest
|
|
341 |
change is in the import/export, which are called once per
|
|
342 |
disk, instead of once per instance.
|
|
343 |
</para>
|
|
344 |
|
|
345 |
</refsect3>
|
|
346 |
|
|
347 |
<refsect3>
|
193 |
348 |
<title>Version 4 to 5</title>
|
194 |
349 |
<para>
|
195 |
350 |
The <filename>rename</filename> script has been added. If
|