Statistics
| Branch: | Tag: | Revision:

root / man / ganeti-os-interface.sgml @ 48c4dfa8

History | View | Annotate | Download (7.5 kB)

1
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2

    
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">
11

    
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">
16
]>
17

    
18
<refentry>
19
  <refentryinfo>
20
    <copyright>
21
      <year>2006</year>
22
      <year>2007</year>
23
      <holder>Google Inc.</holder>
24
    </copyright>
25
    &dhdate;
26
  </refentryinfo>
27
  <refmeta>
28
    &dhucpackage;
29

    
30
    &dhsection;
31
    <refmiscinfo>ganeti 1.2</refmiscinfo>
32
  </refmeta>
33
  <refnamediv>
34
    <refname>ganeti-os-interface</refname>
35

    
36
    <refpurpose>specifications for guest OS types
37
    </refpurpose>
38

    
39
  </refnamediv>
40

    
41
  <refsect1>
42
    <title>DESCRIPTION</title>
43

    
44
    <para>
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
47
      required files.
48
    </para>
49

    
50

    
51
  </refsect1>
52
  <refsect1>
53
    <title>REFERENCE</title>
54

    
55
    <para>
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).
60
    </para>
61

    
62
    <refsect2>
63
      <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

    
71
      <para>The <command>create</command> command is used for creating
72
      a new instance from scratch.</para>
73

    
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>
79

    
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
    </refsect2>
89

    
90
    <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>
98

    
99
      <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>.
106
      </para>
107

    
108
    </refsect2>
109

    
110
    <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>
117

    
118
      <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.
123
      </para>
124

    
125
      <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.
130
      </para>
131

    
132
    </refsect2>
133

    
134
    <refsect2>
135
      <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

    
144
      <para>
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.
150
      </para>
151

    
152
      <para>
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
157
        instance.
158
      </para>
159

    
160
      <para>
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.
164
      </para>
165
    </refsect2>
166

    
167
    <refsect2>
168
      <title>ganeti_api_version</title>
169
      <para>
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
174
        by a newline.
175
      </para>
176
    </refsect2>
177

    
178
  </refsect1>
179

    
180
  <refsect1>
181
    <title>NOTES</title>
182

    
183
    <refsect2>
184
      <title>Common behaviour</title>
185

    
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>
187

    
188
    </refsect2>
189

    
190
    <refsect2>
191
      <title>Upgrading from old versions</title>
192
      <refsect3>
193
        <title>Version 4 to 5</title>
194
        <para>
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:
199
          <screen>
200
#!/bin/sh
201

    
202
exit 0
203
          </screen>
204
        </para>
205

    
206
        <para>Note that the script must be executable.</para>
207
      </refsect3>
208
    </refsect2>
209

    
210
    <!--
211
    <refsect2>
212

    
213
      <title>Export/import format</title>
214

    
215
      <para>
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
219
      </para>
220

    
221
    </refsect2>
222
    -->
223

    
224
  </refsect1>
225

    
226
  &footer;
227

    
228
</refentry>
229

    
230
<!-- Keep this comment at the end of the file
231
Local variables:
232
mode: sgml
233
sgml-omittag:t
234
sgml-shorttag:t
235
sgml-minimize-attributes:nil
236
sgml-always-quote-attributes:t
237
sgml-indent-step:2
238
sgml-indent-data: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
244
End:
245
-->