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