1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
3 <!-- Fill in your name for FIRSTNAME and SURNAME. -->
4 <!-- Please adjust the date whenever revising the manpage. -->
5 <!ENTITY dhdate "<date>June 20, 2007</date>">
6 <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
7 allowed: see man(7), man(1). -->
8 <!ENTITY dhsection "<manvolnum>7</manvolnum>">
9 <!ENTITY dhucpackage "<refentrytitle>ganeti-os-interface</refentrytitle>">
10 <!ENTITY dhpackage "ganeti">
12 <!ENTITY debian "<productname>Debian</productname>">
13 <!ENTITY gnu "<acronym>GNU</acronym>">
14 <!ENTITY gpl "&gnu; <acronym>GPL</acronym>">
15 <!ENTITY footer SYSTEM "footer.sgml">
23 <holder>Google Inc.</holder>
31 <refmiscinfo>ganeti 1.2</refmiscinfo>
34 <refname>ganeti-os-interface</refname>
36 <refpurpose>specifications for guest OS types
42 <title>DESCRIPTION</title>
45 The method of supporting guest operating systems in Ganeti is to
46 have, for each guest OS type, a directory containing a number of
53 <title>REFERENCE</title>
56 There are five required files: <filename>create</filename>,
57 <filename>import</filename>, <filename>export</filename>,
58 <filename>rename</filename> (executables) and
59 <filename>ganeti_api_version</filename> (text file).
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>
71 <para>The <command>create</command> command is used for creating
72 a new instance from scratch.</para>
74 <para>The argument to the <option>-i</option> option is the FQDN
75 of the instance, which is guaranteed to resolve to an IP
76 address. The create script should configure the instance
77 according to this name. It can configure the IP statically or
78 not, depending on the deployment environment.</para>
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>
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>
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>.
111 <title>export</title>
113 <command>export</command>
114 <arg choice="req">-i <replaceable>instance_name</replaceable></arg>
115 <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
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.
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.
135 <title>rename</title>
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>
145 This command is used in order to perform a rename at the
146 instance OS level, after the instance has been renamed in
147 Ganeti. The command should do whatever steps are required to
148 ensure that the instance is updated to use the new name, if
149 the operating system supports it.
153 Note that it is acceptable for the rename script to do nothing
154 at all, however be warned that in this case, there will be a
155 desynchronization between what <computeroutput>gnt-instance
156 list</computeroutput> shows you and the actual hostname of the
161 A very simple rename script should at least change the
162 hostname and IP address of the instance, leaving the
163 administrator to update the other services.
168 <title>ganeti_api_version</title>
170 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
184 <title>Common behaviour</title>
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>
191 <title>Upgrading from old versions</title>
193 <title>Version 4 to 5</title>
195 The <filename>rename</filename> script has been added. If
196 you don't want to do any changes on the instances after a
197 rename, you can migrate the OS definition to version 5 by
198 creating the <filename>rename</filename> script simply as:
206 <para>Note that the script must be executable.</para>
213 <title>Export/import format</title>
216 It is up to the export and import scripts to define the format
217 they use. It is only required for these two to work
218 together. It is not recommended that
230 <!-- Keep this comment at the end of the file
235 sgml-minimize-attributes:nil
236 sgml-always-quote-attributes:t
239 sgml-parent-document:nil
240 sgml-default-dtd-file:nil
241 sgml-exposed-tags:nil
242 sgml-local-catalogs:nil
243 sgml-local-ecat-files:nil