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         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       </para>
 335     </refsect2>
 336
 337     <refsect2>
 338       <title>REMOVE</title>
 339       <cmdsynopsis>
 340         <command>remove</command>
 341         <arg choice="req">instance_name</arg>
 342       </cmdsynopsis>
 343
 344       <para>
 345         Removes the backup for the given instance name, if any. If the
 346         backup was for a deleted instances, it is needed to pass the
 347         <acronym>FQDN</acronym> of the instance, and not only the
 348         short hostname.
 349       </para>
 350
 351     </refsect2>
 352
 353   </refsect1>
 354
 355   &footer;
 356
 357 </refentry>
 358
 359 <!-- Keep this comment at the end of the file
 360 Local variables:
 361 mode: sgml
 362 sgml-omittag:t
 363 sgml-shorttag:t
 364 sgml-minimize-attributes:nil
 365 sgml-always-quote-attributes:t
 366 sgml-indent-step:2
 367 sgml-indent-data:t
 368 sgml-parent-document:nil
 369 sgml-default-dtd-file:nil
 370 sgml-exposed-tags:nil
 371 sgml-local-catalogs:nil
 372 sgml-local-ecat-files:nil
 373 End:
 374 -->