Synnefo » snf-ganeti » ganeti-local

<!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>May 16, 2007</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-instance</refentrytitle>">

  <!ENTITY dhpackage   "gnt-instance">

  <!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>2006</year>

      <year>2007</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>ganeti 1.2</refmiscinfo>

  </refmeta>

  <refnamediv>

    <refname>&dhpackage;</refname>

    <refpurpose>ganeti instance administration</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 instance

      administration in the ganeti system.

    </para>

  </refsect1>

  <refsect1>

    <title>COMMANDS</title>

    <refsect2>

      <title>Creation/removal/querying</title>

      <refsect3>

        <title>ADD</title>

        <cmdsynopsis>

          <command>add</command>

          <arg>-s <replaceable>disksize</replaceable></arg>

          <arg>--swap-size <replaceable>disksize</replaceable></arg>

          <arg>-m <replaceable>memsize</replaceable></arg>

          <sbr>

          <arg>-o <replaceable>os-type</replaceable></arg>

          <arg>-b <replaceable>bridge</replaceable></arg>

          <sbr>

          <arg choice="req">-t<group>

              <arg>diskless</arg>

              <arg>plain</arg>

              <arg>local_raid1</arg>

              <arg>remote_raid1</arg>

            </group>

          </arg>

          <sbr>

          <arg choice="req">-n <replaceable>node</replaceable></arg>

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

        </cmdsynopsis>

        <para>

          Creates a new instance on the specified

          host. <replaceable>instance</replaceable> must be in DNS and

          resolve to a IP in the same network as the nodes in the

          cluster.

        </para>

        <para>

          The <option>-s</option> option specifies the disk size for

          the instance, in mebibytes (defaults to

          <constant>20480MiB</constant> =

          <constant>20GiB</constant>). 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>

          The <option>--swap-size</option> option specifies the swap

          disk size (in mebibytes) for the instance (the one presented

          as <filename class="devicefile">/dev/sdb</filename>). The

          default is <constant>4096MiB</constant>. As for the disk

          size, you can specify other suffixes.

        </para>

        <para>

          The <option>-m</option> option specifies the memory size for

          the instance, in mebibytes (defaults to 128 MiB). Again, you

          can use other suffixes (e.g. <userinput>2g</userinput>).

        </para>

        <para>

          The <option>-o</option> options specifies the operating

          system to be installed. The available operating systems can

          be listed with <command>gnt-os list</command>.

        </para>

        <para>

          The <option>-b</option> option specifies the bridge to which the

          instance will be connected. (defaults to the cluster-wide default

          bridge specified at cluster initialization time).

        </para>

        <para>

          The <option>-t</option> options specifies the disk layout type for

          the instance. 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>local_raid1</term>

              <listitem>

                <para>

                  Disk devices will be md raid1 arrays over two local

                  logical volumes.

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>remote_raid1</term>

              <listitem>

                <para>

                  Disk devices will be md raid1 arrays with one

                  component (so it's not actually raid1): a drbd device

                  between the instance's primary node and the node given

                  by the option <option>--secondary-node</option>.

                </para>

              </listitem>

            </varlistentry>

          </variablelist>

        </para>

        <para>

          The <option>--secondary-node</option> option is used with

          the remote raid disk template type and specifies the remote

          node.

        </para>

        <para>

          If you do not want gnt-instance to wait for the disk mirror

          to be synced, use the <option>--no-wait-for-sync</option>

          option.

        </para>

        <para>

          Example:

          <screen>

# gnt-instance add -t plain -s 30g -m 512 -o debian-etch \

  -n node1.example.com instance1.example.com

# gnt-instance add -t remote_raid1 --secondary-node node3.example.com \

  -s 30g -m 512 -o debian-etch \

  -n node1.example.com instance2.example.com

          </screen>

        </para>

      </refsect3>

      <refsect3>

        <title>REMOVE</title>

        <cmdsynopsis>

          <command>remove</command>

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

        </cmdsynopsis>

        <para>

          Remove an instance. This will remove all data from the

          instance and there is <emphasis>no way back</emphasis>. If

          you are not sure if you use an instance again, use

          <command>shutdown</command> first and leave it in the

          shutdown state for a while.

        </para>

        <para>

          Example:

          <screen>

# gnt-instance remove instance1.example.com

          </screen>

        </para>

      </refsect3>

      <refsect3>

        <title>LIST</title>

        <cmdsynopsis>

          <command>list</command>

          <arg>--no-headers</arg>

          <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>

          <arg>-o <replaceable>FIELD,...</replaceable></arg>

        </cmdsynopsis>

        <para>

          Shows the currently configured instances with memory usage,

          disk usage, the node they are running on, and the CPU time,

          counted in seconds, used by each instance since its latest

          restart.

        </para>

        <para>

          The <option>--no-headers</option> option will skip the

          initial header line. The <option>--separator</option> option

          takes an argument which denotes what will be used between

          the output fields. Both these options are to help scripting.

        </para>

        <para>

          The <option>-o</option> option takes a comma-separated list

          of output fields. The available fields and their meaning

          are:

          <variablelist>

            <varlistentry>

              <term>name</term>

              <listitem>

                <simpara>the instance name</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>os</term>

              <listitem>

                <simpara>the OS of the instance</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>pnode</term>

              <listitem>

                <simpara>the primary node of the instance</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>snodes</term>

              <listitem>

                <simpara>comma-separated list of secondary-nodes for the

                  instance; usually this will be just one node</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>admin_state</term>

              <listitem>

                <simpara>the desired state of the instance (either "yes"

                  or "no" denoting the instance should run or

                  not)</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>admin_ram</term>

              <listitem>

                <simpara>the desired memory for the instance</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>disk_template</term>

              <listitem>

                <simpara>the disk template of the instance</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>oper_state</term>

              <listitem>

                <simpara>the actual state of the instance; can take of

                  the values "running", "stopped", "(node down)"</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>oper_ram</term>

              <listitem>

                <simpara>the actual memory usage of the instance as seen

                  by the hypervisor</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>ip</term>

              <listitem>

                <simpara>the ip address ganeti recognizes as associated with

                the instance interface</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>mac</term>

              <listitem>

                <simpara>the instance interface MAC address</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>bridge</term>

              <listitem>

                <simpara>bridge the instance is connected to

                </simpara>

              </listitem>

            </varlistentry>

          </variablelist>

        </para>

        <para>

          There is a subtle grouping about the available output

          fields: all fields except for <option>oper_state</option>

          and <option>oper_ram</option> are configuration value and

          not run-time values. So if you don't select any of the

          <option>oper_*</option> fields, the query will be satisfied

          instantly from the cluster configuration, without having to

          ask the remote nodes for the data. This can be helpful for

          big clusters when you only want some data and it makes sense

          to specify a reduced set of output fields.

        </para>

        <para>The default output field list is:

          <simplelist type="inline">

            <member>name</member>

            <member>os</member>

            <member>pnode</member>

            <member>admin_state</member>

            <member>oper_state</member>

            <member>oper_ram</member>

          </simplelist>.

        </para>

      </refsect3>

      <refsect3>

        <title>INFO</title>

        <cmdsynopsis>

          <command>info</command>

          <arg rep="repeat"><replaceable>instance</replaceable></arg>

        </cmdsynopsis>

        <para>

          Show detailed information about the (given) instances. This

          is different from <command>list</command> as it shows

          detailed data about the instance's disks (especially useful

          for remote raid templates).

        </para>

      </refsect3>

      <refsect3>

        <title>MODIFY</title>

        <cmdsynopsis>

          <command>modify</command>

          <arg choice="opt">-m <replaceable>memsize</replaceable></arg>

          <arg choice="opt">-p <replaceable>vcpus</replaceable></arg>

          <arg choice="opt">-i <replaceable>ip</replaceable></arg>

          <arg choice="opt">-b <replaceable>bridge</replaceable></arg>

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

        </cmdsynopsis>

        <para>

          Modify the memory size, number of vcpus, ip address and/or bridge

          for an instance.

        </para>

        <para>

          The memory size is given in MiB. Note that you need to give

          at least one of the arguments, otherwise the command

          complains.

        </para>

        <para>

          All the changes take effect at the next restart. If the

          instance is running, there is no effect on the instance.

        </para>

      </refsect3>

      <refsect3>

        <title>REINSTALL</title>

        <cmdsynopsis>

          <command>reinstall</command>

          <arg choice="opt">-o <replaceable>os-type</replaceable></arg>

          <arg choice="opt">-f <replaceable>force</replaceable></arg>

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

        </cmdsynopsis>

        <para>

          Reinstalls the operating system on the given instance. The instance

          must be stopped when running this command. If the

          <option>--os-type</option> is specified, the operating system is

          changed.

        </para>

      </refsect3>

      <refsect3>

        <title>RENAME</title>

        <cmdsynopsis>

          <command>rename</command>

          <arg>--no-ip-check</arg>

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

          <arg choice="req"><replaceable>new_name</replaceable></arg>

        </cmdsynopsis>

        <para>

          Renames the given instance. The instance must be stopped

          when running this command. The requirements for the new name

          are the same as for adding an instance: the new name must be

          resolvable and the IP it resolves to must not be reachable

          (in order to prevent duplicate IPs the next time the

          instance is started). The IP test can be skipped if the

          <option>--no-ip-check</option> option is passed.

        </para>

      </refsect3>

    </refsect2>

    <refsect2>

      <title>Starting/stopping/connecting to console</title>

      <refsect3>

        <title>STARTUP</title>

        <cmdsynopsis>

          <command>startup</command>

          <arg>--extra=<replaceable>PARAMS</replaceable></arg>

          <sbr>

          <group choice="opt">

            <arg>--instance</arg>

            <arg>--node</arg>

            <arg>--primary</arg>

            <arg>--secondary</arg>

            <arg>--all</arg>

          </group>

          <sbr>

          <arg choice="opt"

          rep="repeat"><replaceable>name</replaceable></arg>

        </cmdsynopsis>

        <para>

          Starts one or more instances, depending on the

          <option>--by-*</option> mode. The four available modes are:

          <variablelist>

            <varlistentry>

              <term><option>--instance</option></term>

              <listitem>

                <simpara>will start the instances given as arguments

                (at least one argument required); this is the default

                selection</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>--node</term>

              <listitem>

                <simpara>will start the instances who have the given

                node as either primary or secondary</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><option>--primary</option></term>

              <listitem>

                <simpara>will start all instances whose primary node

                is in the list of nodes passed as arguments (at least

                one node required)</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term><option>--secondary</option></term>

              <listitem>

                <simpara>will start all instances whose secondary node

                is in the list of nodes passed as arguments (at least

                one node required)</simpara>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>--all</term>

              <listitem>

                <simpara>will start all instances in the cluster (no

                arguments accepted)</simpara>

              </listitem>

            </varlistentry>

          </variablelist>

        </para>

        <para>

          Note that although you can pass more than one

          <option>--by-</option> option, the last one wins, so in

          order to guarantee the desired result, don't pass more than

          one such option.

        </para>

        <para>

          The <option>--extra</option> option is used to pass

          additional argument to the instance's kernel for this start

          only. Currently there is no way to specify a persistent set

          of arguments (beside the one hardcoded). Note that this may

          not apply to all virtualization types.

        </para>

        <para>

          Example:

          <screen>

# gnt-instance start instance1.example.com

# gnt-instance start --extra single test1.example.com

# gnt-instance start --by-node node1.example.com node2.example.com

# gnt-instance start --by-cluster

          </screen>

        </para>

      </refsect3>

      <refsect3>

        <title>SHUTDOWN</title>

        <cmdsynopsis>

          <command>shutdown</command>

          <sbr>

          <group choice="opt">

            <arg>--instance</arg>

            <arg>--node</arg>

            <arg>--primary</arg>

            <arg>--secondary</arg>

            <arg>--all</arg>

          </group>

          <sbr>

          <arg choice="opt"

          rep="repeat"><replaceable>name</replaceable></arg>

        </cmdsynopsis>

        <para>

          Stops one or more instances. If the instance cannot be

          cleanly stopped during a hardcoded interval (currently 2

          minutes), it will forcibly stop the instance (equivalent to

          switching off the power on a physical machine).

        </para>

        <para>

          The <option>--instance</option>, <option>--node</option>,

          <option>--primary</option>, <option>--secondary</option> and

          <option>--all</option> options are similar as for the

          <command>startup</command> command and they influence the

          actual instances being shutodnw.

        </para>

        <para>

          Example:

          <screen>

# gnt-instance shutdown instance1.example.com

# gnt-instance shutdown --by-cluster

          </screen>

        </para>

      </refsect3>

      <refsect3>

        <title>CONSOLE</title>

        <cmdsynopsis>

          <command>console</command>

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

        </cmdsynopsis>

        <para>

          Connects to the console of the given instance. If the instance

          is not up, an error is returned.

        </para>

        <para>

          Example:

          <screen>

# gnt-instance console instance1.example.com

          </screen>

        </para>

      </refsect3>

    </refsect2>

    <refsect2>

      <title>Disk management</title>

      <refsect3>

        <title>REPLACE-DISKS</title>

        <cmdsynopsis>

          <command>replace-disks</command>

          <arg choice="req">--new-secondary <replaceable>NODE</replaceable></arg>

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

        </cmdsynopsis>

        <para>

          This command does a full add and replace for both disks of

          an instance.  It basically does an

          <command>addmirror</command> and

          <command>removemirror</command> for both disks of the

          instance.

        </para>

        <para>

          If you also want to replace the secondary node during this

          process (for example to fix a broken secondary node), you

          can do so using the <option>--new-secondary</option> option.

        </para>

      </refsect3>

      <refsect3>

        <title>ADD-MIRROR</title>

        <cmdsynopsis>

          <command>add-mirror</command>

          <arg choice="req">-b <replaceable>sdX</replaceable></arg>

          <arg choice="req">-n <replaceable>node</replaceable></arg>

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

        </cmdsynopsis>

        <para>

          Adds a new mirror to the disk layout of the instance, if the

          instance has a remote raid disk layout.

          The new mirror member will be between the instance's primary

          node and the node given with the <option>-n</option> option.

        </para>

      </refsect3>

      <refsect3>

        <title>REMOVE-MIRROR</title>

        <cmdsynopsis>

          <command>removemirror</command>

          <arg choice="req">-b <replaceable>sdX</replaceable></arg>

          <arg choice="req">-p <replaceable>id</replaceable></arg>

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

        </cmdsynopsis>

        <para>

          Removes a mirror componenent from the disk layout of the

          instance, if the instance has a remote raid disk layout.

        </para>

        <para>

          You need to specifiy on which disk to act on using the

          <option>-b</option> option (either <filename>sda</filename>

          or <filename>sdb</filename>) and the mirror component, which

          is identified by the <option>-p</option> option. You can

          find the list of valid identifiers with the

          <command>info</command> command.

        </para>

      <refsect3>

        <title>ACTIVATE-DISKS</title>

        <cmdsynopsis>

          <command>activate-disks</command>

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

        </cmdsynopsis>

        <para>

          Activates the block devices of the given instance. If

          successful, the command will show the location and name of

          the block devices:

          <screen>

node1.example.com:sda:/dev/md0

node1.example.com:sdb:/dev/md1

          </screen>

          In this example, <emphasis>node1.example.com</emphasis> is

          the name of the node on which the devices have been

          activated. The <emphasis>sda</emphasis> and

          <emphasis>sdb</emphasis> are the names of the block devices

          inside the instance. <emphasis>/dev/md0</emphasis> and

          <emphasis>/dev/md1</emphasis> are the names of the block

          devices as visible on the node.

        </para>

        <para>

          Note that it is safe to run this command while the instance

          is already running.

        </para>

      </refsect3>

      <refsect3>

        <title>DEACTIVATE-DISKS</title>

        <cmdsynopsis>

          <command>deactivate-disks</command>

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

        </cmdsynopsis>

        <para>

          De-activates the block devices of the given instance. Note

          that if you run this command for a remote raid instance

          type, while it is running, it will not be able to shutdown

          the block devices on the primary node, but it will shutdown

          the block devices on the secondary nodes, thus breaking the

          replication.

        </para>

      </refsect3>

    </refsect2>

    <refsect2>

      <title>Recovery</title>

      <refsect3>

        <title>FAILOVER</title>

        <cmdsynopsis>

          <command>failover</command>

          <arg>-f</arg>

          <arg>--ignore-consistency</arg>

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

        </cmdsynopsis>

        <para>

          Failover will fail the instance over its secondary

          node. This works only for instances having a remote raid

          disk layout.

        </para>

        <para>

          Normally the failover will check the consistency of the

          disks before failing over the instance. If you are trying to

          migrate instances off a dead node, this will fail. Use the

          <option>--ignore-consistency</option> option for this

          purpose.

        </para>

        <para>

          Example:

          <screen>

# gnt-instance failover instance1.example.com

          </screen>

        </para>

      </refsect3>

    </refsect2>

    <refsect2>

      <title>TAGS</title>

    <refsect3>

        <title>ADD-TAGS</title>

        <cmdsynopsis>

          <command>add-tags</command>

          <arg choice="opt">--from <replaceable>file</replaceable></arg>

          <arg choice="req"><replaceable>instancename</replaceable></arg>

          <arg choice="req"

            rep="repeat"><replaceable>tag</replaceable></arg>

        </cmdsynopsis>

        <para>

          Add tags to the given instance. If any of the tags contains

          invalid characters, the entire operation will abort.

        </para>

        <para>

          If the <option>--from</option> option is given, the list of

          tags will be extended with the contents of that file (each

          line becomes a tag). In this case, there is not need to pass

          tags on the command line (if you do, both sources will be

          used). A file name of - will be interpreted as stdin.

        </para>

      </refsect3>

      <refsect3>

        <title>LIST-TAGS</title>

        <cmdsynopsis>

          <command>list-tags</command>

          <arg choice="req"><replaceable>instancename</replaceable></arg>

        </cmdsynopsis>

        <para>List the tags of the given instance.</para>

      </refsect3>

      <refsect3>

        <title>REMOVE-TAGS</title>

        <cmdsynopsis>

          <command>remove-tags</command>

          <arg choice="opt">--from <replaceable>file</replaceable></arg>

          <arg choice="req"><replaceable>instancename</replaceable></arg>

          <arg choice="req"

            rep="repeat"><replaceable>tag</replaceable></arg>

        </cmdsynopsis>

        <para>

          Remove tags from the given instance. If any of the tags are

          not existing on the node, the entire operation will abort.

        </para>

        <para>

          If the <option>--from</option> option is given, the list of

          tags will be extended with the contents of that file (each

          line becomes a tag). In this case, there is not need to pass

          tags on the command line (if you do, both sources will be

          used). A file name of - will be interpreted as stdin.

        </para>

      </refsect3>

    </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:

-->