code.grnet.gr Git - ganeti-local/blob - man/gnt-backup.sgml

   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>--shutdown-timeout=<replaceable>N</replaceable></arg>
  67         <arg>--noshutdown</arg>
  68         <arg choice="req"><replaceable>instance</replaceable></arg>
  69
  70       </cmdsynopsis>
  71
  72       <para>
  73         Exports an instance to the target node. All the instance data
  74         and its configuration will be exported under the
  75         /srv/ganeti/export/<replaceable>instance</replaceable>
  76         directory on the target node.
  77       </para>
  78
  79       <para>
  80         The <option>--shutdown-timeout</option> is used to specify how
  81         much time to wait before forcing the shutdown (xm destroy in xen,
  82         killing the kvm process, for kvm). By default two minutes are
  83         given to each instance to stop.
  84       </para>
  85
  86       <para>
  87         The <option>--noshutdown</option> option will create a
  88         snapshot disk of the instance without shutting it down first.
  89         While this is faster and involves no downtime, it cannot be
  90         guaranteed that the instance data will be in a consistent state
  91         in the exported dump.
  92       </para>
  93
  94       <para>
  95         The exit code of the command is 0 if all disks were backed up
  96         successfully, 1 if no data was backed up or if the
  97         configuration export failed, and 2 if just some of the disks
  98         failed to backup. The exact details of the failures will be
  99         shown during the command execution (and will be stored in the
 100         job log). It is recommended that for any non-zero exit code,
 101         the backup is considered invalid, and retried.
 102       </para>
 103
 104       <para>
 105         Example:
 106         <screen>
 107 # gnt-backup export -n node1.example.com instance3.example.com
 108         </screen>
 109       </para>
 110     </refsect2>
 111
 112     <refsect2>
 113       <title>IMPORT</title>
 114       <cmdsynopsis>
 115         <command>import</command>
 116         <sbr>
 117         <group choice="req">
 118           <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg> <arg>--iallocator
 119           <replaceable>name</replaceable></arg>
 120         </group>
 121         <sbr>
 122
 123         <arg rep="repeat">--disk <replaceable>N</replaceable>:size=<replaceable>VAL</replaceable><arg>,mode=<replaceable>ro|rw</replaceable></arg></arg>
 124         <sbr>
 125         <group>
 126           <arg rep="repeat">--net <replaceable>N</replaceable><arg rep="repeat">:options</arg></arg>
 127           <arg>--no-nics</arg>
 128         </group>
 129         <sbr>
 130         <arg>-B <replaceable>BEPARAMS</replaceable></arg>
 131         <sbr>
 132         <arg>-H <replaceable>HYPERVISOR</replaceable><arg>:<arg choice="plain" rep="repeat">option=<replaceable>value</replaceable></arg></arg></arg>
 133         <sbr>
 134         <arg>--src-node=<replaceable>source-node</replaceable></arg>
 135         <arg>--src-dir=<replaceable>source-dir</replaceable></arg>
 136         <sbr>
 137
 138         <arg choice="req">-t<group>
 139             <arg>diskless</arg>
 140             <arg>plain</arg>
 141             <arg>drbd</arg>
 142             <arg>file</arg>
 143           </group></arg>
 144         <sbr>
 145
 146         <arg choice="req"><replaceable>instance</replaceable></arg>
 147       </cmdsynopsis>
 148       <para>
 149         Imports a new instance from an export residing on
 150         <replaceable>source-node</replaceable> in
 151         <replaceable>source-dir</replaceable>.
 152         <replaceable>instance</replaceable> must be in DNS and resolve
 153         to a IP in the same network as the nodes in the cluster. If
 154         the source node and directory are not passed, the last backup
 155         in the cluster is used, as visible with the
 156         <command>list</command> command.
 157       </para>
 158
 159       <para>
 160         The <option>disk</option> option specifies the parameters for
 161         the disks of the instance. The numbering of disks starts at
 162         zero, and at least one disk needs to be passed. For each disk,
 163         at least the size needs to be given, and optionally the access
 164         mode (read-only or the default of read-write) can also be
 165         specified.  The size is interpreted (when no unit is given) in
 166         mebibytes. You can also use one of the suffixes
 167         <literal>m</literal>, <literal>g</literal> or
 168         <literal>t</literal> to specificy the exact the units used;
 169         these suffixes map to mebibytes, gibibytes and tebibytes.
 170       </para>
 171
 172       <para>
 173         Alternatively, a single-disk instance can be created via the
 174         <option>-s</option> option which takes a single argument,
 175         the size of the disk. This is similar to the Ganeti 1.2
 176         version (but will only create one disk).
 177       </para>
 178
 179       <para>
 180         The minimum disk specification is therefore
 181         <userinput>--disk 0:size=20G</userinput> (or <userinput>-s
 182           20G</userinput> when using the <option>-s</option> option),
 183         and a three-disk instance can be specified as
 184         <userinput>--disk 0:size=20G --disk 1:size=4G --disk
 185           2:size=100G</userinput>.
 186       </para>
 187
 188       <para>
 189         The NICs of the instances can be specified via the
 190         <option>--net</option> option. By default, one NIC is created
 191         for the instance, with the MAC set to the original MAC of the
 192         instance (as it was at export time). Each NIC can take up to
 193         three parameters (all optional):
 194         <variablelist>
 195           <varlistentry>
 196             <term>mac</term>
 197             <listitem>
 198               <simpara>either a value or <constant>GENERATE</constant>
 199               to generate a new unique MAC, or
 200               <constant>AUTO</constant> to reuse the old MAC</simpara>
 201             </listitem>
 202           </varlistentry>
 203           <varlistentry>
 204             <term>ip</term>
 205             <listitem>
 206               <simpara>specifies the IP address assigned to the
 207               instance from the Ganeti side (this is not necessarily
 208               what the instance will use, but what the node expects
 209               the instance to use)</simpara>
 210             </listitem>
 211           </varlistentry>
 212             <varlistentry>
 213               <term>mode</term>
 214               <listitem>
 215                 <simpara>specifies the connection mode for this nic:
 216                   routed or bridged.</simpara>
 217               </listitem>
 218             </varlistentry>
 219             <varlistentry>
 220               <term>link</term>
 221               <listitem>
 222                 <simpara>in bridged mode specifies the bridge to attach
 223                   this NIC to, in routed mode it's intended to
 224                   differentiate between different routing tables/instance
 225                   groups (but the meaning is dependent on the network
 226                   script, see gnt-cluster(8) for more details)</simpara>
 227               </listitem>
 228             </varlistentry>
 229           </variablelist>
 230           Of these "mode" and "link" are nic parameters, and inherit their
 231           default at cluster level.
 232       </para>
 233
 234       <para>
 235         Alternatively, if no network is desired for the instance, you
 236         can prevent the default of one NIC with the
 237         <option>--no-nics</option> option.
 238       </para>
 239
 240       <para>
 241         The <option>-B</option> option specifies the backend
 242         parameters for the instance. If no such parameters are
 243         specified, the values are inherited from the cluster. Possible
 244         parameters are:
 245         <variablelist>
 246           <varlistentry>
 247             <term>memory</term>
 248             <listitem>
 249               <simpara>the memory size of the instance; as usual,
 250               suffixes can be used to denote the unit, otherwise the
 251               value is taken in mebibites</simpara>
 252             </listitem>
 253           </varlistentry>
 254           <varlistentry>
 255             <term>vcpus</term>
 256             <listitem>
 257               <simpara>the number of VCPUs to assign to the instance
 258               (if this value makes sense for the hypervisor)</simpara>
 259             </listitem>
 260           </varlistentry>
 261           <varlistentry>
 262             <term>auto_balance</term>
 263             <listitem>
 264               <simpara>whether the instance is considered in the N+1
 265               cluster checks (enough redundancy in the cluster to
 266               survive a node failure)</simpara>
 267             </listitem>
 268           </varlistentry>
 269         </variablelist>
 270       </para>
 271
 272       <para>
 273         The <option>-t</option> options specifies the disk layout type for
 274         the instance. The available choices are:
 275         <variablelist>
 276           <varlistentry>
 277             <term>diskless</term>
 278             <listitem>
 279               <para>
 280                 This creates an instance with no disks. Its useful for
 281                 testing only (or other special cases).
 282               </para>
 283             </listitem>
 284           </varlistentry>
 285           <varlistentry>
 286             <term>plain</term>
 287             <listitem>
 288               <para>Disk devices will be logical volumes.</para>
 289             </listitem>
 290           </varlistentry>
 291           <varlistentry>
 292             <term>drbd</term>
 293             <listitem>
 294               <para>
 295                 Disk devices will be drbd (version 8.x) on top of lvm
 296                 volumes.
 297               </para>
 298             </listitem>
 299           </varlistentry>
 300           <varlistentry>
 301             <term>file</term>
 302             <listitem>
 303               <para>Disk devices will be backed up by files, under the
 304               <filename
 305               class="directory">@RPL_FILE_STORAGE_DIR@</filename>. By
 306               default, each instance will get a directory (as its own
 307               name) under this path, and each disk is stored as
 308               individual files in this (instance-specific)
 309               directory.</para>
 310             </listitem>
 311           </varlistentry>
 312         </variablelist>
 313       </para>
 314
 315       <para>
 316         The <option>--iallocator</option> option specifies the instance
 317         allocator plugin to use. If you pass in this option the allocator will
 318         select nodes for this instance automatically, so you don't need to pass
 319         them with the <option>-n</option> option. For more information please
 320         refer to the instance allocator documentation.
 321       </para>
 322
 323       <para>
 324         The optional second value of the <option>--node</option> is used for
 325         the drbd template and specifies the remote node.
 326       </para>
 327
 328       <para>
 329         If you do not want gnt-backup to wait for the disk mirror
 330         to be synced, use the <option>--no-wait-for-sync</option>
 331         option.
 332       </para>
 333
 334       <para>
 335         Example:
 336         <screen>
 337 # gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
 338 > -n node1.example.com \
 339 > instance3.example.com
 340         </screen>
 341       </para>
 342
 343     </refsect2>
 344
 345     <refsect2>
 346       <title>LIST</title>
 347
 348       <cmdsynopsis>
 349         <command>list</command>
 350         <arg>--node=<replaceable>NODE</replaceable></arg>
 351       </cmdsynopsis>
 352
 353       <para>
 354         Lists the exports currently available in the default directory
 355         in all the nodes of the current cluster, or optionally only a
 356         subset of them specified using the <option>--node</option>
 357         option (which can be used multiple times)
 358       </para>
 359
 360       <para>
 361       Example:
 362 <screen>
 363 # gnt-backup list --nodes node1 --nodes node2
 364 </screen>
 365       </para>
 366     </refsect2>
 367
 368     <refsect2>
 369       <title>REMOVE</title>
 370       <cmdsynopsis>
 371         <command>remove</command>
 372         <arg choice="req">instance_name</arg>
 373       </cmdsynopsis>
 374
 375       <para>
 376         Removes the backup for the given instance name, if any. If the
 377         backup was for a deleted instances, it is needed to pass the
 378         <acronym>FQDN</acronym> of the instance, and not only the
 379         short hostname.
 380       </para>
 381
 382     </refsect2>
 383
 384   </refsect1>
 385
 386   &footer;
 387
 388 </refentry>
 389
 390 <!-- Keep this comment at the end of the file
 391 Local variables:
 392 mode: sgml
 393 sgml-omittag:t
 394 sgml-shorttag:t
 395 sgml-minimize-attributes:nil
 396 sgml-always-quote-attributes:t
 397 sgml-indent-step:2
 398 sgml-indent-data:t
 399 sgml-parent-document:nil
 400 sgml-default-dtd-file:nil
 401 sgml-exposed-tags:nil
 402 sgml-local-catalogs:nil
 403 sgml-local-ecat-files:nil
 404 End:
 405 -->