Move gnt-job to ganeti.client.gnt_job

[ganeti-local] / man / gnt-backup.sgml

<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>June 08, 2010</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
  <!ENTITY dhucpackage "<refentrytitle>gnt-backup</refentrytitle>">
  <!ENTITY dhpackage   "gnt-backup">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  <!ENTITY footer SYSTEM "footer.sgml">
]>

<refentry>
  <refentryinfo>
    <copyright>
      <year>2007</year>
      <year>2008</year>
      <year>2009</year>
      <year>2010</year>
      <holder>Google Inc.</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
    <refmiscinfo>Ganeti 2.2</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>Ganeti instance import/export</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage; </command>

      <arg choice="req">command</arg>
      <arg>arguments...</arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

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

  </refsect1>
  <refsect1>
    <title>COMMANDS</title>

    <refsect2>
      <title>EXPORT</title>

      <cmdsynopsis>
        <command>export</command>
        <arg choice="req">-n <replaceable>node</replaceable></arg>
        <arg>--shutdown-timeout=<replaceable>N</replaceable></arg>
        <arg>--noshutdown</arg>
        <arg>--remove-instance</arg>
        <arg>--ignore-remove-failures</arg>
        <arg choice="req"><replaceable>instance</replaceable></arg>

      </cmdsynopsis>

      <para>
        Exports an instance to the target node. All the instance data
        and its configuration will be exported under the
        /srv/ganeti/export/<replaceable>instance</replaceable>
        directory on the target node.
      </para>

      <para>
        The <option>--shutdown-timeout</option> is used to specify how
        much time to wait before forcing the shutdown (xm destroy in xen,
        killing the kvm process, for kvm). By default two minutes are
        given to each instance to stop.
      </para>

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

      <para>
        The <option>--remove</option> option can be used to remove the
        instance after it was exported. This is useful to make one last
        backup before removing the instance.
      </para>

      <para>
        The exit code of the command is 0 if all disks were backed up
        successfully, 1 if no data was backed up or if the
        configuration export failed, and 2 if just some of the disks
        failed to backup. The exact details of the failures will be
        shown during the command execution (and will be stored in the
        job log). It is recommended that for any non-zero exit code,
        the backup is considered invalid, and retried.
      </para>

      <para>
        Example:
        <screen>
# gnt-backup export -n node1.example.com instance3.example.com
        </screen>
      </para>
    </refsect2>

    <refsect2>
      <title>IMPORT</title>
      <cmdsynopsis>
        <command>import</command>
        <sbr>
        <group choice="req">
          <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg> <arg>--iallocator
          <replaceable>name</replaceable></arg>
        </group>
        <sbr>

        <arg rep="repeat">--disk <replaceable>N</replaceable>:size=<replaceable>VAL</replaceable><arg>,mode=<replaceable>ro|rw</replaceable></arg></arg>
        <sbr>
        <group>
          <arg rep="repeat">--net <replaceable>N</replaceable><arg rep="repeat">:options</arg></arg>
          <arg>--no-nics</arg>
        </group>
        <sbr>
        <arg>-B <replaceable>BEPARAMS</replaceable></arg>
        <sbr>
        <arg>-H <replaceable>HYPERVISOR</replaceable><arg>:<arg choice="plain" rep="repeat">option=<replaceable>value</replaceable></arg></arg></arg>
        <sbr>
        <arg>--src-node=<replaceable>source-node</replaceable></arg>
        <arg>--src-dir=<replaceable>source-dir</replaceable></arg>
        <sbr>

        <arg choice="opt">-t<group>
            <arg>diskless</arg>
            <arg>plain</arg>
            <arg>drbd</arg>
            <arg>file</arg>
          </group></arg>
        <sbr>

        <arg choice="opt">--identify-defaults</arg>
        <sbr>

        <arg choice="req"><replaceable>instance</replaceable></arg>
      </cmdsynopsis>

      <para>
        Imports a new instance from an export residing on
        <replaceable>source-node</replaceable> in
        <replaceable>source-dir</replaceable>.
        <replaceable>instance</replaceable> must be in DNS and resolve
        to a IP in the same network as the nodes in the cluster. If
        the source node and directory are not passed, the last backup
        in the cluster is used, as visible with the
        <command>list</command> command.
      </para>

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

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

      <para>
        If no disk information is passed, the disk configuration saved
        at export time will be used.
      </para>

      <para>
        The minimum disk specification is therefore empty (export
        information will be used), a single disk can be specified as
        <userinput>--disk 0:size=20G</userinput> (or <userinput>-s
          20G</userinput> when using the <option>-s</option> option),
        and a three-disk instance can be specified as
        <userinput>--disk 0:size=20G --disk 1:size=4G --disk
          2:size=100G</userinput>.
      </para>

      <para>
        The NICs of the instances can be specified via the
        <option>--net</option> option. By default, the NIC
        configuration of the original (exported) instance will be
        reused. Each NIC can take up to three parameters (all
        optional):
        <variablelist>
          <varlistentry>
            <term>mac</term>
            <listitem>
              <simpara>either a value or 'generate' to generate a new
              unique MAC, or 'auto' to reuse the old MAC</simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>ip</term>
            <listitem>
              <simpara>specifies the IP address assigned to the
              instance from the Ganeti side (this is not necessarily
              what the instance will use, but what the node expects
              the instance to use)</simpara>
            </listitem>
          </varlistentry>
            <varlistentry>
              <term>mode</term>
              <listitem>
                <simpara>specifies the connection mode for this nic:
                  routed or bridged.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>link</term>
              <listitem>
                <simpara>in bridged mode specifies the bridge to attach
                  this NIC to, in routed mode it's intended to
                  differentiate between different routing tables/instance
                  groups (but the meaning is dependent on the network
                  script, see gnt-cluster(8) for more details)</simpara>
              </listitem>
            </varlistentry>
          </variablelist>
          Of these "mode" and "link" are nic parameters, and inherit their
          default at cluster level.
      </para>

      <para>
        If no network is desired for the instance, you should create a
        single empty NIC and delete it afterwards
        via <command>gnt-instance modify --net delete</command>.
      </para>

      <para>
        The <option>-B</option> option specifies the backend
        parameters for the instance. If no such parameters are
        specified, the values are inherited from the export. Possible
        parameters are:
        <variablelist>
          <varlistentry>
            <term>memory</term>
            <listitem>
              <simpara>the memory size of the instance; as usual,
              suffixes can be used to denote the unit, otherwise the
              value is taken in mebibites</simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>vcpus</term>
            <listitem>
              <simpara>the number of VCPUs to assign to the instance
              (if this value makes sense for the hypervisor)</simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>auto_balance</term>
            <listitem>
              <simpara>whether the instance is considered in the N+1
              cluster checks (enough redundancy in the cluster to
              survive a node failure)</simpara>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>

      <para>
        The <option>-t</option> options specifies the disk layout type
        for the instance. If not passed, the configuration of the
        original instance is used. The available choices are:
        <variablelist>
          <varlistentry>
            <term>diskless</term>
            <listitem>
              <para>
                This creates an instance with no disks. Its useful for
                testing only (or other special cases).
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>plain</term>
            <listitem>
              <para>Disk devices will be logical volumes.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>drbd</term>
            <listitem>
              <para>
                Disk devices will be drbd (version 8.x) on top of lvm
                volumes.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>file</term>
            <listitem>
              <para>Disk devices will be backed up by files, under the
              <filename
              class="directory">@RPL_FILE_STORAGE_DIR@</filename>. By
              default, each instance will get a directory (as its own
              name) under this path, and each disk is stored as
              individual files in this (instance-specific)
              directory.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>

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

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

      <para>
        Since many of the parameters are by default read from the
        exported instance information and used as such, the new
        instance will have all parameters explicitly specified, the
        opposite of a newly added instance which has most parameters
        specified via cluster defaults. To change the import behaviour
        to recognize parameters whose saved value matches the current
        cluster default and mark it as such (default value), pass
        the <option>--identify-defaults</option> option. This will
        affect the hypervisor, backend and NIC parameters, both read
        from the export file and passed in via the command line.
      </para>

      <para>
        Example for identical instance import:
        <screen>
# gnt-backup import -n node1.example.com instance3.example.com
        </screen>
      </para>
      <para>
        Explicit configuration example:
        <screen>
# gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
> -n node1.example.com \
> instance3.example.com
        </screen>
      </para>

    </refsect2>

    <refsect2>
      <title>LIST</title>

      <cmdsynopsis>
        <command>list</command>
        <arg>--node=<replaceable>NODE</replaceable></arg>
      </cmdsynopsis>

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

      <para>
      Example:
<screen>
# gnt-backup list --nodes node1 --nodes node2
</screen>
      </para>
    </refsect2>

    <refsect2>
      <title>REMOVE</title>
      <cmdsynopsis>
        <command>remove</command>
        <arg choice="req">instance_name</arg>
      </cmdsynopsis>

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

    </refsect2>

  </refsect1>

  &footer;

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->