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