gnt-instance.sgml 74.7 KB
Newer Older
Iustin Pop's avatar
Iustin Pop committed
1 2 3 4
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!-- Please adjust the date whenever revising the manpage. -->
5
  <!ENTITY dhdate      "<date>February 11, 2009</date>">
Iustin Pop's avatar
Iustin Pop committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
  <!ENTITY dhucpackage "<refentrytitle>gnt-instance</refentrytitle>">
  <!ENTITY dhpackage   "gnt-instance">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  <!ENTITY footer SYSTEM "footer.sgml">
]>

<refentry>
  <refentryinfo>
    <copyright>
      <year>2006</year>
      <year>2007</year>
23
      <year>2008</year>
24
      <year>2009</year>
Iustin Pop's avatar
Iustin Pop committed
25 26 27 28 29 30 31 32
      <holder>Google Inc.</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
33
    <refmiscinfo>ganeti 2.0</refmiscinfo>
Iustin Pop's avatar
Iustin Pop committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>ganeti instance administration</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage; </command>

      <arg choice="req">command</arg>
      <arg>arguments...</arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      The <command>&dhpackage;</command> is used for instance
      administration in the ganeti system.
    </para>

  </refsect1>
  <refsect1>
    <title>COMMANDS</title>

    <refsect2>
      <title>Creation/removal/querying</title>

      <refsect3>
        <title>ADD</title>
        <cmdsynopsis>
          <command>add</command>
67
          <sbr>
68 69 70 71 72 73 74 75 76 77 78 79
          <arg choice="req">-t<group choice="req">
              <arg>diskless</arg>
              <arg>file</arg>
              <arg>plain</arg>
              <arg>drbd</arg>
            </group></arg>
          <sbr>

          <group choice="req">
            <arg rep="repeat">--disk=<replaceable>N</replaceable>:size=<replaceable>VAL</replaceable><arg>,mode=<replaceable>ro|rw</replaceable></arg></arg>
            <arg>-s <replaceable>SIZE</replaceable></arg>
          </group>
80
          <sbr>
81 82 83 84
          <group>
            <arg rep="repeat">--net=<replaceable>N</replaceable><arg rep="repeat">:options</arg></arg>
            <arg>--no-nics</arg>
          </group>
Iustin Pop's avatar
Iustin Pop committed
85
          <sbr>
86
          <arg>-B <replaceable>BEPARAMS</replaceable></arg>
87
          <sbr>
88

89
          <arg>-H <replaceable>HYPERVISOR</replaceable><arg>:<arg choice="plain" rep="repeat">option=<replaceable>value</replaceable></arg></arg></arg>
90
          <sbr>
91

92
          <arg>--file-storage-dir <replaceable>dir_path</replaceable></arg>
93
          <arg>--file-driver<group choice="req">
94 95 96 97
              <arg>loop</arg>
              <arg>blktap</arg>
            </group></arg>
          <sbr>
98

99 100 101 102 103 104
          <group choice="req">
            <arg>-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
            <arg>--iallocator <replaceable>name</replaceable></arg>
          </group>
          <sbr>

105 106
          <arg choice="req">-o <replaceable>os-type</replaceable></arg>
          <sbr>
107 108
          <arg>--submit</arg>
          <sbr>
109

Iustin Pop's avatar
Iustin Pop committed
110 111
          <arg choice="req"><replaceable>instance</replaceable></arg>
        </cmdsynopsis>
112

Iustin Pop's avatar
Iustin Pop committed
113
        <para>
114 115
          Creates a new instance on the specified host. The
          <replaceable>instance</replaceable> argument must be in DNS,
116 117
          but depending on the bridge/routing setup, need not be in
          the same network as the nodes in the cluster.
Iustin Pop's avatar
Iustin Pop committed
118 119 120
        </para>

        <para>
121 122 123 124 125 126 127 128
          The <option>disk</option> option specifies the parameters
          for the disks of the instance. The numbering of disks starts
          at zero, and at least one disk needs to be passed. For each
          disk, at least the size needs to be given, and optionally
          the access mode (read-only or the default of read-write) can
          also be specified.  The size is interpreted (when no unit is
          given) in mebibytes. You can also use one of the suffixes
          <literal>m</literal>, <literal>g</literal> or
129 130
          <literal>t</literal> to specificy the exact the units used;
          these suffixes map to mebibytes, gibibytes and tebibytes.
Iustin Pop's avatar
Iustin Pop committed
131 132
        </para>

133 134 135 136 137 138 139
        <para>
          Alternatively, a single-disk instance can be created via the
          <option>-s</option> option which takes a single argument,
          the size of the disk. This is similar to the Ganeti 1.2
          version (but will only create one disk).
        </para>

Iustin Pop's avatar
Iustin Pop committed
140
        <para>
141
          The minimum disk specification is therefore
142 143 144 145 146
          <userinput>--disk 0:size=20G</userinput> (or <userinput>-s
          20G</userinput> when using the <option>-s</option> option),
          and a three-disk instance can be specified as
          <userinput>--disk 0:size=20G --disk 1:size=4G --disk
          2:size=100G</userinput>.
Iustin Pop's avatar
Iustin Pop committed
147 148 149
        </para>

        <para>
150
          The NICs of the instances can be specified via the
151
          <option>--net</option> option. By default, one NIC is
152 153 154
          created for the instance, with a random MAC, and set
          up according the the cluster level nic parameters.
          Each NIC can take these parameters (all optional):
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
          <variablelist>
            <varlistentry>
              <term>mac</term>
              <listitem>
                <simpara>either a value or <constant>GENERATE</constant>
                  to generate a new unique MAC</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>ip</term>
              <listitem>
                <simpara>specifies the IP address assigned to the
                  instance from the Ganeti side (this is not necessarily
                  what the instance will use, but what the node expects
                  the instance to use)</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
173
              <term>mode</term>
174
              <listitem>
175 176 177 178 179 180 181 182 183 184 185 186
                <simpara>specifies the connection mode for this nic:
                  routed or bridged.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>link</term>
              <listitem>
                <simpara>in bridged mode specifies the bridge to attach
                  this NIC to, in routed mode it's intended to
                  differentiate between different routing tables/instance
                  groups (but the meaning is dependent on the network
                  script)</simpara>
187 188 189
              </listitem>
            </varlistentry>
          </variablelist>
190 191
          Of these "mode" and "link" are nic parameters, and inherit their
          default at cluster level.
192 193 194
        </para>

        <para>
195 196 197
          Alternatively, if no network is desired for the instance, you
          can prevent the default of one NIC with the
          <option>--no-nics</option> option.
Iustin Pop's avatar
Iustin Pop committed
198 199 200
        </para>

        <para>
201 202 203
          The <option>-o</option> options specifies the operating
          system to be installed. The available operating systems can
          be listed with <command>gnt-os list</command>.
Iustin Pop's avatar
Iustin Pop committed
204 205
        </para>

206
        <para>
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
          The <option>-B</option> option specifies the backend
          parameters for the instance. If no such parameters are
          specified, the values are inherited from the cluster. Possible
          parameters are:
          <variablelist>
            <varlistentry>
              <term>memory</term>
              <listitem>
                <simpara>the memory size of the instance; as usual,
                  suffixes can be used to denote the unit, otherwise the
                  value is taken in mebibites</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>vcpus</term>
              <listitem>
                <simpara>the number of VCPUs to assign to the instance
                  (if this value makes sense for the hypervisor)</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>auto_balance</term>
              <listitem>
                <simpara>whether the instance is considered in the N+1
                  cluster checks (enough redundancy in the cluster to
                  survive a node failure)</simpara>
              </listitem>
            </varlistentry>
          </variablelist>
236 237
        </para>

238
        <para>
239 240 241 242 243 244 245 246
          The <option>-H</option> option specified the hypervisor to
          use for the instance (must be one of the enabled hypervisors
          on the cluster) and optionally custom parameters for this
          instance. If not other options are used (i.e. the invocation
          is just <userinput>-H
          <replaceable>NAME</replaceable></userinput>) the instance
          will inherit the cluster options. The defaults below show
          the cluster defaults at cluster creation time.
247 248 249
        </para>

        <para>
250
          The possible hypervisor options are as follows:
251 252
          <variablelist>
            <varlistentry>
253
              <term>boot_order</term>
254
              <listitem>
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
                <simpara>Valid for the Xen HVM and KVM
                hypervisors.</simpara>

                <simpara>A string value denoting the boot order. This
                has different meaning for the Xen HVM hypervisor and
                for the KVM one.</simpara>

                <simpara>
                  For Xen HVM, The boot order is a string of letters
                  listing the boot devices, with valid device letters
                  being:
                </simpara>
                  <variablelist>
                    <varlistentry>
                      <term>a</term>
                      <listitem>
                        <para>
                          floppy drive
                        </para>
                      </listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>c</term>
                      <listitem>
                        <para>
                          hard disk
                        </para>
                      </listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>d</term>
                      <listitem>
                        <para>
                          CDROM drive
                        </para>
                      </listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>n</term>
                      <listitem>
                        <para>
                          network boot (PXE)
                        </para>
                      </listitem>
                    </varlistentry>
                  </variablelist>
                <simpara>
                  The default is not to set an HVM boot order which is
                  interpreted as 'dc'.
                </simpara>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>cdrom_image_path</term>
              <listitem>
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

                <simpara>The path to a CDROM image to attach to the
                instance.</simpara>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>nic_type</term>
              <listitem>
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

323
                <para>
324 325 326 327 328 329 330 331 332 333 334 335 336
                  This parameter determines the way the network cards
                  are presented to the instance. The possible options are:
                  <simplelist>
                    <member>rtl8139 (default for Xen HVM) (HVM & KVM)</member>
                    <member>ne2k_isa (HVM & KVM)</member>
                    <member>ne2k_pci (HVM & KVM)</member>
                    <member>i82551 (KVM)</member>
                    <member>i82557b (KVM)</member>
                    <member>i82559er (KVM)</member>
                    <member>pcnet (KVM)</member>
                    <member>e1000 (KVM)</member>
                    <member>paravirtual (default for KVM) (HVM & KVM)</member>
                  </simplelist>
337 338 339 340
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
341
              <term>disk_type</term>
342
              <listitem>
343 344
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

345
                <para>
346 347 348 349 350 351 352 353 354 355
                  This parameter determines the way the disks are
                  presented to the instance. The possible options are:
                  <simplelist>
                    <member>ioemu (default for HVM & KVM) (HVM & KVM)</member>
                    <member>ide (HVM & KVM)</member>
                    <member>scsi (KVM)</member>
                    <member>sd (KVM)</member>
                    <member>mtd (KVM)</member>
                    <member>pflash (KVM)</member>
                  </simplelist>
356 357 358 359
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
360
              <term>vnc_bind_address</term>
361
              <listitem>
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

                <para>Specifies the address that the VNC listener for
                this instance should bind to. Valid values are IPv4
                addresses. Use the address 0.0.0.0 to bind to all
                available interfaces (this is the default) or specify
                the address of one of the interfaces on the node to
                restrict listening to that interface.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>vnc_tls</term>
              <listitem>
                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>A boolean option that controls whether the
                VNC connection is secured with TLS.</simpara>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>vnc_x509_path</term>
              <listitem>
                <simpara>Valid for the KVM hypervisor.</simpara>

                <para>If <option>vnc_tls</option> is enabled, this
                options specifies the path to the x509 certificate to
                use.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>vnc_x509_verify</term>
              <listitem>
                <simpara>Valid for the KVM hypervisor.</simpara>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>acpi</term>
              <listitem>
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

406
                <para>
407 408 409
                  A boolean option that specifies if the hypervisor
                  should enable ACPI support for this instance. By
                  default, ACPI is disabled.
410 411 412
                </para>
              </listitem>
            </varlistentry>
413

414
            <varlistentry>
415
              <term>pae</term>
416
              <listitem>
417 418
                <simpara>Valid for the Xen HVM and KVM hypervisors.</simpara>

419
                <para>
420 421 422
                  A boolean option that specifies if the hypervisor
                  should enabled PAE support for this instance. The
                  default is false, disabling PAE support.
423 424 425 426
                </para>
              </listitem>
            </varlistentry>

427 428 429 430
            <varlistentry>
              <term>kernel_path</term>
              <listitem>
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
431

432 433 434 435 436 437 438 439 440
                <para>
                  This option specifies the path (on the node) to the
                  kernel to boot the instance with. Xen PVM instances
                  always require this, while for KVM if this option is
                  empty, it will cause the machine to load the kernel
                  from its disks.
                </para>
              </listitem>
            </varlistentry>
441

442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464
            <varlistentry>
              <term>kernel_args</term>
              <listitem>
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>

                <para>
                  This options specifies extra arguments to the kernel
                  that will be loaded.  device. This is always used
                  for Xen PVM, while for KVM it is only used if the
                  <option>kernel_path</option> option is also
                  specified.
                </para>

                <para>
                  The default setting for this value is simply
                  <constant>"ro"</constant>, which mounts the root
                  disk (initially) in read-only one. For example,
                  setting this to <userinput>single</userinput> will
                  cause the instance to start in single-user mode.
                </para>
              </listitem>
            </varlistentry>

465 466 467 468
            <varlistentry>
              <term>initrd_path</term>
              <listitem>
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
469

470 471 472 473 474
                <para>
                  This option specifies the path (on the node) to the
                  initrd to boot the instance with. Xen PVM instances
                  can use this always, while for KVM if this option is
                  only used if the <option>kernel_path</option> option
475 476 477 478
                  is also specified. You can pass here either an
                  absolute filename (the path to the initrd) if you
                  want to use an initrd, or use the format
                  <userinput>no_initrd_path</userinput> for no initrd.
479 480 481
                </para>
              </listitem>
            </varlistentry>
482

483 484 485 486
            <varlistentry>
              <term>root_path</term>
              <listitem>
                <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>
487

488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507
                <para>
                  This options specifies the name of the root
                  device. This is always needed for Xen PVM, while for
                  KVM it is only used if the
                  <option>kernel_path</option> option is also
                  specified.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>serial_console</term>
              <listitem>
                <simpara>Valid for the KVM hypervisor.</simpara>

                <simpara>This boolean option specifies whether to
                emulate a serial console for the instance.</simpara>
              </listitem>
            </varlistentry>
          </variablelist>
508 509
        </para>

510 511 512
        <para>
        </para>

513
        <para>
514 515 516 517 518 519 520
          The <option>--iallocator</option> option specifies the instance
          allocator plugin to use. If you pass in this option the allocator
          will select nodes for this instance automatically, so you don't need
          to pass them with the <option>-n</option> option. For more
          information please refer to the instance allocator documentation.
        </para>

Iustin Pop's avatar
Iustin Pop committed
521 522 523 524 525 526 527 528 529 530 531 532 533
        <para>
          The <option>-t</option> options specifies the disk layout type for
          the instance. The available choices are:
          <variablelist>
            <varlistentry>
              <term>diskless</term>
              <listitem>
                <para>
                  This creates an instance with no disks. Its useful for
                  testing only (or other special cases).
                </para>
              </listitem>
            </varlistentry>
534 535 536 537 538 539
            <varlistentry>
              <term>file</term>
              <listitem>
                <para>Disk devices will be regular files.</para>
              </listitem>
            </varlistentry>
Iustin Pop's avatar
Iustin Pop committed
540 541 542 543 544 545
            <varlistentry>
              <term>plain</term>
              <listitem>
                <para>Disk devices will be logical volumes.</para>
              </listitem>
            </varlistentry>
Iustin Pop's avatar
Iustin Pop committed
546 547 548 549 550
            <varlistentry>
              <term>drbd</term>
              <listitem>
                <para>
                  Disk devices will be drbd (version 8.x) on top of
551
                  lvm volumes.
Iustin Pop's avatar
Iustin Pop committed
552 553 554 555 556 557 558
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </para>

        <para>
559
          The optional second value of the <option>--node</option> is used for
560
          the drbd template type and specifies the remote node.
Iustin Pop's avatar
Iustin Pop committed
561 562 563 564 565 566 567 568
        </para>

        <para>
          If you do not want gnt-instance to wait for the disk mirror
          to be synced, use the <option>--no-wait-for-sync</option>
          option.
        </para>

569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588
        <para>
          The <option>--file-storage-dir</option> specifies the relative path
          under the cluster-wide file storage directory to store file-based
          disks. It is useful for having different subdirectories for
          different instances. The full path of the directory where the disk
          files are stored will consist of cluster-wide file storage directory
          + optional subdirectory + instance name. Example:
          /srv/ganeti/file-storage/mysubdir/instance1.example.com. This option
          is only relevant for instances using the file storage backend.
        </para>

        <para>
          The <option>--file-driver</option> specifies the driver to use for
          file-based disks. Note that currently these drivers work with the
          xen hypervisor only. This option is only relevant for instances using
          the file storage backend. The available choices are:
          <variablelist>
            <varlistentry>
              <term>loop</term>
              <listitem>
589 590 591 592 593 594 595 596 597 598
                <para>
                  Kernel loopback driver. This driver uses loopback
                  devices to access the filesystem within the
                  file. However, running I/O intensive applications in
                  your instance using the loop driver might result in
                  slowdowns.  Furthermore, if you use the loopback
                  driver consider increasing the maximum amount of
                  loopback devices (on most systems it's 8) using the
                  max_loop param.
                </para>
599 600 601 602 603
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>blktap</term>
              <listitem>
604 605 606 607 608 609 610 611 612
                <para>The blktap driver (for Xen hypervisors). In
                order to be able to use the blktap driver you should
                check if the 'blktapctrl' user space disk agent is
                running (usually automatically started via xend). This
                user-level disk I/O interface has the advantage of
                better performance. Especially if you use a network
                file system (e.g. NFS) to store your instances this is
                the recommended choice.
                </para>
613 614
              </listitem>
            </varlistentry>
615
          </variablelist>
616 617 618
        </para>

        <para>
619 620 621 622
          The <option>--submit</option> option is used to send the job to
          the master daemon but not wait for its completion. The job
          ID will be shown so that it can be examined via
          <command>gnt-job info</command>.
623
        </para>
624

Iustin Pop's avatar
Iustin Pop committed
625 626 627
        <para>
          Example:
          <screen>
628
# gnt-instance add -t file --disk 0:size=30g -B memory=512 -o debian-etch \
629
  -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
630
# gnt-instance add -t plain --disk 0:size=30g -B memory=512 -o debian-etch \
631
  -n node1.example.com instance1.example.com
632
# gnt-instance add -t drbd --disk 0:size=30g -B memory=512 -o debian-etch \
633
  -n node1.example.com:node2.example.com instance2.example.com
Iustin Pop's avatar
Iustin Pop committed
634 635 636 637
          </screen>
        </para>
      </refsect3>

638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688
      <refsect3>
        <title>BATCH-CREATE</title>
        <cmdsynopsis>
          <command>batch-create</command>
          <arg choice="req">instances_file.json</arg>
        </cmdsynopsis>

        <para>
          This command (similar to the Ganeti 1.2
          <command>batcher</command> tool) submits multiple instance
          creation jobs based on a definition file. The instance
          configurations do not encompass all the possible options for
          the <command>add</command> command, but only a subset.
        </para>

        <para>
          The instance file should be a valid-formed JSON file,
          containing a dictionary with instance name and instance
          parameters. The accepted parameters are:

          <variablelist>
            <varlistentry>
              <term>disk_size</term>
              <listitem>
                <simpara>The size of the disks of the instance.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>disk_templace</term>
              <listitem>
                <simpara>The disk template to use for the instance,
                the same as in the <command>add</command>
                command.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>backend</term>
              <listitem>
                <simpara>A dictionary of backend parameters.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>hypervisor</term>
              <listitem>
                <simpara>A dictionary with a single key (the
                hypervisor name), and as value the hypervisor
                options. If not passed, the default hypervisor and
                hypervisor options will be inherited.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
689
              <term>mac, ip, mode, link</term>
690 691
              <listitem>
                <simpara>Specifications for the one NIC that will be
692 693 694 695 696 697 698 699 700 701 702 703
                created for the instance. 'bridge' is also accepted
                as a backwards compatibile key.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>nics</term>
              <listitem>
                <simpara>List of nics that will be created for the
                instance. Each entry should be a dict, with mac, ip, mode
                and link as possible keys. Please don't provide the "mac,
                ip, mode, link" parent keys if you use this method for
                specifying nics.</simpara>
704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>primary_node, secondary_node</term>
              <listitem>
                <simpara>The primary and optionally the secondary node
                to use for the instance (in case an iallocator script
                is not used).</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>iallocator</term>
              <listitem>
                <simpara>Instead of specifying the nodes, an
                iallocator script can be used to automatically compute
                them.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>start</term>
              <listitem>
                <simpara>whether to start the instance</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>ip_check</term>
              <listitem>
                <simpara>Skip the check for already-in-use instance;
                see the description in the <command>add</command>
                command for details.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>file_storage_dir, file_driver</term>
              <listitem>
                <simpara>Configuration for the <literal>file</literal>
                disk type, see the <command>add</command> command for
                details.</simpara>
              </listitem>
            </varlistentry>
          </variablelist>
        </para>

        <para>
          A simple definition for one instance can be (with most of
          the parameters taken from the cluster defaults):
          <screen>
{
  "instance3": {
    "template": "drbd",
    "os": "debootstrap",
    "disk_size": ["25G"],
    "iallocator": "dumb"
  },
  "instance5": {
    "template": "drbd",
    "os": "debootstrap",
    "disk_size": ["25G"],
    "iallocator": "dumb",
    "hypervisor": "xen-hvm",
    "hvparams": {"acpi": true},
    "backend": {"memory": 512}
  }
}
</screen>
        </para>

        <para>
          The command will display the job id for each submitted instance, as follows:
          <screen>
# gnt-instance batch-create instances.json
instance3: 11224
instance5: 11225
</screen>
        </para>

      </refsect3>

Iustin Pop's avatar
Iustin Pop committed
782 783 784 785 786
      <refsect3>
        <title>REMOVE</title>

        <cmdsynopsis>
          <command>remove</command>
Iustin Pop's avatar
Iustin Pop committed
787
          <arg>--ignore-failures</arg>
788
          <arg>--submit</arg>
Iustin Pop's avatar
Iustin Pop committed
789 790 791 792 793 794 795 796 797
          <arg choice="req"><replaceable>instance</replaceable></arg>
        </cmdsynopsis>

        <para>
          Remove an instance. This will remove all data from the
          instance and there is <emphasis>no way back</emphasis>. If
          you are not sure if you use an instance again, use
          <command>shutdown</command> first and leave it in the
          shutdown state for a while.
Iustin Pop's avatar
Iustin Pop committed
798 799 800 801 802 803 804 805 806

        </para>

        <para>
          The <option>--ignore-failures</option> option will cause the
          removal to proceed even in the presence of errors during the
          removal of the instance (e.g. during the shutdown or the
          disk removal). If this option is not given, the command will
          stop at the first error.
Iustin Pop's avatar
Iustin Pop committed
807 808
        </para>

809 810 811 812 813 814 815
        <para>
          The <option>--submit</option> option is used to send the job to
          the master daemon but not wait for its completion. The job
          ID will be shown so that it can be examined via
          <command>gnt-job info</command>.
        </para>

Iustin Pop's avatar
Iustin Pop committed
816 817 818 819 820 821 822 823 824 825 826 827 828 829 830
        <para>
          Example:
          <screen>
# gnt-instance remove instance1.example.com
          </screen>
        </para>
      </refsect3>

      <refsect3>
        <title>LIST</title>

        <cmdsynopsis>
          <command>list</command>
          <arg>--no-headers</arg>
          <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
831
          <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>
832
          <arg rep="repeat">instance</arg>
Iustin Pop's avatar
Iustin Pop committed
833 834 835 836
        </cmdsynopsis>

        <para>
          Shows the currently configured instances with memory usage,
837 838
          disk usage, the node they are running on, and their run
          status.
Iustin Pop's avatar
Iustin Pop committed
839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873
        </para>

        <para>
          The <option>--no-headers</option> option will skip the
          initial header line. The <option>--separator</option> option
          takes an argument which denotes what will be used between
          the output fields. Both these options are to help scripting.
        </para>

        <para>
          The <option>-o</option> option takes a comma-separated list
          of output fields. The available fields and their meaning
          are:
          <variablelist>
            <varlistentry>
              <term>name</term>
              <listitem>
                <simpara>the instance name</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>os</term>
              <listitem>
                <simpara>the OS of the instance</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>pnode</term>
              <listitem>
                <simpara>the primary node of the instance</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>snodes</term>
              <listitem>
874
                <simpara>comma-separated list of secondary nodes for the
Iustin Pop's avatar
Iustin Pop committed
875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894
                  instance; usually this will be just one node</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>admin_state</term>
              <listitem>
                <simpara>the desired state of the instance (either "yes"
                  or "no" denoting the instance should run or
                  not)</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>disk_template</term>
              <listitem>
                <simpara>the disk template of the instance</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>oper_state</term>
              <listitem>
895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915
                <simpara>the actual state of the instance; can be
                one of the values "running", "stopped", "(node
                down)"</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>status</term>
              <listitem>
                <simpara>combined form of admin_state and oper_stat;
                this can be one of:
                <computeroutput>ERROR_nodedown</computeroutput> if the
                node of the instance is down,
                <computeroutput>ERROR_down</computeroutput> if the
                instance should run but is down,
                <computeroutput>ERROR_up</computeroutput> if the
                instance should be stopped but is actually running,
                <computeroutput>ADMIN_down</computeroutput> if the
                instance has been stopped (and is stopped) and
                <computeroutput>running</computeroutput> if the
                instance is set to be running (and is
                running)</simpara>
Iustin Pop's avatar
Iustin Pop committed
916 917 918 919 920 921 922 923 924 925 926 927 928
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>oper_ram</term>
              <listitem>
                <simpara>the actual memory usage of the instance as seen
                  by the hypervisor</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>ip</term>
              <listitem>
                <simpara>the ip address ganeti recognizes as associated with
929
                the first instance interface</simpara>
Iustin Pop's avatar
Iustin Pop committed
930 931 932 933 934
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>mac</term>
              <listitem>
935
                <simpara>the first instance interface MAC address</simpara>
Iustin Pop's avatar
Iustin Pop committed
936 937
              </listitem>
            </varlistentry>
938 939 940 941 942 943 944 945

            <varlistentry>
              <term>mode</term>
              <listitem>
                <simpara>the mode of the first instance NIC
                (routed or bridged)</simpara>
              </listitem>
            </varlistentry>
Iustin Pop's avatar
Iustin Pop committed
946
            <varlistentry>
947
              <term>link</term>
Iustin Pop's avatar
Iustin Pop committed
948
              <listitem>
949
                <simpara>the link of the first instance NIC
Iustin Pop's avatar
Iustin Pop committed
950 951 952
                </simpara>
              </listitem>
            </varlistentry>
953 954 955 956 957 958 959 960 961
            <varlistentry>
              <term>sda_size</term>
              <listitem>
                <simpara>the size of the instance's first disk</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>sdb_size</term>
              <listitem>
962 963
                <simpara>the size of the instance's second disk, if
                any</simpara>
964 965 966 967 968 969 970 971 972
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>vcpus</term>
              <listitem>
                <simpara>the number of VCPUs allocated to the
                instance</simpara>
              </listitem>
            </varlistentry>
973 974 975 976 977 978 979
            <varlistentry>
              <term>tags</term>
              <listitem>
                <simpara>comma-separated list of the instances's
                tags</simpara>
              </listitem>
            </varlistentry>
980 981 982 983 984 985
            <varlistentry>
              <term>serial_no</term>
              <listitem>
                <simpara>the so called 'serial number' of the
                instance; this is a numeric field that is incremented
                each time the instance is modified, and it can be used
986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048
                to track modifications</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>network_port</term>
              <listitem>
                <simpara>If the instance has a network port assigned
                to it (e.g. for VNC connections), this will be shown,
                otherwise <literal>-</literal> will be
                displayed.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>beparams</term>
              <listitem>
                <simpara>A text format of the entire beparams for the
                instance. It's more useful to select individual fields
                from this dictionary, see below.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>disk.count</term>
              <listitem>
                <simpara>The number of instance disks.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>disk.size/N</term>
              <listitem>
                <simpara>The size of the instance's Nth disk. This is
                a more generic form of the <literal>sda_size</literal>
                and <literal>sdb_size</literal> fields.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>disk.sizes</term>
              <listitem>
                <simpara>A comma-separated list of the disk sizes for
                this instance.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>disk_usage</term>
              <listitem>
                <simpara>The total disk space used by this instance on
                each of its nodes. This is not the instance-visible
                disk size, but the actual disk "cost" of the
                instance.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>nic.mac/N</term>
              <listitem>
                <simpara>The MAC of the Nth instance NIC.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>nic.ip/N</term>
              <listitem>
                <simpara>The IP address of the Nth instance NIC.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
1049
              <term>nic.mode/N</term>
1050
              <listitem>
1051 1052 1053 1054 1055 1056 1057
                <simpara>The mode of the Nth instance NIC</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>nic.link/N</term>
              <listitem>
                <simpara>The link of the Nth instance NIC</simpara>
1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>nic.macs</term>
              <listitem>
                <simpara>A comma-separated list of all the MACs of the
                instance's NICs.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>nic.ips</term>
              <listitem>
                <simpara>A comma-separated list of all the IP
                addresses of the instance's NICs.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
1075
              <term>nic.modes</term>
1076
              <listitem>
1077
                <simpara>A comma-separated list of all the modes of the
1078 1079 1080
                instance's NICs.</simpara>
              </listitem>
            </varlistentry>
1081 1082 1083 1084 1085 1086 1087
            <varlistentry>
              <term>nic.links</term>
              <listitem>
                <simpara>A comma-separated list of all the link parameters
                of the instance's NICs.</simpara>
              </listitem>
            </varlistentry>
1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120
            <varlistentry>
              <term>nic.count</term>
              <listitem>
                <simpara>The number of instance nics.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>hv/<replaceable>NAME</replaceable></term>
              <listitem>
                <simpara>The value of the hypervisor parameter called
                <replaceable>NAME</replaceable>. For details of what
                hypervisor parameters exist and their meaning, see the
                <command>add</command> command.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>be/memory</term>
              <listitem>
                <simpara>The configured memory for the instance.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>be/vcpus</term>
              <listitem>
                <simpara>The configured number of VCPUs for the
                instance.</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>be/auto_balance</term>
              <listitem>
                <simpara>Whether the instance is considered in N+1
                checks.</simpara>
1121 1122
              </listitem>
            </varlistentry>
Iustin Pop's avatar
Iustin Pop committed
1123 1124 1125
          </variablelist>
        </para>

1126 1127
        <para>
          If the value of the option starts with the character
1128
          <constant>+</constant>, the new field(s) will be added to the
1129 1130 1131 1132 1133
          default list. This allows to quickly see the default list
          plus a few other fields, instead of retyping the entire list
          of fields.
        </para>

Iustin Pop's avatar
Iustin Pop committed
1134 1135
        <para>
          There is a subtle grouping about the available output
Iustin Pop's avatar
Iustin Pop committed
1136 1137 1138 1139
          fields: all fields except for <option>oper_state</option>,
          <option>oper_ram</option> and <option>status</option> are
          configuration value and not run-time values. So if you don't
          select any of the these fields, the query will be satisfied
Iustin Pop's avatar
Iustin Pop committed
1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162
          instantly from the cluster configuration, without having to
          ask the remote nodes for the data. This can be helpful for
          big clusters when you only want some data and it makes sense
          to specify a reduced set of output fields.
        </para>

        <para>The default output field list is:
          <simplelist type="inline">
            <member>name</member>
            <member>os</member>
            <member>pnode</member>
            <member>admin_state</member>
            <member>oper_state</member>
            <member>oper_ram</member>
          </simplelist>.
        </para>
      </refsect3>

      <refsect3>
        <title>INFO</title>

        <cmdsynopsis>
          <command>info</command>
1163 1164 1165 1166
          <group>
            <arg>-s</arg>
            <arg>--static</arg>
          </group>
1167 1168 1169 1170
          <group choice="req">
            <arg>--all</arg>
            <arg rep="repeat"><replaceable>instance</replaceable></arg>
          </group>
Iustin Pop's avatar
Iustin Pop committed
1171 1172 1173
        </cmdsynopsis>

        <para>
1174 1175
          Show detailed information about the given instance(s). This is
          different from <command>list</command> as it shows detailed data
1176
          about the instance's disks (especially useful for the drbd disk
1177
          template).
Iustin Pop's avatar
Iustin Pop committed
1178
        </para>
1179 1180 1181 1182 1183 1184

        <para>
          If the option <option>-s</option> is used, only information
          available in the configuration file is returned, without
          querying nodes, making the operation faster.
        </para>
1185 1186 1187 1188 1189

        <para>
          Use the <option>--all</option> to get info about all instances,
          rather than explicitely passing the ones you're interested in.
        </para>
Iustin Pop's avatar
Iustin Pop committed
1190 1191 1192 1193 1194 1195 1196
      </refsect3>

      <refsect3>
        <title>MODIFY</title>

        <cmdsynopsis>
          <command>modify</command>
1197
          <sbr>
1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213
          <arg choice="opt">-H <replaceable>HYPERVISOR_PARAMETERS</replaceable></arg>
          <sbr>
          <arg choice="opt">-B <replaceable>BACKEND_PARAMETERS</replaceable></arg>
          <sbr>
          <group>
            <arg>--net add<replaceable><optional>:options</optional></replaceable></arg>
            <arg>--net remove</arg>
            <arg>--net <replaceable>N:options</replaceable></arg>
          </group>
          <sbr>
          <group>
            <arg>--disk add:size=<replaceable>SIZE</replaceable></arg>
            <arg>--disk remove</arg>
            <arg>--disk <replaceable>N</replaceable>:mode=<replaceable>MODE</replaceable></arg>
          </group>

1214
          <sbr>
1215
          <arg>--submit</arg>
1216
          <sbr>
Iustin Pop's avatar
Iustin Pop committed
1217 1218 1219 1220
          <arg choice="req"><replaceable>instance</replaceable></arg>
        </cmdsynopsis>

        <para>
1221
          Modifies the memory size, number of vcpus, ip address, MAC
1222 1223 1224 1225
          address and/or nic parameters for an instance. It can also
          add and remove disks and NICs to/from the instance. Note
          that you need to give at least one of the arguments, otherwise
          the command complains.
Iustin Pop's avatar
Iustin Pop committed
1226 1227 1228
        </para>

        <para>
1229 1230
          The <option>-H</option> option specifies hypervisor options
          in the form of <userinput>name=value[,...]</userinput>. For details which options can be specified, see the <command>add</command> command.
Iustin Pop's avatar
Iustin Pop committed
1231 1232
        </para>

1233
        <para>
1234 1235 1236 1237 1238 1239 1240 1241 1242
          The <option>--disk
          add:size=<replaceable>SIZE</replaceable></option> option
          adds a disk to the instance. The <option>--disk
          remove</option> will remove the last disk of the
          instance. The <option>--disk
          <replaceable>N</replaceable>:mode=<replaceable>MODE</replaceable></option>
          option will change the mode of the Nth disk of the instance
          between read-only (<literal>ro</literal>) and read-write
          (<literal>rw</literal>).
1243 1244
        </para>

1245
        <para>
1246
          The <option>--net
1247 1248
          add:<replaceable>options</replaceable></option> option will
          add a new NIC to the instance. The available options are the
1249 1250
          same as in the <command>add</command> command (mac, ip, link,
          mode). The <option>--net remove</option> will remove the
1251
          last NIC of the instance, while the <option>--net
1252 1253
          <replaceable>N</replaceable>:<replaceable>options</replaceable></option>
          option will change the parameters of the Nth instance NIC.
1254 1255
        </para>

1256
        <para>
1257 1258 1259 1260
          The <option>--submit</option> option is used to send the job to
          the master daemon but not wait for its completion. The job
          ID will be shown so that it can be examined via
          <command>gnt-job info</command>.
1261 1262
        </para>

Iustin Pop's avatar
Iustin Pop committed
1263 1264 1265 1266 1267 1268
        <para>
          All the changes take effect at the next restart. If the
          instance is running, there is no effect on the instance.
        </para>
      </refsect3>

1269 1270 1271 1272 1273 1274
      <refsect3>
        <title>REINSTALL</title>

        <cmdsynopsis>
          <command>reinstall</command>
          <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
1275
          <arg>--select-os</arg>
1276 1277 1278 1279 1280 1281 1282 1283 1284 1285
          <arg choice="opt">-f <replaceable>force</replaceable></arg>
          <arg>--force-multiple</arg>
          <sbr>
          <group choice="opt">
            <arg>--instance</arg>
            <arg>--node</arg>
            <arg>--primary</arg>
            <arg>--secondary</arg>
            <arg>--all</arg>
          </group>
1286
          <arg>--submit</arg>
1287
          <arg choice="opt" rep="repeat"><replaceable>instance</replaceable></arg>
1288 1289 1290
        </cmdsynopsis>

        <para>
1291 1292
          Reinstalls the operating system on the given instance(s). The
          instance(s) must be stopped when running this command. If the
1293 1294 1295 1296
          <option>--os-type</option> is specified, the operating
          system is changed.
        </para>

1297 1298 1299 1300 1301
        <para>
          The <option>--select-os</option> option switches to an
          interactive OS reinstall. The user is prompted to select the OS
          template from the list of available OS templates.
        </para>
1302

1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315
        <para>
          Since this is a potentially dangerous command, the user will
          be required to confirm this action, unless the
          <option>-f</option> flag is passed. When multiple instances
          are selected (either by passing multiple arguments or by
          using the <option>--node</option>,
          <option>--primary</option>, <option>--secondary</option> or
          <option>--all</option> options), the user must pass both the
          <option>--force</option> and
          <option>--force-multiple</option> options to skip the
          interactive confirmation.
        </para>

1316 1317 1318 1319 1320 1321 1322 1323
        <para>
          The <option>--submit</option> option is used to send the job to
          the master daemon but not wait for its completion. The job
          ID will be shown so that it can be examined via
          <command>gnt-job info</command>.
        </para>


1324 1325
      </refsect3>

1326 1327 1328 1329 1330 1331
      <refsect3>
        <title>RENAME</title>

        <cmdsynopsis>
          <command>rename</command>
          <arg>--no-ip-check</arg>
1332
          <arg>--submit</arg>
1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345
          <arg choice="req"><replaceable>instance</replaceable></arg>
          <arg choice="req"><replaceable>new_name</replaceable></arg>
        </cmdsynopsis>

        <para>
          Renames the given instance. The instance must be stopped
          when running this command. The requirements for the new name
          are the same as for adding an instance: the new name must be
          resolvable and the IP it resolves to must not be reachable
          (in order to prevent duplicate IPs the next time the
          instance is started). The IP test can be skipped if the
          <option>--no-ip-check</option> option is passed.
        </para>
1346 1347 1348 1349 1350 1351 1352 1353

        <para>
          The <option>--submit</option> option is used to send the job to
          the master daemon but not wait for its completion. The job
          ID will be shown so that it can be examined via
          <command>gnt-job info</command>.
        </para>

1354 1355
      </refsect3>

Iustin Pop's avatar
Iustin Pop committed
1356 1357 1358 1359 1360 1361 1362 1363 1364 1365
    </refsect2>

    <refsect2>
      <title>Starting/stopping/connecting to console</title>

      <refsect3>
        <title>STARTUP</title>

        <cmdsynopsis>
          <command>startup</command>
1366
          <sbr>
1367
          <arg>--force</arg>
1368
          <sbr>
1369 1370
          <arg>--force-multiple</arg>
          <sbr>
1371 1372 1373 1374 1375 1376 1377 1378
          <group choice="opt">
            <arg>--instance</arg>
            <arg>--node</arg>
            <arg>--primary</arg>
            <arg>--secondary</arg>
            <arg>--all</arg>
          </group>
          <sbr>
1379 1380 1381
          <arg>-H <option>key=value...</option></arg>
          <arg>-B <option>key=value...</option></arg>
          <sbr>
1382 1383
          <arg>--submit</arg>
          <sbr>
1384 1385
          <arg choice="opt"
          rep="repeat"><replaceable>name</replaceable></arg>
Iustin Pop's avatar
Iustin Pop committed
1386 1387 1388
        </cmdsynopsis>

        <para>
1389 1390
          Starts one or more instances, depending on the following
          options. The four available modes are:
1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433
          <variablelist>
            <varlistentry>
              <term><option>--instance</option></term>
              <listitem>
                <simpara>will start the instances given as arguments
                (at least one argument required); this is the default
                selection</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>--node</term>
              <listitem>
                <simpara>will start the instances who have the given
                node as either primary or secondary</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><option>--primary</option></term>
              <listitem>
                <simpara>will start all instances whose primary node
                is in the list of nodes passed as arguments (at least
                one node required)</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><option>--secondary</option></term>
              <listitem>
                <simpara>will start all instances whose secondary node
                is in the list of nodes passed as arguments (at least
                one node required)</simpara>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>--all</term>
              <listitem>
                <simpara>will start all instances in the cluster (no
                arguments accepted)</simpara>
              </listitem>
            </varlistentry>
          </variablelist>
        </para>

        <para>
1434 1435 1436
          Note that although you can pass more than one selection
          option, the last one wins, so in order to guarantee the
          desired result, don't pass more than one such option.
Iustin Pop's avatar
Iustin Pop committed
1437 1438
        </para>

1439 1440 1441 1442
        <para>
          Use <option>--force</option> to start even if secondary disks are
          failing.
        </para>
Iustin Pop's avatar
Iustin Pop committed
1443

1444 1445 1446 1447 1448 1449
        <para>
          The <option>--force-multiple</option> will skip the
          interactive confirmation in the case the more than one
          instance will be affected.
        </para>

1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466
        <para>
          The <option>-H</option> and <option>-B</option> options
          specify extra, temporary hypervisor and backend parameters
          that can be used to start an instance with modified
          parameters. They can be useful for quick testing without
          having to modify an instance back and forth, e.g.:
          <screen>
# gnt-instance start -H root_args="single" instance1
# gnt-instance start -B memory=2048 instance2
          </screen>
          The first form will start the instance
          <userinput>instance1</userinput> in single-user mode, and
          the instance <userinput>instance2</userinput> with 2GB of
          RAM (this time only, unless that is the actual instance
          memory size already).
        </para>

1467 1468 1469 1470 1471 1472 1473
        <para>
          The <option>--submit</option> option is used to send the job to
          the master daemon but not wait for its completion. The job
          ID will be shown so that it can be examined via
          <command>gnt-job info</command>.
        </para>

Iustin Pop's avatar
Iustin Pop committed
1474 1475 1476 1477
        <para>
          Example:
          <screen>
# gnt-instance start instance1.example.com
1478 1479
# gnt-instance start --node node1.example.com node2.example.com
# gnt-instance start --all
Iustin Pop's avatar
Iustin Pop committed
1480 1481 1482 1483 1484 1485 1486 1487 1488
          </screen>
        </para>
      </refsect3>

      <refsect3>
        <title>SHUTDOWN</title>

        <cmdsynopsis>
          <command>shutdown</command>
1489
          <sbr>
1490 1491
          <arg>--force-multiple</arg>
          <sbr>
1492 1493 1494 1495 1496 1497 1498 1499
          <group choice="opt">
            <arg>--instance</arg>
            <arg>--node</arg>
            <arg>--primary</arg>
            <arg>--secondary</arg>
            <arg>--all</arg>
          </group>
          <sbr>
1500 1501
          <arg>--submit</arg>
          <sbr>
1502 1503
          <arg choice="opt"
          rep="repeat"><replaceable>name</replaceable></arg>
Iustin Pop's avatar
Iustin Pop committed
1504 1505 1506
        </cmdsynopsis>

        <para>