root / man / ganeti-os-interface.sgml @ 5b209f0c
History | View | Annotate | Download (7.6 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 guest 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 |
</screen> |
165 |
</para> |
166 |
</refsect2> |
167 |
|
168 |
<refsect2> |
169 |
<title>ganeti_api_version</title> |
170 |
<para> |
171 |
The <filename>ganeti_api_version</filename> file is a plain |
172 |
text file containing the version of the guest OS api that this |
173 |
OS definition complies with. The version documented by this |
174 |
man page is 5, so this file must contain the number 5 followed |
175 |
by a newline. |
176 |
</para> |
177 |
</refsect2> |
178 |
|
179 |
</refsect1> |
180 |
|
181 |
<refsect1> |
182 |
<title>NOTES</title> |
183 |
|
184 |
<refsect2> |
185 |
<title>Common behaviour</title> |
186 |
|
187 |
<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> |
188 |
|
189 |
</refsect2> |
190 |
|
191 |
<refsect2> |
192 |
<title>Upgrading from old versions</title> |
193 |
<refsect3> |
194 |
<title>Version 4 to 5</title> |
195 |
<para> |
196 |
The <filename>rename</filename> script has been added. If |
197 |
you don't want to do any changes on the instances after a |
198 |
rename, you can migrate the OS definition to version 5 by |
199 |
creating the <filename>rename</filename> script simply as: |
200 |
<screen> |
201 |
#!/bin/sh |
202 |
|
203 |
exit 0 |
204 |
</screen> |
205 |
</para> |
206 |
|
207 |
<para>Note that the script must be executable.</para> |
208 |
</refsect3> |
209 |
</refsect2> |
210 |
|
211 |
<!-- |
212 |
<refsect2> |
213 |
|
214 |
<title>Export/import format</title> |
215 |
|
216 |
<para> |
217 |
It is up to the export and import scripts to define the format |
218 |
they use. It is only required for these two to work |
219 |
together. It is not recommended that |
220 |
</para> |
221 |
|
222 |
</refsect2> |
223 |
--> |
224 |
|
225 |
</refsect1> |
226 |
|
227 |
&footer; |
228 |
|
229 |
</refentry> |
230 |
|
231 |
<!-- Keep this comment at the end of the file |
232 |
Local variables: |
233 |
mode: sgml |
234 |
sgml-omittag:t |
235 |
sgml-shorttag:t |
236 |
sgml-minimize-attributes:nil |
237 |
sgml-always-quote-attributes:t |
238 |
sgml-indent-step:2 |
239 |
sgml-indent-data:t |
240 |
sgml-parent-document:nil |
241 |
sgml-default-dtd-file:nil |
242 |
sgml-exposed-tags:nil |
243 |
sgml-local-catalogs:nil |
244 |
sgml-local-ecat-files:nil |
245 |
End: |
246 |
--> |