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