Statistics
| Branch: | Tag: | Revision:

root / man / gnt-backup.sgml @ c0e4a2c3

History | View | Annotate | Download (12.1 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>February 11, 2009</date>">
6
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
7
       allowed: see man(7), man(1). -->
8
  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
9
  <!ENTITY dhucpackage "<refentrytitle>gnt-backup</refentrytitle>">
10
  <!ENTITY dhpackage   "gnt-backup">
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>2007</year>
22
      <year>2008</year>
23
      <year>2009</year>
24
      <holder>Google Inc.</holder>
25
    </copyright>
26
    &dhdate;
27
  </refentryinfo>
28
  <refmeta>
29
    &dhucpackage;
30

    
31
    &dhsection;
32
    <refmiscinfo>ganeti 2.0</refmiscinfo>
33
  </refmeta>
34
  <refnamediv>
35
    <refname>&dhpackage;</refname>
36

    
37
    <refpurpose>ganeti instance import/export</refpurpose>
38
  </refnamediv>
39
  <refsynopsisdiv>
40
    <cmdsynopsis>
41
      <command>&dhpackage; </command>
42

    
43
      <arg choice="req">command</arg>
44
      <arg>arguments...</arg>
45
    </cmdsynopsis>
46
  </refsynopsisdiv>
47
  <refsect1>
48
    <title>DESCRIPTION</title>
49

    
50
    <para>
51
      The <command>&dhpackage;</command> is used for importing and exporting
52
      instances and their configuration from a ganeti system. It is useful for
53
      backing instances up and also to migrate them between clusters.
54
    </para>
55

    
56
  </refsect1>
57
  <refsect1>
58
    <title>COMMANDS</title>
59

    
60
    <refsect2>
61
      <title>EXPORT</title>
62

    
63
      <cmdsynopsis>
64
        <command>export</command>
65
        <arg choice="req">-n <replaceable>node</replaceable></arg>
66
        <arg>--noshutdown</arg>
67
        <arg choice="req"><replaceable>instance</replaceable></arg>
68
      </cmdsynopsis>
69

    
70
      <para>
71
        Exports an instance to the target node. All the instance data
72
        and its configuration will be exported under the
73
        /srv/ganeti/export/<replaceable>instance</replaceable>
74
        directory on the target node.
75
      </para>
76

    
77
      <para>
78
        The <option>--noshutdown</option> option will create a
79
        snapshot disk of the instance without shutting it down first.
80
        While this is faster and involves no downtime, it cannot be
81
        guaranteed that the instance data will be in a consistent state
82
        in the exported dump.
83
      </para>
84

    
85
      <para>
86
        Example:
87
        <screen>
88
# gnt-backup export -n node1.example.com instance3.example.com
89
        </screen>
90
      </para>
91
    </refsect2>
92

    
93
    <refsect2>
94
      <title>IMPORT</title>
95
      <cmdsynopsis>
96
        <command>import</command>
97
        <sbr>
98
        <group choice="req">
99
          <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg> <arg>--iallocator
100
          <replaceable>name</replaceable></arg>
101
        </group>
102
        <sbr>
103

    
104
        <arg rep="repeat">--disk <replaceable>N</replaceable>:size=<replaceable>VAL</replaceable><arg>,mode=<replaceable>ro|rw</replaceable></arg></arg>
105
        <sbr>
106
        <group>
107
          <arg rep="repeat">--net <replaceable>N</replaceable><arg rep="repeat">:options</arg></arg>
108
          <arg>--no-nics</arg>
109
        </group>
110
        <sbr>
111
        <arg>-B <replaceable>BEPARAMS</replaceable></arg>
112
        <sbr>
113
        <arg>-H <replaceable>HYPERVISOR</replaceable><arg>:<arg choice="plain" rep="repeat">option=<replaceable>value</replaceable></arg></arg></arg>
114
        <sbr>
115
        <arg>--src-node=<replaceable>source-node</replaceable></arg>
116
        <arg>--src-dir=<replaceable>source-dir</replaceable></arg>
117
        <sbr>
118

    
119
        <arg choice="req">-t<group>
120
            <arg>diskless</arg>
121
            <arg>plain</arg>
122
            <arg>drbd</arg>
123
            <arg>file</arg>
124
          </group></arg>
125
        <sbr>
126

    
127
        <arg choice="req"><replaceable>instance</replaceable></arg>
128
      </cmdsynopsis>
129
      <para>
130
        Imports a new instance from an export residing on
131
        <replaceable>source-node</replaceable> in
132
        <replaceable>source-dir</replaceable>.
133
        <replaceable>instance</replaceable> must be in DNS and resolve
134
        to a IP in the same network as the nodes in the cluster. If
135
        the source node and directory are not passed, the last backup
136
        in the cluster is used, as visible with the
137
        <command>list</command> command.
138
      </para>
139

    
140
      <para>
141
        The <option>disk</option> option specifies the parameters for
142
        the disks of the instance. The numbering of disks starts at
143
        zero, and at least one disk needs to be passed. For each disk,
144
        at least the size needs to be given, and optionally the access
145
        mode (read-only or the default of read-write) can also be
146
        specified.  The size is interpreted (when no unit is given) in
147
        mebibytes. You can also use one of the suffixes
148
        <literal>m</literal>, <literal>g</literal> or
149
        <literal>t</literal> to specificy the exact the units used;
150
        these suffixes map to mebibytes, gibibytes and tebibytes.
151
      </para>
152

    
153
      <para>
154
        Alternatively, a single-disk instance can be created via the
155
        <option>-s</option> option which takes a single argument,
156
        the size of the disk. This is similar to the Ganeti 1.2
157
        version (but will only create one disk).
158
      </para>
159

    
160
      <para>
161
        The minimum disk specification is therefore
162
        <userinput>--disk 0:size=20G</userinput> (or <userinput>-s
163
          20G</userinput> when using the <option>-s</option> option),
164
        and a three-disk instance can be specified as
165
        <userinput>--disk 0:size=20G --disk 1:size=4G --disk
166
          2:size=100G</userinput>.
167
      </para>
168

    
169
      <para>
170
        The NICs of the instances can be specified via the
171
        <option>--nic</option> option. By default, one NIC is created
172
        for the instance, with the MAC set to the original MAC of the
173
        instance (as it was at export time). Each NIC can take up to
174
        three parameters (all optional):
175
        <variablelist>
176
          <varlistentry>
177
            <term>mac</term>
178
            <listitem>
179
              <simpara>either a value or <constant>GENERATE</constant>
180
              to generate a new unique MAC, or
181
              <constant>AUTO</constant> to reuse the old MAC</simpara>
182
            </listitem>
183
          </varlistentry>
184
          <varlistentry>
185
            <term>ip</term>
186
            <listitem>
187
              <simpara>specifies the IP address assigned to the
188
              instance from the Ganeti side (this is not necessarily
189
              what the instance will use, but what the node expects
190
              the instance to use)</simpara>
191
            </listitem>
192
          </varlistentry>
193
          <varlistentry>
194
            <term>bridge</term>
195
            <listitem>
196
              <simpara>specifies the bridge to attach this NIC
197
              to</simpara>
198
            </listitem>
199
          </varlistentry>
200
        </variablelist>
201
      </para>
202

    
203
      <para>
204
        Alternatively, if no network is desired for the instance, you
205
        can prevent the default of one NIC with the
206
        <option>--no-nics</option> option.
207
      </para>
208

    
209
      <para>
210
        The <option>-B</option> option specifies the backend
211
        parameters for the instance. If no such parameters are
212
        specified, the values are inherited from the cluster. Possible
213
        parameters are:
214
        <variablelist>
215
          <varlistentry>
216
            <term>memory</term>
217
            <listitem>
218
              <simpara>the memory size of the instance; as usual,
219
              suffixes can be used to denote the unit, otherwise the
220
              value is taken in mebibites</simpara>
221
            </listitem>
222
          </varlistentry>
223
          <varlistentry>
224
            <term>vcpus</term>
225
            <listitem>
226
              <simpara>the number of VCPUs to assign to the instance
227
              (if this value makes sense for the hypervisor)</simpara>
228
            </listitem>
229
          </varlistentry>
230
          <varlistentry>
231
            <term>auto_balance</term>
232
            <listitem>
233
              <simpara>whether the instance is considered in the N+1
234
              cluster checks (enough redundancy in the cluster to
235
              survive a node failure)</simpara>
236
            </listitem>
237
          </varlistentry>
238
        </variablelist>
239
      </para>
240

    
241
      <para>
242
        The <option>-t</option> options specifies the disk layout type for
243
        the instance. The available choices are:
244
        <variablelist>
245
          <varlistentry>
246
            <term>diskless</term>
247
            <listitem>
248
              <para>
249
                This creates an instance with no disks. Its useful for
250
                testing only (or other special cases).
251
              </para>
252
            </listitem>
253
          </varlistentry>
254
          <varlistentry>
255
            <term>plain</term>
256
            <listitem>
257
              <para>Disk devices will be logical volumes.</para>
258
            </listitem>
259
          </varlistentry>
260
          <varlistentry>
261
            <term>drbd</term>
262
            <listitem>
263
              <para>
264
                Disk devices will be drbd (version 8.x) on top of lvm
265
                volumes.
266
              </para>
267
            </listitem>
268
          </varlistentry>
269
          <varlistentry>
270
            <term>file</term>
271
            <listitem>
272
              <para>Disk devices will be backed up by files, under the
273
              <filename
274
              class="directory">@RPL_FILE_STORAGE_DIR@</filename>. By
275
              default, each instance will get a directory (as its own
276
              name) under this path, and each disk is stored as
277
              individual files in this (instance-specific)
278
              directory.</para>
279
            </listitem>
280
          </varlistentry>
281
        </variablelist>
282
      </para>
283

    
284
      <para>
285
        The <option>--iallocator</option> option specifies the instance
286
        allocator plugin to use. If you pass in this option the allocator will
287
        select nodes for this instance automatically, so you don't need to pass
288
        them with the <option>-n</option> option. For more information please
289
        refer to the instance allocator documentation.
290
      </para>
291

    
292
      <para>
293
        The optional second value of the <option>--node</option> is used for
294
        the drbd template and specifies the remote node.
295
      </para>
296

    
297
      <para>
298
        If you do not want gnt-backup to wait for the disk mirror
299
        to be synced, use the <option>--no-wait-for-sync</option>
300
        option.
301
      </para>
302

    
303
      <para>
304
        Example:
305
        <screen>
306
# gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
307
> -n node1.example.com \
308
> instance3.example.com
309
        </screen>
310
      </para>
311

    
312
    </refsect2>
313

    
314
    <refsect2>
315
      <title>LIST</title>
316

    
317
      <cmdsynopsis>
318
        <command>list</command>
319
        <arg>--node=<replaceable>NODE</replaceable></arg>
320
      </cmdsynopsis>
321

    
322
      <para>
323
        Lists the exports currently available in the default directory
324
        in all the nodes of the current cluster, or optionally only a
325
        subset of them specified using the <option>--node</option>
326
        option (which can be used multiple times)
327
      </para>
328

    
329
      <para>
330
      Example:
331
<screen>
332
# gnt-backup list --nodes node1 --nodes node2
333
</screen>
334
    </refsect2>
335

    
336
    <refsect2>
337
      <title>REMOVE</title>
338
      <cmdsynopsis>
339
        <command>remove</command>
340
        <arg choice="req">instance_name</arg>
341
      </cmdsynopsis>
342

    
343
      <para>
344
        Removes the backup for the given instance name, if any. If the
345
        backup was for a deleted instances, it is needed to pass the
346
        <acronym>FQDN</acronym> of the instance, and not only the
347
        short hostname.
348
      </para>
349

    
350
    </refsect2>
351

    
352
  </refsect1>
353

    
354
  &footer;
355

    
356
</refentry>
357

    
358
<!-- Keep this comment at the end of the file
359
Local variables:
360
mode: sgml
361
sgml-omittag:t
362
sgml-shorttag:t
363
sgml-minimize-attributes:nil
364
sgml-always-quote-attributes:t
365
sgml-indent-step:2
366
sgml-indent-data:t
367
sgml-parent-document:nil
368
sgml-default-dtd-file:nil
369
sgml-exposed-tags:nil
370
sgml-local-catalogs:nil
371
sgml-local-ecat-files:nil
372
End:
373
-->