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