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