Statistics
| Branch: | Tag: | Revision:

root / man / ganeti-os-interface.sgml @ 20e23543

History | View | Annotate | Download (7.5 kB)

1 a8083063 Iustin Pop
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2 a8083063 Iustin Pop
3 a8083063 Iustin Pop
  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
4 a8083063 Iustin Pop
  <!-- Please adjust the date whenever revising the manpage. -->
5 a8083063 Iustin Pop
  <!ENTITY dhdate      "<date>June 20, 2007</date>">
6 a8083063 Iustin Pop
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
7 a8083063 Iustin Pop
       allowed: see man(7), man(1). -->
8 a8083063 Iustin Pop
  <!ENTITY dhsection   "<manvolnum>7</manvolnum>">
9 a8083063 Iustin Pop
  <!ENTITY dhucpackage "<refentrytitle>ganeti-os-interface</refentrytitle>">
10 a8083063 Iustin Pop
  <!ENTITY dhpackage   "ganeti">
11 a8083063 Iustin Pop
12 a8083063 Iustin Pop
  <!ENTITY debian      "<productname>Debian</productname>">
13 a8083063 Iustin Pop
  <!ENTITY gnu         "<acronym>GNU</acronym>">
14 a8083063 Iustin Pop
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
15 a8083063 Iustin Pop
  <!ENTITY footer SYSTEM "footer.sgml">
16 a8083063 Iustin Pop
]>
17 a8083063 Iustin Pop
18 a8083063 Iustin Pop
<refentry>
19 a8083063 Iustin Pop
  <refentryinfo>
20 a8083063 Iustin Pop
    <copyright>
21 a8083063 Iustin Pop
      <year>2006</year>
22 a8083063 Iustin Pop
      <year>2007</year>
23 a8083063 Iustin Pop
      <holder>Google Inc.</holder>
24 a8083063 Iustin Pop
    </copyright>
25 a8083063 Iustin Pop
    &dhdate;
26 a8083063 Iustin Pop
  </refentryinfo>
27 a8083063 Iustin Pop
  <refmeta>
28 a8083063 Iustin Pop
    &dhucpackage;
29 a8083063 Iustin Pop
30 a8083063 Iustin Pop
    &dhsection;
31 a8083063 Iustin Pop
    <refmiscinfo>ganeti 1.2</refmiscinfo>
32 a8083063 Iustin Pop
  </refmeta>
33 a8083063 Iustin Pop
  <refnamediv>
34 037da795 Guido Trotter
    <refname>ganeti-os-interface</refname>
35 a8083063 Iustin Pop
36 a8083063 Iustin Pop
    <refpurpose>specifications for guest OS types
37 a8083063 Iustin Pop
    </refpurpose>
38 a8083063 Iustin Pop
39 a8083063 Iustin Pop
  </refnamediv>
40 a8083063 Iustin Pop
41 a8083063 Iustin Pop
  <refsect1>
42 a8083063 Iustin Pop
    <title>DESCRIPTION</title>
43 a8083063 Iustin Pop
44 a8083063 Iustin Pop
    <para>
45 a8083063 Iustin Pop
      The method of supporting guest operating systems in Ganeti is to
46 a8083063 Iustin Pop
      have, for each guest OS type, a directory containing a number of
47 a8083063 Iustin Pop
      required files.
48 a8083063 Iustin Pop
    </para>
49 a8083063 Iustin Pop
50 a8083063 Iustin Pop
51 a8083063 Iustin Pop
  </refsect1>
52 a8083063 Iustin Pop
  <refsect1>
53 a8083063 Iustin Pop
    <title>REFERENCE</title>
54 a8083063 Iustin Pop
55 a8083063 Iustin Pop
    <para>
56 386b57af Iustin Pop
      There are five required files: <filename>create</filename>,
57 386b57af Iustin Pop
      <filename>import</filename>, <filename>export</filename>,
58 386b57af Iustin Pop
      <filename>rename</filename> (executables) and
59 386b57af Iustin Pop
      <filename>ganeti_api_version</filename> (text file).
60 a8083063 Iustin Pop
    </para>
61 a8083063 Iustin Pop
62 a8083063 Iustin Pop
    <refsect2>
63 a8083063 Iustin Pop
      <title>create</title>
64 a8083063 Iustin Pop
      <cmdsynopsis>
65 a8083063 Iustin Pop
        <command>create</command>
66 a8083063 Iustin Pop
        <arg choice="req">-i <replaceable>instance_name</replaceable></arg>
67 a8083063 Iustin Pop
        <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
68 a8083063 Iustin Pop
        <arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>
69 a8083063 Iustin Pop
      </cmdsynopsis>
70 a8083063 Iustin Pop
71 a8083063 Iustin Pop
      <para>The <command>create</command> command is used for creating
72 a8083063 Iustin Pop
      a new instance from scratch.</para>
73 a8083063 Iustin Pop
74 a8083063 Iustin Pop
      <para>The argument to the <option>-i</option> option is the FQDN
75 a8083063 Iustin Pop
      of the instance, which is guaranteed to resolve to an IP
76 a8083063 Iustin Pop
      address. The create script should configure the instance
77 a8083063 Iustin Pop
      according to this name. It can configure the IP statically or
78 a8083063 Iustin Pop
      not, depending on the deployment environment.</para>
79 a8083063 Iustin Pop
80 a8083063 Iustin Pop
      <para>The <option>-b</option> and <option>-s</option> options
81 a8083063 Iustin Pop
      denote the block devices which will be visible in the instance
82 a8083063 Iustin Pop
      as <emphasis>sda</emphasis> and <emphasis>sdb</emphasis>. The
83 a8083063 Iustin Pop
      <emphasis>sda</emphasis> block device should be used for the
84 386b57af Iustin Pop
      root disk (and will be passed as the root device for Linux
85 a8083063 Iustin Pop
      kernels). The <emphasis>sdb</emphasis> device should be setup
86 a8083063 Iustin Pop
      for swap usage.</para>
87 a8083063 Iustin Pop
88 a8083063 Iustin Pop
    </refsect2>
89 a8083063 Iustin Pop
90 a8083063 Iustin Pop
    <refsect2>
91 a8083063 Iustin Pop
      <title>import</title>
92 a8083063 Iustin Pop
      <cmdsynopsis>
93 a8083063 Iustin Pop
        <command>import</command>
94 a8083063 Iustin Pop
        <arg choice="req">-i <replaceable>instance_name</replaceable></arg>
95 a8083063 Iustin Pop
        <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
96 a8083063 Iustin Pop
        <arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>
97 a8083063 Iustin Pop
      </cmdsynopsis>
98 a8083063 Iustin Pop
99 a8083063 Iustin Pop
      <para>
100 a8083063 Iustin Pop
        The <command>import</command> command is used for restoring an
101 a8083063 Iustin Pop
        instance from a backup as done by
102 a8083063 Iustin Pop
        <command>export</command>. The arguments are the same as for
103 a8083063 Iustin Pop
        <command>create</command> and the output of the
104 a8083063 Iustin Pop
        <command>export</command> will be provided on
105 a8083063 Iustin Pop
        <acronym>stdin</acronym>.
106 a8083063 Iustin Pop
      </para>
107 a8083063 Iustin Pop
108 a8083063 Iustin Pop
    </refsect2>
109 a8083063 Iustin Pop
110 a8083063 Iustin Pop
    <refsect2>
111 a8083063 Iustin Pop
      <title>export</title>
112 a8083063 Iustin Pop
      <cmdsynopsis>
113 a8083063 Iustin Pop
        <command>export</command>
114 a8083063 Iustin Pop
        <arg choice="req">-i <replaceable>instance_name</replaceable></arg>
115 a8083063 Iustin Pop
        <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
116 a8083063 Iustin Pop
      </cmdsynopsis>
117 a8083063 Iustin Pop
118 a8083063 Iustin Pop
      <para>
119 a8083063 Iustin Pop
        This command is used in order to make a backup of the
120 a8083063 Iustin Pop
        instance. The command should write to stdout a dump of the
121 a8083063 Iustin Pop
        given block device. The output of this program will be passed
122 a8083063 Iustin Pop
        to the <command>import</command> command.
123 a8083063 Iustin Pop
      </para>
124 a8083063 Iustin Pop
125 a8083063 Iustin Pop
      <para>
126 a8083063 Iustin Pop
        The options have the same meaning as for
127 a8083063 Iustin Pop
        <command>create</command> and <command>import</command>, with
128 a8083063 Iustin Pop
        the exception that the argument to <option>-i</option> denotes
129 a8083063 Iustin Pop
        an existing instance.
130 a8083063 Iustin Pop
      </para>
131 a8083063 Iustin Pop
132 a8083063 Iustin Pop
    </refsect2>
133 a8083063 Iustin Pop
134 a8083063 Iustin Pop
    <refsect2>
135 386b57af Iustin Pop
      <title>rename</title>
136 386b57af Iustin Pop
      <cmdsynopsis>
137 386b57af Iustin Pop
        <command>rename</command>
138 386b57af Iustin Pop
        <arg choice="req">-o <replaceable>old_name</replaceable></arg>
139 386b57af Iustin Pop
        <arg choice="req">-n <replaceable>new_name</replaceable></arg>
140 386b57af Iustin Pop
        <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
141 386b57af Iustin Pop
        <arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>
142 386b57af Iustin Pop
      </cmdsynopsis>
143 386b57af Iustin Pop
144 386b57af Iustin Pop
      <para>
145 386b57af Iustin Pop
        This command is used in order to perform a rename at the
146 386b57af Iustin Pop
        instance OS level, after the instance has been renamed in
147 386b57af Iustin Pop
        Ganeti. The command should do whatever steps are required to
148 386b57af Iustin Pop
        ensure that the instance is updated to use the new name, if
149 386b57af Iustin Pop
        the operating system supports it.
150 386b57af Iustin Pop
      </para>
151 386b57af Iustin Pop
152 386b57af Iustin Pop
      <para>
153 386b57af Iustin Pop
        Note that it is acceptable for the rename script to do nothing
154 386b57af Iustin Pop
        at all, however be warned that in this case, there will be a
155 386b57af Iustin Pop
        desynchronization between what <computeroutput>gnt-instance
156 386b57af Iustin Pop
        list</computeroutput> shows you and the actual hostname of the
157 386b57af Iustin Pop
        instance.
158 386b57af Iustin Pop
      </para>
159 386b57af Iustin Pop
160 386b57af Iustin Pop
      <para>
161 386b57af Iustin Pop
        A very simple rename script should at least change the
162 386b57af Iustin Pop
        hostname and IP address of the instance, leaving the
163 386b57af Iustin Pop
        administrator to update the other services.
164 386b57af Iustin Pop
      </para>
165 386b57af Iustin Pop
    </refsect2>
166 386b57af Iustin Pop
167 386b57af Iustin Pop
    <refsect2>
168 a8083063 Iustin Pop
      <title>ganeti_api_version</title>
169 a8083063 Iustin Pop
      <para>
170 a8083063 Iustin Pop
        The <filename>ganeti_api_version</filename> file is a plain
171 a8083063 Iustin Pop
        text file containing the version of the guest OS api that this
172 a8083063 Iustin Pop
        OS definition complies with. The version documented by this
173 386b57af Iustin Pop
        man page is 5, so this file must contain the number 5 followed
174 386b57af Iustin Pop
        by a newline.
175 a8083063 Iustin Pop
      </para>
176 a8083063 Iustin Pop
    </refsect2>
177 a8083063 Iustin Pop
178 a8083063 Iustin Pop
  </refsect1>
179 a8083063 Iustin Pop
180 a8083063 Iustin Pop
  <refsect1>
181 a8083063 Iustin Pop
    <title>NOTES</title>
182 a8083063 Iustin Pop
183 a8083063 Iustin Pop
    <refsect2>
184 a8083063 Iustin Pop
      <title>Common behaviour</title>
185 a8083063 Iustin Pop
186 a8083063 Iustin Pop
      <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>
187 a8083063 Iustin Pop
188 a8083063 Iustin Pop
    </refsect2>
189 a8083063 Iustin Pop
190 386b57af Iustin Pop
    <refsect2>
191 386b57af Iustin Pop
      <title>Upgrading from old versions</title>
192 386b57af Iustin Pop
      <refsect3>
193 386b57af Iustin Pop
        <title>Version 4 to 5</title>
194 386b57af Iustin Pop
        <para>
195 386b57af Iustin Pop
          The <filename>rename</filename> script has been added. If
196 386b57af Iustin Pop
          you don't want to do any changes on the instances after a
197 386b57af Iustin Pop
          rename, you can migrate the OS definition to version 5 by
198 386b57af Iustin Pop
          creating the <filename>rename</filename> script simply as:
199 386b57af Iustin Pop
          <screen>
200 386b57af Iustin Pop
#!/bin/sh
201 386b57af Iustin Pop
202 386b57af Iustin Pop
exit 0
203 386b57af Iustin Pop
          </screen>
204 386b57af Iustin Pop
        </para>
205 386b57af Iustin Pop
206 386b57af Iustin Pop
        <para>Note that the script must be executable.</para>
207 386b57af Iustin Pop
      </refsect3>
208 386b57af Iustin Pop
    </refsect2>
209 386b57af Iustin Pop
210 a8083063 Iustin Pop
    <!--
211 a8083063 Iustin Pop
    <refsect2>
212 a8083063 Iustin Pop
213 a8083063 Iustin Pop
      <title>Export/import format</title>
214 a8083063 Iustin Pop
215 386b57af Iustin Pop
      <para>
216 386b57af Iustin Pop
        It is up to the export and import scripts to define the format
217 386b57af Iustin Pop
        they use. It is only required for these two to work
218 386b57af Iustin Pop
        together. It is not recommended that
219 386b57af Iustin Pop
      </para>
220 a8083063 Iustin Pop
221 a8083063 Iustin Pop
    </refsect2>
222 a8083063 Iustin Pop
    -->
223 a8083063 Iustin Pop
224 a8083063 Iustin Pop
  </refsect1>
225 a8083063 Iustin Pop
226 a8083063 Iustin Pop
  &footer;
227 a8083063 Iustin Pop
228 a8083063 Iustin Pop
</refentry>
229 a8083063 Iustin Pop
230 a8083063 Iustin Pop
<!-- Keep this comment at the end of the file
231 a8083063 Iustin Pop
Local variables:
232 a8083063 Iustin Pop
mode: sgml
233 a8083063 Iustin Pop
sgml-omittag:t
234 a8083063 Iustin Pop
sgml-shorttag:t
235 a8083063 Iustin Pop
sgml-minimize-attributes:nil
236 a8083063 Iustin Pop
sgml-always-quote-attributes:t
237 a8083063 Iustin Pop
sgml-indent-step:2
238 a8083063 Iustin Pop
sgml-indent-data:t
239 a8083063 Iustin Pop
sgml-parent-document:nil
240 a8083063 Iustin Pop
sgml-default-dtd-file:nil
241 a8083063 Iustin Pop
sgml-exposed-tags:nil
242 a8083063 Iustin Pop
sgml-local-catalogs:nil
243 a8083063 Iustin Pop
sgml-local-ecat-files:nil
244 a8083063 Iustin Pop
End:
245 a8083063 Iustin Pop
-->