Revision 216842d7 man/ganeti-os-interface.sgml
| b/man/ganeti-os-interface.sgml | ||
|---|---|---|
| 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 |
Also available in: Unified diff