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           <replaceable>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             <varlistentry>
 616               <term>serial_no</term>
 617               <listitem>
 618                 <simpara>the so called 'serial number' of the
 619                 instance; this is a numeric field that is incremented
 620                 each time the instance is modified, and it can be used
 621                 to detect modifications</simpara>
 622               </listitem>
 623             </varlistentry>
 624           </variablelist>
 625         </para>
 626
 627         <para>
 628           If the value of the option starts with the character
 629           <constant>+</constant>, the new fields will be added to the
 630           default list. This allows to quickly see the default list
 631           plus a few other fields, instead of retyping the entire list
 632           of fields.
 633         </para>
 634
 635         <para>
 636           There is a subtle grouping about the available output
 637           fields: all fields except for <option>oper_state</option>,
 638           <option>oper_ram</option> and <option>status</option> are
 639           configuration value and not run-time values. So if you don't
 640           select any of the these fields, the query will be satisfied
 641           instantly from the cluster configuration, without having to
 642           ask the remote nodes for the data. This can be helpful for
 643           big clusters when you only want some data and it makes sense
 644           to specify a reduced set of output fields.
 645         </para>
 646
 647         <para>The default output field list is:
 648           <simplelist type="inline">
 649             <member>name</member>
 650             <member>os</member>
 651             <member>pnode</member>
 652             <member>admin_state</member>
 653             <member>oper_state</member>
 654             <member>oper_ram</member>
 655           </simplelist>.
 656         </para>
 657       </refsect3>
 658
 659       <refsect3>
 660         <title>INFO</title>
 661
 662         <cmdsynopsis>
 663           <command>info</command>
 664           <arg rep="repeat"><replaceable>instance</replaceable></arg>
 665         </cmdsynopsis>
 666
 667         <para>
 668           Show detailed information about the (given) instances. This
 669           is different from <command>list</command> as it shows
 670           detailed data about the instance's disks (especially useful
 671           for drbd disk template).
 672         </para>
 673       </refsect3>
 674
 675       <refsect3>
 676         <title>MODIFY</title>
 677
 678         <cmdsynopsis>
 679           <command>modify</command>
 680           <arg choice="opt">-m <replaceable>memsize</replaceable></arg>
 681           <arg choice="opt">-p <replaceable>vcpus</replaceable></arg>
 682           <arg choice="opt">-i <replaceable>ip</replaceable></arg>
 683           <arg choice="opt">-b <replaceable>bridge</replaceable></arg>
 684           <arg choice="opt">--mac <replaceable>MAC-address</replaceable></arg>
 685           <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
 686           <arg>--hvm-acpi <replaceable>ACPI-support</replaceable></arg>
 687           <arg>--hvm-pae <replaceable>PAE-support</replaceable></arg>
 688           <arg>--hvm-cdrom-image-path
 689             <replaceable>cdrom-image-path</replaceable></arg>
 690           <arg>--hvm-nic-type <replaceable>NICTYPE</replaceable></arg>
 691           <arg>--hvm-disk-type <replaceable>DISKTYPE</replaceable></arg>
 692           <arg>--vnc-bind-address
 693             <replaceable>vnc-bind-address</replaceable></arg>
 694
 695           <sbr>
 696           <arg>--kernel <group choice="req">
 697               <arg>default</arg>
 698               <arg><replaceable>kernel_path</replaceable></arg>
 699             </group></arg>
 700           <sbr>
 701           <arg>--initrd <group choice="req">
 702               <arg>default</arg>
 703               <arg>none</arg>
 704               <arg><replaceable>initrd_path</replaceable></arg>
 705             </group> </arg>
 706           <sbr>
 707           <arg choice="req"><replaceable>instance</replaceable></arg>
 708         </cmdsynopsis>
 709
 710         <para>
 711           Modify the memory size, number of vcpus, ip address, MAC
 712           address and/or bridge for an instance.
 713         </para>
 714
 715         <para>
 716           The memory size is given in MiB. Note that you need to give
 717           at least one of the arguments, otherwise the command
 718           complains.
 719         </para>
 720
 721         <para>
 722           The <option>--kernel</option>, <option>--initrd</option>
 723           and <option>--hvm-boot-order</option>
 724           options are described in the <command>add</command> command.
 725         </para>
 726
 727         <para>
 728           Additionally, the HVM boot order can be reset to the default
 729           values by using <option>--hvm-boot-order=default</option>.
 730         </para>
 731
 732         <para>
 733           The <option>--hvm-acpi</option> option specifies if Xen
 734           should enable ACPI support for this HVM instance. Valid
 735           values are true or false.
 736         </para>
 737
 738         <para>
 739           The <option>--hvm-pae</option> option specifies if Xen
 740           should enabled PAE support for this HVM instance. Valid
 741           values are true or false.
 742         </para>
 743
 744         <para>
 745           The <option>--hvm-cdrom-image-path</option> specifies the
 746           path to the file xen uses to emulate a virtual CDROM drive
 747           for this HVM instance. Valid values are either an
 748           absolute path to an existing file or None, which disables
 749           virtual CDROM support for this instance.
 750         </para>
 751
 752         <para>
 753           The <option>--hvm-nic-type</option> specifies the NIC type
 754           Xen should use for this HVM instance. Valid choices are
 755           rtl8139, ne2k_pci, ne2k_isa and paravirtual with rtl8139
 756           as the default. The paravirtual setting is intended for use
 757           with the GPL PV drivers inside HVM Windows instances.
 758         </para>
 759
 760         <para>
 761           The <option>--hvm-disk-type</option> specifies the disk type
 762           Xen should use for the HVM instance. Valid choices are ioemu
 763           and paravirtual with ioemu as the default. The paravirtual
 764           setting is intended for use with the GPL PV drivers inside
 765           HVM Windows instances.
 766         </para>
 767
 768         <para>
 769           The <option>--vnc-bind-address</option> specifies the
 770           address that the VNC listener for this instance should bind
 771           to. Valid values are IPv4 addresses. Use the address 0.0.0.0
 772           to bind to all available interfaces.
 773         </para>
 774
 775         <para>
 776           All the changes take effect at the next restart. If the
 777           instance is running, there is no effect on the instance.
 778         </para>
 779       </refsect3>
 780
 781       <refsect3>
 782         <title>REINSTALL</title>
 783
 784         <cmdsynopsis>
 785           <command>reinstall</command>
 786           <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
 787           <arg choice="opt">-f <replaceable>force</replaceable></arg>
 788           <arg>--select-os</arg>
 789           <arg choice="req"><replaceable>instance</replaceable></arg>
 790         </cmdsynopsis>
 791
 792         <para>
 793           Reinstalls the operating system on the given instance. The instance
 794           must be stopped when running this command. If the
 795           <option>--os-type</option> is specified, the operating system is
 796           changed.
 797         </para>
 798
 799         <para>
 800           The <option>--select-os</option> option switches to an
 801           interactive OS reinstall. The user is prompted to select the OS
 802           template from the list of available OS templates.
 803         </para>
 804       </refsect3>
 805
 806       <refsect3>
 807         <title>RENAME</title>
 808
 809         <cmdsynopsis>
 810           <command>rename</command>
 811           <arg>--no-ip-check</arg>
 812           <arg choice="req"><replaceable>instance</replaceable></arg>
 813           <arg choice="req"><replaceable>new_name</replaceable></arg>
 814         </cmdsynopsis>
 815
 816         <para>
 817           Renames the given instance. The instance must be stopped
 818           when running this command. The requirements for the new name
 819           are the same as for adding an instance: the new name must be
 820           resolvable and the IP it resolves to must not be reachable
 821           (in order to prevent duplicate IPs the next time the
 822           instance is started). The IP test can be skipped if the
 823           <option>--no-ip-check</option> option is passed.
 824         </para>
 825       </refsect3>
 826
 827     </refsect2>
 828
 829     <refsect2>
 830       <title>Starting/stopping/connecting to console</title>
 831
 832       <refsect3>
 833         <title>STARTUP</title>
 834
 835         <cmdsynopsis>
 836           <command>startup</command>
 837           <arg>--extra=<replaceable>PARAMS</replaceable></arg>
 838           <arg>--force</arg>
 839           <sbr>
 840           <group choice="opt">
 841             <arg>--instance</arg>
 842             <arg>--node</arg>
 843             <arg>--primary</arg>
 844             <arg>--secondary</arg>
 845             <arg>--all</arg>
 846           </group>
 847           <sbr>
 848           <arg choice="opt"
 849           rep="repeat"><replaceable>name</replaceable></arg>
 850         </cmdsynopsis>
 851
 852         <para>
 853           Starts one or more instances, depending on the following
 854           options. The four available modes are:
 855           <variablelist>
 856             <varlistentry>
 857               <term><option>--instance</option></term>
 858               <listitem>
 859                 <simpara>will start the instances given as arguments
 860                 (at least one argument required); this is the default
 861                 selection</simpara>
 862               </listitem>
 863             </varlistentry>
 864             <varlistentry>
 865               <term>--node</term>
 866               <listitem>
 867                 <simpara>will start the instances who have the given
 868                 node as either primary or secondary</simpara>
 869               </listitem>
 870             </varlistentry>
 871             <varlistentry>
 872               <term><option>--primary</option></term>
 873               <listitem>
 874                 <simpara>will start all instances whose primary node
 875                 is in the list of nodes passed as arguments (at least
 876                 one node required)</simpara>
 877               </listitem>
 878             </varlistentry>
 879             <varlistentry>
 880               <term><option>--secondary</option></term>
 881               <listitem>
 882                 <simpara>will start all instances whose secondary node
 883                 is in the list of nodes passed as arguments (at least
 884                 one node required)</simpara>
 885               </listitem>
 886             </varlistentry>
 887             <varlistentry>
 888               <term>--all</term>
 889               <listitem>
 890                 <simpara>will start all instances in the cluster (no
 891                 arguments accepted)</simpara>
 892               </listitem>
 893             </varlistentry>
 894           </variablelist>
 895         </para>
 896
 897         <para>
 898           Note that although you can pass more than one selection
 899           option, the last one wins, so in order to guarantee the
 900           desired result, don't pass more than one such option.
 901         </para>
 902
 903         <para>
 904           The <option>--extra</option> option is used to pass
 905           additional argument to the instance's kernel for this start
 906           only. Currently there is no way to specify a persistent set
 907           of arguments (beside the one hardcoded). Note that this may
 908           not apply to all virtualization types.
 909         </para>
 910
 911         <para>
 912           Use <option>--force</option> to start even if secondary disks are
 913           failing.
 914         </para>
 915
 916         <para>
 917           Example:
 918           <screen>
 919 # gnt-instance start instance1.example.com
 920 # gnt-instance start --extra single test1.example.com
 921 # gnt-instance start --node node1.example.com node2.example.com
 922 # gnt-instance start --all
 923           </screen>
 924         </para>
 925       </refsect3>
 926
 927       <refsect3>
 928         <title>SHUTDOWN</title>
 929
 930         <cmdsynopsis>
 931           <command>shutdown</command>
 932           <sbr>
 933           <group choice="opt">
 934             <arg>--instance</arg>
 935             <arg>--node</arg>
 936             <arg>--primary</arg>
 937             <arg>--secondary</arg>
 938             <arg>--all</arg>
 939           </group>
 940           <sbr>
 941
 942           <arg choice="opt"
 943           rep="repeat"><replaceable>name</replaceable></arg>
 944         </cmdsynopsis>
 945
 946         <para>
 947           Stops one or more instances. If the instance cannot be
 948           cleanly stopped during a hardcoded interval (currently 2
 949           minutes), it will forcibly stop the instance (equivalent to
 950           switching off the power on a physical machine).
 951         </para>
 952
 953         <para>
 954           The <option>--instance</option>, <option>--node</option>,
 955           <option>--primary</option>, <option>--secondary</option> and
 956           <option>--all</option> options are similar as for the
 957           <command>startup</command> command and they influence the
 958           actual instances being shutdown.
 959         </para>
 960
 961         <para>
 962           Example:
 963           <screen>
 964 # gnt-instance shutdown instance1.example.com
 965 # gnt-instance shutdown --all
 966           </screen>
 967         </para>
 968       </refsect3>
 969
 970       <refsect3>
 971         <title>REBOOT</title>
 972
 973         <cmdsynopsis>
 974           <command>reboot</command>
 975           <sbr>
 976           <arg>--extra=<replaceable>PARAMS</replaceable></arg>
 977           <sbr>
 978           <arg>--type=<replaceable>REBOOT-TYPE</replaceable></arg>
 979           <sbr>
 980           <arg>--ignore-secondaries</arg>
 981           <sbr>
 982           <arg>--force-multiple</arg>
 983           <sbr>
 984           <group choice="opt">
 985             <arg>--instance</arg>
 986             <arg>--node</arg>
 987             <arg>--primary</arg>
 988             <arg>--secondary</arg>
 989             <arg>--all</arg>
 990           </group>
 991           <sbr>
 992
 993           <arg choice="opt"
 994           rep="repeat"><replaceable>name</replaceable></arg>
 995         </cmdsynopsis>
 996
 997         <para>
 998           Reboots one or more instances. The type of reboot depends on
 999           the value of <option>--type</option>. A soft reboot does a
1000           hypervisor reboot, a hard reboot does a instance stop,
1001           recreates the hypervisor config for the instance and
1002           starts the instance. A full reboot does the equivalent
1003           of <command>gnt-instance shutdown &amp;&amp; gnt-instance
1004           startup</command>. The default is hard reboot.
1005         </para>
1006
1007         <para>
1008           For the hard reboot the option
1009           <option>--ignore-secondaries</option> ignores errors for the
1010           secondary node while re-assembling the instance disks.
1011         </para>
1012
1013         <para>
1014           The <option>--instance</option>, <option>--node</option>,
1015           <option>--primary</option>, <option>--secondary</option> and
1016           <option>--all</option> options are similar as for the
1017           <command>startup</command> command and they influence the
1018           actual instances being rebooted.
1019         </para>
1020
1021         <para>
1022           Use the <option>--force-multiple</option> option to keep
1023           gnt-instance from asking for confirmation when more than one
1024           instance is affected.
1025         </para>
1026
1027         <para>
1028           Example:
1029           <screen>
1030 # gnt-instance reboot instance1.example.com
1031 # gnt-instance reboot --type=full instance1.example.com
1032           </screen>
1033         </para>
1034       </refsect3>
1035
1036       <refsect3>
1037         <title>CONSOLE</title>
1038         <cmdsynopsis>
1039           <command>console</command>
1040           <arg choice="opt">--show-cmd</arg>
1041           <arg choice="req"><replaceable>instance</replaceable></arg>
1042         </cmdsynopsis>
1043
1044         <para>
1045           Connects to the console of the given instance. If the instance
1046           is not up, an error is returned. Use the <option>--show-cmd</option>
1047           option to display the command instead of executing it.
1048         </para>
1049
1050         <para>
1051           For HVM instances, this will attempt to connect to the serial
1052           console of the instance. To connect to the virtualized
1053           "physical" console of a HVM instance, use a VNC client with
1054           the connection info from gnt-instance info.
1055         </para>
1056
1057         <para>
1058           Example:
1059           <screen>
1060 # gnt-instance console instance1.example.com
1061           </screen>
1062         </para>
1063       </refsect3>
1064
1065     </refsect2>
1066
1067     <refsect2>
1068       <title>Disk management</title>
1069
1070       <refsect3>
1071         <title>REPLACE-DISKS</title>
1072
1073         <cmdsynopsis>
1074           <command>replace-disks</command>
1075
1076           <group choice="req">
1077             <arg>--iallocator <replaceable>name</replaceable></arg>
1078             <arg>--new-secondary <replaceable>NODE</replaceable></arg>
1079           </group>
1080           <sbr>
1081
1082           <arg choice="opt">-s</arg>
1083           <arg choice="req"><replaceable>instance</replaceable></arg>
1084         </cmdsynopsis>
1085
1086         <cmdsynopsis>
1087           <command>replace-disks</command>
1088
1089           <group>
1090           <arg choice="req">-s</arg>
1091           <arg choice="req">-p</arg>
1092           </group>
1093           <arg choice="req"><replaceable>instance</replaceable></arg>
1094         </cmdsynopsis>
1095
1096         <para>
1097           This command is a generalized form for adding and replacing
1098           disks. It is currently only valid for the mirrored (DRBD)
1099           disk template.
1100         </para>
1101
1102         <para>
1103           The first form will do a secondary node change, while the
1104           second form will replace the disks on either the primary
1105           (<option>-p</option>) or the secondary (<option>-s</option>)
1106           node of the instance only, without changing the node.
1107         </para>
1108
1109         <para>
1110           Specifying <option>--iallocator</option> enables secondary node
1111           replacement and and makes the new secondary be selected automatically
1112           by the specified allocator plugin.
1113         </para>
1114       </refsect3>
1115
1116       <refsect3>
1117         <title>ACTIVATE-DISKS</title>
1118
1119         <cmdsynopsis>
1120           <command>activate-disks</command>
1121           <arg choice="req"><replaceable>instance</replaceable></arg>
1122         </cmdsynopsis>
1123         <para>
1124           Activates the block devices of the given instance. If
1125           successful, the command will show the location and name of
1126           the block devices:
1127           <screen>
1128 node1.example.com:sda:/dev/drbd0
1129 node1.example.com:sdb:/dev/drbd1
1130           </screen>
1131
1132           In this example, <emphasis>node1.example.com</emphasis> is
1133           the name of the node on which the devices have been
1134           activated. The <emphasis>sda</emphasis> and
1135           <emphasis>sdb</emphasis> are the names of the block devices
1136           inside the instance. <emphasis>/dev/drbd0</emphasis> and
1137           <emphasis>/dev/drbd1</emphasis> are the names of the block
1138           devices as visible on the node.
1139         </para>
1140
1141         <para>
1142           Note that it is safe to run this command while the instance
1143           is already running.
1144         </para>
1145       </refsect3>
1146
1147       <refsect3>
1148         <title>DEACTIVATE-DISKS</title>
1149
1150         <cmdsynopsis>
1151           <command>deactivate-disks</command>
1152           <arg choice="req"><replaceable>instance</replaceable></arg>
1153         </cmdsynopsis>
1154         <para>
1155           De-activates the block devices of the given instance. Note
1156           that if you run this command for an instance with a drbd
1157           disk template, while it is running, it will not be able to
1158           shutdown the block devices on the primary node, but it will
1159           shutdown the block devices on the secondary nodes, thus
1160           breaking the replication.
1161         </para>
1162
1163       </refsect3>
1164
1165       <refsect3>
1166         <title>GROW-DISK</title>
1167         <cmdsynopsis>
1168           <command>grow-disk</command>
1169           <arg choice="req"><replaceable>instance</replaceable></arg>
1170           <arg choice="req"><replaceable>disk</replaceable></arg>
1171           <arg choice="req"><replaceable>amount</replaceable></arg>
1172         </cmdsynopsis>
1173
1174         <para>
1175           Grows an instance's disk. This is only possible for
1176           instances having a <literal>plain</literal> or
1177           <literal>drbd</literal> disk template.
1178         </para>
1179
1180         <para>
1181           Note that this command only change the block device size; it
1182           will not grow the actual filesystems, partitions, etc. that
1183           live on that disk. Usually, you will need to:
1184           <orderedlist>
1185             <listitem>
1186               <simpara>use <command>gnt-instance grow-disk</command></simpara>
1187             </listitem>
1188             <listitem>
1189               <simpara>reboot the instance (later, at a convenient
1190               time)</simpara>
1191             </listitem>
1192             <listitem>
1193               <simpara>use a filesystem resizer, such as
1194               <citerefentry> <refentrytitle>ext2online</refentrytitle>
1195               <manvolnum>8</manvolnum> </citerefentry> or
1196               <citerefentry> <refentrytitle>xfs_growfs</refentrytitle>
1197               <manvolnum>8</manvolnum> </citerefentry> to resize the
1198               filesystem, or use <citerefentry>
1199               <refentrytitle>fdisk</refentrytitle>
1200               <manvolnum>8</manvolnum> </citerefentry> to change the
1201               partition table on the disk
1202               </simpara>
1203             </listitem>
1204           </orderedlist>
1205         </para>
1206
1207
1208         <para>
1209           The <replaceable>disk</replaceable> argument is either
1210           <literal>sda</literal> or <literal>sdb</literal>. The
1211           <replaceable>amount</replaceable> argument is given either
1212           as a number (and it represents the amount to increase the
1213           disk with in mebibytes) or can be given similar to the
1214           arguments in the create instance operation, with a suffix
1215           denoting the unit.
1216         </para>
1217
1218         <para>
1219           Note that the disk grow operation might complete on one node
1220           but fail on the other; this will leave the instance with
1221           different-sized LVs on the two nodes, but this will not
1222           create problems (except for unused space).
1223         </para>
1224
1225         <para>Example (increasing sda for instance1 with 16GiB):
1226           <screen>
1227 # gnt-instance grow-disk instance1.example.com sda 16g
1228           </screen>
1229         </para>
1230
1231         <para>
1232           Also note that disk shrinking will not be supported; use
1233           <command>gnt-backup export</command> and then
1234           <command>gnt-backup import</command> to reduce the disk size
1235           of an instance.
1236         </para>
1237       </refsect3>
1238
1239     </refsect2>
1240
1241     <refsect2>
1242       <title>Recovery</title>
1243
1244       <refsect3>
1245         <title>FAILOVER</title>
1246
1247         <cmdsynopsis>
1248           <command>failover</command>
1249           <arg>-f</arg>
1250           <arg>--ignore-consistency</arg>
1251           <arg choice="req"><replaceable>instance</replaceable></arg>
1252         </cmdsynopsis>
1253
1254         <para>
1255           Failover will fail the instance over its secondary
1256           node. This works only for instances having a drbd disk
1257           template.
1258         </para>
1259
1260         <para>
1261           Normally the failover will check the consistency of the
1262           disks before failing over the instance. If you are trying to
1263           migrate instances off a dead node, this will fail. Use the
1264           <option>--ignore-consistency</option> option for this
1265           purpose. Note that this option can be dangerous as errors in
1266           shutting down the instance will be ignored, resulting in
1267           possibly having the instance running on two machines in
1268           parallel (on disconnected DRBD drives).
1269         </para>
1270
1271         <para>
1272           Example:
1273           <screen>
1274 # gnt-instance failover instance1.example.com
1275           </screen>
1276         </para>
1277       </refsect3>
1278
1279     </refsect2>
1280
1281     <refsect2>
1282       <title>TAGS</title>
1283
1284     <refsect3>
1285         <title>ADD-TAGS</title>
1286
1287         <cmdsynopsis>
1288           <command>add-tags</command>
1289           <arg choice="opt">--from <replaceable>file</replaceable></arg>
1290           <arg choice="req"><replaceable>instancename</replaceable></arg>
1291           <arg choice="req"
1292             rep="repeat"><replaceable>tag</replaceable></arg>
1293         </cmdsynopsis>
1294
1295         <para>
1296           Add tags to the given instance. If any of the tags contains
1297           invalid characters, the entire operation will abort.
1298         </para>
1299         <para>
1300           If the <option>--from</option> option is given, the list of
1301           tags will be extended with the contents of that file (each
1302           line becomes a tag). In this case, there is not need to pass
1303           tags on the command line (if you do, both sources will be
1304           used). A file name of - will be interpreted as stdin.
1305         </para>
1306       </refsect3>
1307
1308       <refsect3>
1309         <title>LIST-TAGS</title>
1310
1311         <cmdsynopsis>
1312           <command>list-tags</command>
1313           <arg choice="req"><replaceable>instancename</replaceable></arg>
1314         </cmdsynopsis>
1315
1316         <para>List the tags of the given instance.</para>
1317       </refsect3>
1318
1319       <refsect3>
1320         <title>REMOVE-TAGS</title>
1321         <cmdsynopsis>
1322           <command>remove-tags</command>
1323           <arg choice="opt">--from <replaceable>file</replaceable></arg>
1324           <arg choice="req"><replaceable>instancename</replaceable></arg>
1325           <arg choice="req"
1326             rep="repeat"><replaceable>tag</replaceable></arg>
1327         </cmdsynopsis>
1328
1329         <para>
1330           Remove tags from the given instance. If any of the tags are
1331           not existing on the node, the entire operation will abort.
1332         </para>
1333
1334         <para>
1335           If the <option>--from</option> option is given, the list of
1336           tags will be extended with the contents of that file (each
1337           line becomes a tag). In this case, there is not need to pass
1338           tags on the command line (if you do, both sources will be
1339           used). A file name of - will be interpreted as stdin.
1340         </para>
1341       </refsect3>
1342
1343     </refsect2>
1344
1345   </refsect1>
1346
1347   &footer;
1348
1349 </refentry>
1350
1351 <!-- Keep this comment at the end of the file
1352 Local variables:
1353 mode: sgml
1354 sgml-omittag:t
1355 sgml-shorttag:t
1356 sgml-minimize-attributes:nil
1357 sgml-always-quote-attributes:t
1358 sgml-indent-step:2
1359 sgml-indent-data:t
1360 sgml-parent-document:nil
1361 sgml-default-dtd-file:nil
1362 sgml-exposed-tags:nil
1363 sgml-local-catalogs:nil
1364 sgml-local-ecat-files:nil
1365 End:
1366 -->