code.grnet.gr Git - ganeti-local/blob - man/gnt-instance.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>May 29, 2008</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-instance</refentrytitle>">
  10   <!ENTITY dhpackage   "gnt-instance">
  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>2006</year>
  22       <year>2007</year>
  23       <year>2008</year>
  24       <holder>Google Inc.</holder>
  25     </copyright>
  26     &dhdate;
  27   </refentryinfo>
  28   <refmeta>
  29     &dhucpackage;
  30
  31     &dhsection;
  32     <refmiscinfo>ganeti 1.2</refmiscinfo>
  33   </refmeta>
  34   <refnamediv>
  35     <refname>&dhpackage;</refname>
  36
  37     <refpurpose>ganeti instance administration</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 instance
  52       administration in the ganeti system.
  53     </para>
  54
  55   </refsect1>
  56   <refsect1>
  57     <title>COMMANDS</title>
  58
  59     <refsect2>
  60       <title>Creation/removal/querying</title>
  61
  62       <refsect3>
  63         <title>ADD</title>
  64         <cmdsynopsis>
  65           <command>add</command>
  66           <arg>-s <replaceable>disksize</replaceable></arg>
  67           <arg>--swap-size <replaceable>disksize</replaceable></arg>
  68           <arg>-m <replaceable>memsize</replaceable></arg>
  69           <sbr>
  70
  71           <arg>-b <replaceable>bridge</replaceable></arg>
  72           <arg>--mac <replaceable>MAC-address</replaceable></arg>
  73           <sbr>
  74
  75           <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
  76           <arg>--hvm-acpi <replaceable>ACPI-support</replaceable></arg>
  77           <sbr>
  78
  79           <arg>--hvm-pae <replaceable>PAE-support</replaceable></arg>
  80           <sbr>
  81
  82           <arg>--hvm-cdrom-image-path
  83             <replaceable>cdrom-image-path</replaceable></arg>
  84           <sbr>
  85
  86           <arg>--hvm-nic-type <replaceable>NICTYPE</replaceable></arg>
  87           <sbr>
  88
  89           <arg>--hvm-disk-type
  90           <replaceale>DISKTYPE</replaceable></arg>
  91           <sbr>
  92
  93           <arg>--vnc-bind-address
  94             <replaceable>vnc-bind-address</replaceable></arg>
  95           <sbr>
  96
  97           <arg>--kernel<group choice="req">
  98               <arg>default</arg>
  99               <arg><replaceable>kernel_path</replaceable></arg>
 100             </group></arg>
 101           <sbr>
 102
 103           <arg>--initrd<group choice="req">
 104               <arg>default</arg>
 105               <arg>none</arg>
 106               <arg><replaceable>initrd_path</replaceable></arg>
 107             </group></arg>
 108           <sbr>
 109
 110           <arg>--file-storage-dir <replaceable>dir_path</replaceable></arg>
 111           <arg>--file-driver<group choice="req">
 112               <arg>loop</arg>
 113               <arg>blktap</arg>
 114             </group></arg>
 115           <sbr>
 116
 117           <arg choice="req">-t<group choice="req">
 118               <arg>diskless</arg>
 119               <arg>file</arg>
 120               <arg>plain</arg>
 121               <arg>drbd</arg>
 122             </group></arg>
 123           <sbr>
 124
 125           <group choice="req">
 126             <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
 127             <arg>--iallocator <replaceable>name</replaceable></arg>
 128           </group>
 129           <sbr>
 130
 131           <arg choice="req">-o <replaceable>os-type</replaceable></arg>
 132           <sbr>
 133
 134           <arg choice="req"><replaceable>instance</replaceable></arg>
 135         </cmdsynopsis>
 136
 137         <para>
 138           Creates a new instance on the specified
 139           host. <replaceable>instance</replaceable> must be in DNS and
 140           resolve to a IP in the same network as the nodes in the
 141           cluster.
 142         </para>
 143
 144         <para>
 145           The <option>-s</option> option specifies the disk size for
 146           the instance, in mebibytes (defaults to
 147           <constant>20480MiB</constant> =
 148           <constant>20GiB</constant>). You can also use one of the
 149           suffixes <literal>m</literal>, <literal>g</literal> or
 150           <literal>t</literal> to specificy the exact the units used;
 151           these suffixes map to mebibytes, gibibytes and tebibytes.
 152         </para>
 153
 154         <para>
 155           The <option>--swap-size</option> option specifies the swap
 156           disk size (in mebibytes) for the instance (the one presented
 157           as <filename class="devicefile">/dev/sdb</filename>). The
 158           default is <constant>4096MiB</constant>. As for the disk
 159           size, you can specify other suffixes.
 160         </para>
 161
 162         <para>
 163           The <option>-m</option> option specifies the memory size for
 164           the instance, in mebibytes (defaults to 128 MiB). Again, you
 165           can use other suffixes (e.g. <userinput>2g</userinput>).
 166         </para>
 167
 168         <para>
 169           The <option>-o</option> options specifies the operating
 170           system to be installed. The available operating systems can
 171           be listed with <command>gnt-os list</command>.
 172         </para>
 173
 174         <para>
 175           The <option>-b</option> option specifies the bridge to which the
 176           instance will be connected. (defaults to the cluster-wide default
 177           bridge specified at cluster initialization time).
 178         </para>
 179
 180         <para>
 181           The <option>--mac</option> option specifies the MAC address
 182           of the ethernet interface for the instance. If this option
 183           is not specified, a new MAC address is generated randomly with
 184           the configured MAC prefix. The randomly generated MAC
 185           address is guaranteed to be unique among the instances of
 186           this cluster.
 187         </para>
 188
 189         <para>
 190           The <option>--hvm-boot-order</option> option specifies the
 191           boot device order for Xen HVM instances. The boot order is a
 192           string of letters listing the boot devices, with valid
 193           device letters being:
 194         </para>
 195
 196         <para>
 197           <variablelist>
 198             <varlistentry>
 199               <term>a</term>
 200               <listitem>
 201                 <para>
 202                   floppy drive
 203                 </para>
 204               </listitem>
 205             </varlistentry>
 206             <varlistentry>
 207               <term>c</term>
 208               <listitem>
 209                 <para>
 210                   hard disk
 211                 </para>
 212               </listitem>
 213             </varlistentry>
 214             <varlistentry>
 215               <term>d</term>
 216               <listitem>
 217                 <para>
 218                   CDROM drive
 219                 </para>
 220               </listitem>
 221             </varlistentry>
 222             <varlistentry>
 223               <term>n</term>
 224               <listitem>
 225                 <para>
 226                   network boot (PXE)
 227                 </para>
 228               </listitem>
 229             </varlistentry>
 230           </variablelist>
 231         </para>
 232
 233         <para>
 234           The default is not to set an HVM boot order which is
 235           interpreted as 'dc'. This option, like all options starting
 236           with 'hvm', is only relevant for Xen HVM instances and
 237           ignored by all other instance types.
 238         </para>
 239
 240         <para>
 241           The <option>--hvm-acpi</option> option specifies if Xen
 242           should enable ACPI support for this HVM instance. Valid
 243           values are true or false. The default value is false,
 244           disabling ACPI support for this instance.
 245         </para>
 246
 247         <para>
 248           The <option>--hvm-pae</option> option specifies if Xen
 249           should enabled PAE support for this HVM instance. Valid
 250           values are true or false. The default is false, disabling
 251           PAE support for this instance.
 252         </para>
 253
 254         <para>
 255           The <option>--hvm-cdrom-image-path</option> option specifies the
 256           path to the file Xen uses to emulate a virtual CDROM drive
 257           for this HVM instance. Valid values are either an
 258           absolute path to an existing file or None, which disables
 259           virtual CDROM support for this instance. The default is
 260           None, disabling virtual CDROM support.
 261         </para>
 262
 263         <para>
 264           The <option>--hvm-nic-type</option> specifies the NIC type
 265           Xen should use for this HVM instance. Valid choices are
 266           rtl8139, ne2k_pci, ne2k_isa and paravirtual with rtl8139
 267           as the default. The paravirtual setting is intended for use
 268           with the GPL PV drivers inside HVM Windows instances.
 269         </para>
 270
 271         <para>
 272           The <option>--hvm-disk-type</option> specifies the disk type
 273           Xen should use for the HVM instance. Valid choices are ioemu
 274           and paravirtual with ioemu as the default. The paravirtual
 275           setting is intended for use with the GPL PV drivers inside
 276           HVM Windows instances.
 277         </para>
 278
 279         <para>
 280           The <option>--vnc-bind-address</option> option specifies the
 281           address that the VNC listener for this instance should bind
 282           to. Valid values are IPv4 addresses. Use the address 0.0.0.0
 283           to bind to all available interfaces (this is the default)
 284           or specify the address of one of the interfaces on the node
 285           to restrict listening to that interface.
 286         </para>
 287
 288         <para>
 289           The <option>--iallocator</option> option specifies the instance
 290           allocator plugin to use. If you pass in this option the allocator
 291           will select nodes for this instance automatically, so you don't need
 292           to pass them with the <option>-n</option> option. For more
 293           information please refer to the instance allocator documentation.
 294         </para>
 295
 296         <para>
 297           The <option>--kernel</option> option allows the instance to
 298           use a custom kernel (if a filename is passed) or to use the
 299           default kernel (<filename>@CUSTOM_XEN_KERNEL@</filename>), if the
 300           string <constant>default</constant> is passed.
 301         </para>
 302
 303         <para>
 304           The <option>--initrd</option> option is similar: it allows
 305           the instance to use a custom initrd (if a filename is
 306           passed) or to use the default initrd
 307           (<filename>@CUSTOM_XEN_INITRD@</filename>), if the string
 308           <constant>default</constant> is passed, or to disable the
 309           use of an initrd, if the string <constant>none</constant> is
 310           passed. Note that in the case the instance is set to use the
 311           default initrd and it doesn't exist, it will be silently
 312           ignored; if the instance is set to use a custom initrd and
 313           it doesn't exist, this will be treated as an error and will
 314           prevent the startup of the instance.
 315         </para>
 316
 317         <para>
 318           The <option>-t</option> options specifies the disk layout type for
 319           the instance. The available choices are:
 320           <variablelist>
 321             <varlistentry>
 322               <term>diskless</term>
 323               <listitem>
 324                 <para>
 325                   This creates an instance with no disks. Its useful for
 326                   testing only (or other special cases).
 327                 </para>
 328               </listitem>
 329             </varlistentry>
 330             <varlistentry>
 331               <term>file</term>
 332               <listitem>
 333                 <para>Disk devices will be regular files.</para>
 334               </listitem>
 335             </varlistentry>
 336             <varlistentry>
 337               <term>plain</term>
 338               <listitem>
 339                 <para>Disk devices will be logical volumes.</para>
 340               </listitem>
 341             </varlistentry>
 342             <varlistentry>
 343               <term>drbd</term>
 344               <listitem>
 345                 <para>
 346                   Disk devices will be drbd (version 8.x) on top of
 347                   lvm volumes.
 348                 </para>
 349               </listitem>
 350             </varlistentry>
 351           </variablelist>
 352         </para>
 353
 354         <para>
 355           The optional second value of the <option>--node</option> is used for
 356           the drbd template type and specifies the remote node.
 357         </para>
 358
 359         <para>
 360           If you do not want gnt-instance to wait for the disk mirror
 361           to be synced, use the <option>--no-wait-for-sync</option>
 362           option.
 363         </para>
 364
 365         <para>
 366           The <option>--file-storage-dir</option> specifies the relative path
 367           under the cluster-wide file storage directory to store file-based
 368           disks. It is useful for having different subdirectories for
 369           different instances. The full path of the directory where the disk
 370           files are stored will consist of cluster-wide file storage directory
 371           + optional subdirectory + instance name. Example:
 372           /srv/ganeti/file-storage/mysubdir/instance1.example.com. This option
 373           is only relevant for instances using the file storage backend.
 374         </para>
 375
 376         <para>
 377           The <option>--file-driver</option> specifies the driver to use for
 378           file-based disks. Note that currently these drivers work with the
 379           xen hypervisor only. This option is only relevant for instances using
 380           the file storage backend. The available choices are:
 381           <variablelist>
 382             <varlistentry>
 383               <term>loop</term>
 384               <listitem>
 385                 <para>Kernel loopback driver.</para>
 386               </listitem>
 387             </varlistentry>
 388             <varlistentry>
 389               <term>blktap</term>
 390               <listitem>
 391                 <para>blktap driver.</para>
 392               </listitem>
 393             </varlistentry>
 394           </variablelist>
 395         </para>
 396
 397         <para>
 398           The loop driver uses loopback devices to access the filesystem
 399           within the file. However, running I/O intensive applications
 400           in your instance using the loop driver might result in slowdowns.
 401           Furthermore, if you use the loopback driver consider increasing
 402           the maximum amount of loopback devices (on most systems it's 8)
 403           using the max_loop param.
 404         </para>
 405
 406         <para>
 407           In order to be able to use the blktap driver you should check
 408           if the 'blktapctrl' user space disk agent is running (usually
 409           automatically started via xend). This user-level disk I/O
 410           interface has the advantage of better performance. Especially
 411           if you use a network file system (e.g. NFS) to store your instances
 412           this is the recommended choice.
 413         </para>
 414
 415         <para>
 416           Example:
 417           <screen>
 418 # gnt-instance add -t file -s 30g -m 512 -o debian-etch \
 419   -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
 420 # gnt-instance add -t plain -s 30g -m 512 -o debian-etch \
 421   -n node1.example.com instance1.example.com
 422 # gnt-instance add -t drbd -s 30g -m 512 -o debian-etch \
 423   -n node1.example.com:node2.example.com instance2.example.com
 424           </screen>
 425         </para>
 426       </refsect3>
 427
 428       <refsect3>
 429         <title>REMOVE</title>
 430
 431         <cmdsynopsis>
 432           <command>remove</command>
 433           <arg>--ignore-failures</arg>
 434           <arg choice="req"><replaceable>instance</replaceable></arg>
 435         </cmdsynopsis>
 436
 437         <para>
 438           Remove an instance. This will remove all data from the
 439           instance and there is <emphasis>no way back</emphasis>. If
 440           you are not sure if you use an instance again, use
 441           <command>shutdown</command> first and leave it in the
 442           shutdown state for a while.
 443
 444         </para>
 445
 446         <para>
 447           The <option>--ignore-failures</option> option will cause the
 448           removal to proceed even in the presence of errors during the
 449           removal of the instance (e.g. during the shutdown or the
 450           disk removal). If this option is not given, the command will
 451           stop at the first error.
 452         </para>
 453
 454         <para>
 455           Example:
 456           <screen>
 457 # gnt-instance remove instance1.example.com
 458           </screen>
 459         </para>
 460       </refsect3>
 461
 462       <refsect3>
 463         <title>LIST</title>
 464
 465         <cmdsynopsis>
 466           <command>list</command>
 467           <arg>--no-headers</arg>
 468           <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
 469           <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>
 470         </cmdsynopsis>
 471
 472         <para>
 473           Shows the currently configured instances with memory usage,
 474           disk usage, the node they are running on, and the CPU time,
 475           counted in seconds, used by each instance since its latest
 476           restart.
 477         </para>
 478
 479         <para>
 480           The <option>--no-headers</option> option will skip the
 481           initial header line. The <option>--separator</option> option
 482           takes an argument which denotes what will be used between
 483           the output fields. Both these options are to help scripting.
 484         </para>
 485
 486         <para>
 487           The <option>-o</option> option takes a comma-separated list
 488           of output fields. The available fields and their meaning
 489           are:
 490           <variablelist>
 491             <varlistentry>
 492               <term>name</term>
 493               <listitem>
 494                 <simpara>the instance name</simpara>
 495               </listitem>
 496             </varlistentry>
 497             <varlistentry>
 498               <term>os</term>
 499               <listitem>
 500                 <simpara>the OS of the instance</simpara>
 501               </listitem>
 502             </varlistentry>
 503             <varlistentry>
 504               <term>pnode</term>
 505               <listitem>
 506                 <simpara>the primary node of the instance</simpara>
 507               </listitem>
 508             </varlistentry>
 509             <varlistentry>
 510               <term>snodes</term>
 511               <listitem>
 512                 <simpara>comma-separated list of secondary nodes for the
 513                   instance; usually this will be just one node</simpara>
 514               </listitem>
 515             </varlistentry>
 516             <varlistentry>
 517               <term>admin_state</term>
 518               <listitem>
 519                 <simpara>the desired state of the instance (either "yes"
 520                   or "no" denoting the instance should run or
 521                   not)</simpara>
 522               </listitem>
 523             </varlistentry>
 524             <varlistentry>
 525               <term>admin_ram</term>
 526               <listitem>
 527                 <simpara>the desired memory for the instance</simpara>
 528               </listitem>
 529             </varlistentry>
 530             <varlistentry>
 531               <term>disk_template</term>
 532               <listitem>
 533                 <simpara>the disk template of the instance</simpara>
 534               </listitem>
 535             </varlistentry>
 536             <varlistentry>
 537               <term>oper_state</term>
 538               <listitem>
 539                 <simpara>the actual state of the instance; can be
 540                 one of the values "running", "stopped", "(node
 541                 down)"</simpara>
 542               </listitem>
 543             </varlistentry>
 544             <varlistentry>
 545               <term>status</term>
 546               <listitem>
 547                 <simpara>combined form of admin_state and oper_stat;
 548                 this can be one of:
 549                 <computeroutput>ERROR_nodedown</computeroutput> if the
 550                 node of the instance is down,
 551                 <computeroutput>ERROR_down</computeroutput> if the
 552                 instance should run but is down,
 553                 <computeroutput>ERROR_up</computeroutput> if the
 554                 instance should be stopped but is actually running,
 555                 <computeroutput>ADMIN_down</computeroutput> if the
 556                 instance has been stopped (and is stopped) and
 557                 <computeroutput>running</computeroutput> if the
 558                 instance is set to be running (and is
 559                 running)</simpara>
 560               </listitem>
 561             </varlistentry>
 562             <varlistentry>
 563               <term>oper_ram</term>
 564               <listitem>
 565                 <simpara>the actual memory usage of the instance as seen
 566                   by the hypervisor</simpara>
 567               </listitem>
 568             </varlistentry>
 569             <varlistentry>
 570               <term>ip</term>
 571               <listitem>
 572                 <simpara>the ip address ganeti recognizes as associated with
 573                 the instance interface</simpara>
 574               </listitem>
 575             </varlistentry>
 576             <varlistentry>
 577               <term>mac</term>
 578               <listitem>
 579                 <simpara>the instance interface MAC address</simpara>
 580               </listitem>
 581             </varlistentry>
 582             <varlistentry>
 583               <term>bridge</term>
 584               <listitem>
 585                 <simpara>bridge the instance is connected to
 586                 </simpara>
 587               </listitem>
 588             </varlistentry>
 589             <varlistentry>
 590               <term>sda_size</term>
 591               <listitem>
 592                 <simpara>the size of the instance's first disk</simpara>
 593               </listitem>
 594             </varlistentry>
 595             <varlistentry>
 596               <term>sdb_size</term>
 597               <listitem>
 598                 <simpara>the size of the instance's second disk</simpara>
 599               </listitem>
 600             </varlistentry>
 601             <varlistentry>
 602               <term>vcpus</term>
 603               <listitem>
 604                 <simpara>the number of VCPUs allocated to the
 605                 instance</simpara>
 606               </listitem>
 607             </varlistentry>
 608             <varlistentry>
 609               <term>tags</term>
 610               <listitem>
 611                 <simpara>comma-separated list of the instances's
 612                 tags</simpara>
 613               </listitem>
 614             </varlistentry>
 615           </variablelist>
 616         </para>
 617
 618         <para>
 619           If the value of the option starts with the character
 620           <constant>+</constant>, the new fields will be added to the
 621           default list. This allows to quickly see the default list
 622           plus a few other fields, instead of retyping the entire list
 623           of fields.
 624         </para>
 625
 626         <para>
 627           There is a subtle grouping about the available output
 628           fields: all fields except for <option>oper_state</option>,
 629           <option>oper_ram</option> and <option>status</option> are
 630           configuration value and not run-time values. So if you don't
 631           select any of the these fields, the query will be satisfied
 632           instantly from the cluster configuration, without having to
 633           ask the remote nodes for the data. This can be helpful for
 634           big clusters when you only want some data and it makes sense
 635           to specify a reduced set of output fields.
 636         </para>
 637
 638         <para>The default output field list is:
 639           <simplelist type="inline">
 640             <member>name</member>
 641             <member>os</member>
 642             <member>pnode</member>
 643             <member>admin_state</member>
 644             <member>oper_state</member>
 645             <member>oper_ram</member>
 646           </simplelist>.
 647         </para>
 648       </refsect3>
 649
 650       <refsect3>
 651         <title>INFO</title>
 652
 653         <cmdsynopsis>
 654           <command>info</command>
 655           <arg rep="repeat"><replaceable>instance</replaceable></arg>
 656         </cmdsynopsis>
 657
 658         <para>
 659           Show detailed information about the (given) instances. This
 660           is different from <command>list</command> as it shows
 661           detailed data about the instance's disks (especially useful
 662           for drbd disk template).
 663         </para>
 664       </refsect3>
 665
 666       <refsect3>
 667         <title>MODIFY</title>
 668
 669         <cmdsynopsis>
 670           <command>modify</command>
 671           <arg choice="opt">-m <replaceable>memsize</replaceable></arg>
 672           <arg choice="opt">-p <replaceable>vcpus</replaceable></arg>
 673           <arg choice="opt">-i <replaceable>ip</replaceable></arg>
 674           <arg choice="opt">-b <replaceable>bridge</replaceable></arg>
 675           <arg choice="opt">--mac <replaceable>MAC-address</replaceable></arg>
 676           <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
 677           <arg>--hvm-acpi <replaceable>ACPI-support</replaceable></arg>
 678           <arg>--hvm-pae <replaceable>PAE-support</replaceable></arg>
 679           <arg>--hvm-cdrom-image-path
 680             <replaceable>cdrom-image-path</replaceable></arg>
 681           <arg>--hvm-nic-type <replaceable>NICTYPE</replaceable></arg>
 682           <arg>--hvm-disk-type <replaceable>DISKTYPE</replaceable></arg>
 683           <arg>--vnc-bind-address
 684             <replaceable>vnc-bind-address</replaceable></arg>
 685
 686           <sbr>
 687           <arg>--kernel <group choice="req">
 688               <arg>default</arg>
 689               <arg><replaceable>kernel_path</replaceable></arg>
 690             </group></arg>
 691           <sbr>
 692           <arg>--initrd <group choice="req">
 693               <arg>default</arg>
 694               <arg>none</arg>
 695               <arg><replaceable>initrd_path</replaceable></arg>
 696             </group> </arg>
 697           <sbr>
 698           <arg choice="req"><replaceable>instance</replaceable></arg>
 699         </cmdsynopsis>
 700
 701         <para>
 702           Modify the memory size, number of vcpus, ip address, MAC
 703           address and/or bridge for an instance.
 704         </para>
 705
 706         <para>
 707           The memory size is given in MiB. Note that you need to give
 708           at least one of the arguments, otherwise the command
 709           complains.
 710         </para>
 711
 712         <para>
 713           The <option>--kernel</option>, <option>--initrd</option>
 714           and <option>--hvm-boot-order</option>
 715           options are described in the <command>add</command> command.
 716         </para>
 717
 718         <para>
 719           Additionally, the HVM boot order can be reset to the default
 720           values by using <option>--hvm-boot-order=default</option>.
 721         </para>
 722
 723         <para>
 724           The <option>--hvm-acpi</option> option specifies if Xen
 725           should enable ACPI support for this HVM instance. Valid
 726           values are true or false.
 727         </para>
 728
 729         <para>
 730           The <option>--hvm-pae</option> option specifies if Xen
 731           should enabled PAE support for this HVM instance. Valid
 732           values are true or false.
 733         </para>
 734
 735         <para>
 736           The <option>--hvm-cdrom-image-path</option> specifies the
 737           path to the file xen uses to emulate a virtual CDROM drive
 738           for this HVM instance. Valid values are either an
 739           absolute path to an existing file or None, which disables
 740           virtual CDROM support for this instance.
 741         </para>
 742
 743         <para>
 744           The <option>--hvm-nic-type</option> specifies the NIC type
 745           Xen should use for this HVM instance. Valid choices are
 746           rtl8139, ne2k_pci, ne2k_isa and paravirtual with rtl8139
 747           as the default. The paravirtual setting is intended for use
 748           with the GPL PV drivers inside HVM Windows instances.
 749         </para>
 750
 751         <para>
 752           The <option>--hvm-disk-type</option> specifies the disk type
 753           Xen should use for the HVM instance. Valid choices are ioemu
 754           and paravirtual with ioemu as the default. The paravirtual
 755           setting is intended for use with the GPL PV drivers inside
 756           HVM Windows instances.
 757         </para>
 758
 759         <para>
 760           The <option>--vnc-bind-address</option> specifies the
 761           address that the VNC listener for this instance should bind
 762           to. Valid values are IPv4 addresses. Use the address 0.0.0.0
 763           to bind to all available interfaces.
 764         </para>
 765
 766         <para>
 767           All the changes take effect at the next restart. If the
 768           instance is running, there is no effect on the instance.
 769         </para>
 770       </refsect3>
 771
 772       <refsect3>
 773         <title>REINSTALL</title>
 774
 775         <cmdsynopsis>
 776           <command>reinstall</command>
 777           <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
 778           <arg choice="opt">-f <replaceable>force</replaceable></arg>
 779           <arg choice="req"><replaceable>instance</replaceable></arg>
 780         </cmdsynopsis>
 781
 782         <para>
 783           Reinstalls the operating system on the given instance. The instance
 784           must be stopped when running this command. If the
 785           <option>--os-type</option> is specified, the operating system is
 786           changed.
 787         </para>
 788       </refsect3>
 789
 790       <refsect3>
 791         <title>RENAME</title>
 792
 793         <cmdsynopsis>
 794           <command>rename</command>
 795           <arg>--no-ip-check</arg>
 796           <arg choice="req"><replaceable>instance</replaceable></arg>
 797           <arg choice="req"><replaceable>new_name</replaceable></arg>
 798         </cmdsynopsis>
 799
 800         <para>
 801           Renames the given instance. The instance must be stopped
 802           when running this command. The requirements for the new name
 803           are the same as for adding an instance: the new name must be
 804           resolvable and the IP it resolves to must not be reachable
 805           (in order to prevent duplicate IPs the next time the
 806           instance is started). The IP test can be skipped if the
 807           <option>--no-ip-check</option> option is passed.
 808         </para>
 809       </refsect3>
 810
 811     </refsect2>
 812
 813     <refsect2>
 814       <title>Starting/stopping/connecting to console</title>
 815
 816       <refsect3>
 817         <title>STARTUP</title>
 818
 819         <cmdsynopsis>
 820           <command>startup</command>
 821           <arg>--extra=<replaceable>PARAMS</replaceable></arg>
 822           <arg>--force</arg>
 823           <sbr>
 824           <group choice="opt">
 825             <arg>--instance</arg>
 826             <arg>--node</arg>
 827             <arg>--primary</arg>
 828             <arg>--secondary</arg>
 829             <arg>--all</arg>
 830           </group>
 831           <sbr>
 832           <arg choice="opt"
 833           rep="repeat"><replaceable>name</replaceable></arg>
 834         </cmdsynopsis>
 835
 836         <para>
 837           Starts one or more instances, depending on the following
 838           options. The four available modes are:
 839           <variablelist>
 840             <varlistentry>
 841               <term><option>--instance</option></term>
 842               <listitem>
 843                 <simpara>will start the instances given as arguments
 844                 (at least one argument required); this is the default
 845                 selection</simpara>
 846               </listitem>
 847             </varlistentry>
 848             <varlistentry>
 849               <term>--node</term>
 850               <listitem>
 851                 <simpara>will start the instances who have the given
 852                 node as either primary or secondary</simpara>
 853               </listitem>
 854             </varlistentry>
 855             <varlistentry>
 856               <term><option>--primary</option></term>
 857               <listitem>
 858                 <simpara>will start all instances whose primary node
 859                 is in the list of nodes passed as arguments (at least
 860                 one node required)</simpara>
 861               </listitem>
 862             </varlistentry>
 863             <varlistentry>
 864               <term><option>--secondary</option></term>
 865               <listitem>
 866                 <simpara>will start all instances whose secondary node
 867                 is in the list of nodes passed as arguments (at least
 868                 one node required)</simpara>
 869               </listitem>
 870             </varlistentry>
 871             <varlistentry>
 872               <term>--all</term>
 873               <listitem>
 874                 <simpara>will start all instances in the cluster (no
 875                 arguments accepted)</simpara>
 876               </listitem>
 877             </varlistentry>
 878           </variablelist>
 879         </para>
 880
 881         <para>
 882           Note that although you can pass more than one selection
 883           option, the last one wins, so in order to guarantee the
 884           desired result, don't pass more than one such option.
 885         </para>
 886
 887         <para>
 888           The <option>--extra</option> option is used to pass
 889           additional argument to the instance's kernel for this start
 890           only. Currently there is no way to specify a persistent set
 891           of arguments (beside the one hardcoded). Note that this may
 892           not apply to all virtualization types.
 893         </para>
 894
 895         <para>
 896           Use <option>--force</option> to start even if secondary disks are
 897           failing.
 898         </para>
 899
 900         <para>
 901           Example:
 902           <screen>
 903 # gnt-instance start instance1.example.com
 904 # gnt-instance start --extra single test1.example.com
 905 # gnt-instance start --node node1.example.com node2.example.com
 906 # gnt-instance start --all
 907           </screen>
 908         </para>
 909       </refsect3>
 910
 911       <refsect3>
 912         <title>SHUTDOWN</title>
 913
 914         <cmdsynopsis>
 915           <command>shutdown</command>
 916           <sbr>
 917           <group choice="opt">
 918             <arg>--instance</arg>
 919             <arg>--node</arg>
 920             <arg>--primary</arg>
 921             <arg>--secondary</arg>
 922             <arg>--all</arg>
 923           </group>
 924           <sbr>
 925
 926           <arg choice="opt"
 927           rep="repeat"><replaceable>name</replaceable></arg>
 928         </cmdsynopsis>
 929
 930         <para>
 931           Stops one or more instances. If the instance cannot be
 932           cleanly stopped during a hardcoded interval (currently 2
 933           minutes), it will forcibly stop the instance (equivalent to
 934           switching off the power on a physical machine).
 935         </para>
 936
 937         <para>
 938           The <option>--instance</option>, <option>--node</option>,
 939           <option>--primary</option>, <option>--secondary</option> and
 940           <option>--all</option> options are similar as for the
 941           <command>startup</command> command and they influence the
 942           actual instances being shutdown.
 943         </para>
 944
 945         <para>
 946           Example:
 947           <screen>
 948 # gnt-instance shutdown instance1.example.com
 949 # gnt-instance shutdown --all
 950           </screen>
 951         </para>
 952       </refsect3>
 953
 954       <refsect3>
 955         <title>REBOOT</title>
 956
 957         <cmdsynopsis>
 958           <command>reboot</command>
 959           <sbr>
 960           <arg>--extra=<replaceable>PARAMS</replaceable></arg>
 961           <sbr>
 962           <arg>--type=<replaceable>REBOOT-TYPE</replaceable></arg>
 963           <sbr>
 964           <arg>--ignore-secondaries</arg>
 965           <sbr>
 966           <arg>--force-multiple</arg>
 967           <sbr>
 968           <group choice="opt">
 969             <arg>--instance</arg>
 970             <arg>--node</arg>
 971             <arg>--primary</arg>
 972             <arg>--secondary</arg>
 973             <arg>--all</arg>
 974           </group>
 975           <sbr>
 976
 977           <arg choice="opt"
 978           rep="repeat"><replaceable>name</replaceable></arg>
 979         </cmdsynopsis>
 980
 981         <para>
 982           Reboots one or more instances. The type of reboot depends on
 983           the value of <option>--type</option>. A soft reboot does a
 984           hypervisor reboot, a hard reboot does a instance stop,
 985           recreates the hypervisor config for the instance and
 986           starts the instance. A full reboot does the equivalent
 987           of <command>gnt-instance shutdown &amp;&amp; gnt-instance
 988           startup</command>. The default is soft reboot.
 989         </para>
 990
 991         <para>
 992           For the hard reboot the option
 993           <option>--ignore-secondaries</option> ignores errors for the
 994           secondary node while re-assembling the instance disks.
 995         </para>
 996
 997         <para>
 998           The <option>--instance</option>, <option>--node</option>,
 999           <option>--primary</option>, <option>--secondary</option> and
1000           <option>--all</option> options are similar as for the
1001           <command>startup</command> command and they influence the
1002           actual instances being rebooted.
1003         </para>
1004
1005         <para>
1006           Use the <option>--force-multiple</option> option to keep
1007           gnt-instance from asking for confirmation when more than one
1008           instance is affected.
1009         </para>
1010
1011         <para>
1012           Example:
1013           <screen>
1014 # gnt-instance reboot instance1.example.com
1015 # gnt-instance reboot --type=full instance1.example.com
1016           </screen>
1017         </para>
1018       </refsect3>
1019
1020       <refsect3>
1021         <title>CONSOLE</title>
1022         <cmdsynopsis>
1023           <command>console</command>
1024           <arg choice="opt">--show-cmd</arg>
1025           <arg choice="req"><replaceable>instance</replaceable></arg>
1026         </cmdsynopsis>
1027
1028         <para>
1029           Connects to the console of the given instance. If the instance
1030           is not up, an error is returned. Use the <option>--show-cmd</option>
1031           option to display the command instead of executing it.
1032         </para>
1033
1034         <para>
1035           Example:
1036           <screen>
1037 # gnt-instance console instance1.example.com
1038           </screen>
1039         </para>
1040       </refsect3>
1041
1042     </refsect2>
1043
1044     <refsect2>
1045       <title>Disk management</title>
1046
1047       <refsect3>
1048         <title>REPLACE-DISKS</title>
1049
1050         <cmdsynopsis>
1051           <command>replace-disks</command>
1052
1053           <group choice="req">
1054             <arg>--iallocator <replaceable>name</replaceable></arg>
1055             <arg>--new-secondary <replaceable>NODE</replaceable></arg>
1056           </group>
1057           <sbr>
1058
1059           <arg choice="opt">-s</arg>
1060           <arg choice="req"><replaceable>instance</replaceable></arg>
1061         </cmdsynopsis>
1062
1063         <cmdsynopsis>
1064           <command>replace-disks</command>
1065
1066           <group>
1067           <arg choice="req">-s</arg>
1068           <arg choice="req">-p</arg>
1069           </group>
1070           <arg choice="req"><replaceable>instance</replaceable></arg>
1071         </cmdsynopsis>
1072
1073         <para>
1074           This command is a generalized form for adding and replacing
1075           disks. It is currently only valid for the mirrored (DRBD)
1076           disk template.
1077         </para>
1078
1079         <para>
1080           The first form will do a secondary node change, while the
1081           second form will replace the disks on either the primary
1082           (<option>-p</option>) or the secondary (<option>-s</option>)
1083           node of the instance only, without changing the node.
1084         </para>
1085
1086         <para>
1087           Specifying <option>--iallocator</option> enables secondary node
1088           replacement and and makes the new secondary be selected automatically
1089           by the specified allocator plugin.
1090         </para>
1091       </refsect3>
1092
1093       <refsect3>
1094         <title>ACTIVATE-DISKS</title>
1095
1096         <cmdsynopsis>
1097           <command>activate-disks</command>
1098           <arg choice="req"><replaceable>instance</replaceable></arg>
1099         </cmdsynopsis>
1100         <para>
1101           Activates the block devices of the given instance. If
1102           successful, the command will show the location and name of
1103           the block devices:
1104           <screen>
1105 node1.example.com:sda:/dev/drbd0
1106 node1.example.com:sdb:/dev/drbd1
1107           </screen>
1108
1109           In this example, <emphasis>node1.example.com</emphasis> is
1110           the name of the node on which the devices have been
1111           activated. The <emphasis>sda</emphasis> and
1112           <emphasis>sdb</emphasis> are the names of the block devices
1113           inside the instance. <emphasis>/dev/drbd0</emphasis> and
1114           <emphasis>/dev/drbd1</emphasis> are the names of the block
1115           devices as visible on the node.
1116         </para>
1117
1118         <para>
1119           Note that it is safe to run this command while the instance
1120           is already running.
1121         </para>
1122       </refsect3>
1123
1124       <refsect3>
1125         <title>DEACTIVATE-DISKS</title>
1126
1127         <cmdsynopsis>
1128           <command>deactivate-disks</command>
1129           <arg choice="req"><replaceable>instance</replaceable></arg>
1130         </cmdsynopsis>
1131         <para>
1132           De-activates the block devices of the given instance. Note
1133           that if you run this command for an instance with a drbd
1134           disk template, while it is running, it will not be able to
1135           shutdown the block devices on the primary node, but it will
1136           shutdown the block devices on the secondary nodes, thus
1137           breaking the replication.
1138         </para>
1139
1140       </refsect3>
1141
1142       <refsect3>
1143         <title>GROW-DISK</title>
1144         <cmdsynopsis>
1145           <command>grow-disk</command>
1146           <arg choice="req"><replaceable>instance</replaceable></arg>
1147           <arg choice="req"><replaceable>disk</replaceable></arg>
1148           <arg choice="req"><replaceable>amount</replaceable></arg>
1149         </cmdsynopsis>
1150
1151         <para>
1152           Grows an instance's disk. This is only possible for
1153           instances having a <literal>plain</literal> or
1154           <literal>drbd</literal> disk template.
1155         </para>
1156
1157         <para>
1158           Note that this command only change the block device size; it
1159           will not grow the actual filesystems, partitions, etc. that
1160           live on that disk. Usually, you will need to:
1161           <orderedlist>
1162             <listitem>
1163               <simpara>use <command>gnt-instance grow-disk</command></simpara>
1164             </listitem>
1165             <listitem>
1166               <simpara>reboot the instance (later, at a convenient
1167               time)</simpara>
1168             </listitem>
1169             <listitem>
1170               <simpara>use a filesystem resizer, such as
1171               <citerefentry> <refentrytitle>ext2online</refentrytitle>
1172               <manvolnum>8</manvolnum> </citerefentry> or
1173               <citerefentry> <refentrytitle>xfs_growfs</refentrytitle>
1174               <manvolnum>8</manvolnum> </citerefentry> to resize the
1175               filesystem, or use <citerefentry>
1176               <refentrytitle>fdisk</refentrytitle>
1177               <manvolnum>8</manvolnum> </citerefentry> to change the
1178               partition table on the disk
1179               </simpara>
1180             </listitem>
1181           </orderedlist>
1182         </para>
1183
1184
1185         <para>
1186           The <replaceable>disk</replaceable> argument is either
1187           <literal>sda</literal> or <literal>sdb</literal>. The
1188           <replaceable>amount</replaceable> argument is given either
1189           as a number (and it represents the amount to increase the
1190           disk with in mebibytes) or can be given similar to the
1191           arguments in the create instance operation, with a suffix
1192           denoting the unit.
1193         </para>
1194
1195         <para>
1196           Note that the disk grow operation might complete on one node
1197           but fail on the other; this will leave the instance with
1198           different-sized LVs on the two nodes, but this will not
1199           create problems (except for unused space).
1200         </para>
1201
1202         <para>Example (increasing sda for instance1 with 16GiB):
1203           <screen>
1204 # gnt-instance grow-disk instance1.example.com sda 16g
1205           </screen>
1206         </para>
1207
1208         <para>
1209           Also note that disk shrinking will not be supported; use
1210           <command>gnt-backup export</command> and then
1211           <command>gnt-backup import</command> to reduce the disk size
1212           of an instance.
1213         </para>
1214       </refsect3>
1215
1216     </refsect2>
1217
1218     <refsect2>
1219       <title>Recovery</title>
1220
1221       <refsect3>
1222         <title>FAILOVER</title>
1223
1224         <cmdsynopsis>
1225           <command>failover</command>
1226           <arg>-f</arg>
1227           <arg>--ignore-consistency</arg>
1228           <arg choice="req"><replaceable>instance</replaceable></arg>
1229         </cmdsynopsis>
1230
1231         <para>
1232           Failover will fail the instance over its secondary
1233           node. This works only for instances having a drbd disk
1234           template.
1235         </para>
1236
1237         <para>
1238           Normally the failover will check the consistency of the
1239           disks before failing over the instance. If you are trying to
1240           migrate instances off a dead node, this will fail. Use the
1241           <option>--ignore-consistency</option> option for this
1242           purpose. Note that this option can be dangerous as errors in
1243           shutting down the instance will be ignored, resulting in
1244           possibly having the instance running on two machines in
1245           parallel (on disconnected DRBD drives).
1246         </para>
1247
1248         <para>
1249           Example:
1250           <screen>
1251 # gnt-instance failover instance1.example.com
1252           </screen>
1253         </para>
1254       </refsect3>
1255
1256     </refsect2>
1257
1258     <refsect2>
1259       <title>TAGS</title>
1260
1261     <refsect3>
1262         <title>ADD-TAGS</title>
1263
1264         <cmdsynopsis>
1265           <command>add-tags</command>
1266           <arg choice="opt">--from <replaceable>file</replaceable></arg>
1267           <arg choice="req"><replaceable>instancename</replaceable></arg>
1268           <arg choice="req"
1269             rep="repeat"><replaceable>tag</replaceable></arg>
1270         </cmdsynopsis>
1271
1272         <para>
1273           Add tags to the given instance. If any of the tags contains
1274           invalid characters, the entire operation will abort.
1275         </para>
1276         <para>
1277           If the <option>--from</option> option is given, the list of
1278           tags will be extended with the contents of that file (each
1279           line becomes a tag). In this case, there is not need to pass
1280           tags on the command line (if you do, both sources will be
1281           used). A file name of - will be interpreted as stdin.
1282         </para>
1283       </refsect3>
1284
1285       <refsect3>
1286         <title>LIST-TAGS</title>
1287
1288         <cmdsynopsis>
1289           <command>list-tags</command>
1290           <arg choice="req"><replaceable>instancename</replaceable></arg>
1291         </cmdsynopsis>
1292
1293         <para>List the tags of the given instance.</para>
1294       </refsect3>
1295
1296       <refsect3>
1297         <title>REMOVE-TAGS</title>
1298         <cmdsynopsis>
1299           <command>remove-tags</command>
1300           <arg choice="opt">--from <replaceable>file</replaceable></arg>
1301           <arg choice="req"><replaceable>instancename</replaceable></arg>
1302           <arg choice="req"
1303             rep="repeat"><replaceable>tag</replaceable></arg>
1304         </cmdsynopsis>
1305
1306         <para>
1307           Remove tags from the given instance. If any of the tags are
1308           not existing on the node, the entire operation will abort.
1309         </para>
1310
1311         <para>
1312           If the <option>--from</option> option is given, the list of
1313           tags will be extended with the contents of that file (each
1314           line becomes a tag). In this case, there is not need to pass
1315           tags on the command line (if you do, both sources will be
1316           used). A file name of - will be interpreted as stdin.
1317         </para>
1318       </refsect3>
1319
1320     </refsect2>
1321
1322   </refsect1>
1323
1324   &footer;
1325
1326 </refentry>
1327
1328 <!-- Keep this comment at the end of the file
1329 Local variables:
1330 mode: sgml
1331 sgml-omittag:t
1332 sgml-shorttag:t
1333 sgml-minimize-attributes:nil
1334 sgml-always-quote-attributes:t
1335 sgml-indent-step:2
1336 sgml-indent-data:t
1337 sgml-parent-document:nil
1338 sgml-default-dtd-file:nil
1339 sgml-exposed-tags:nil
1340 sgml-local-catalogs:nil
1341 sgml-local-ecat-files:nil
1342 End:
1343 -->