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