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 choice="req">-n <replaceable>node</replaceable></arg>
  66           <arg>-s <replaceable>disksize</replaceable></arg>
  67           <arg>-o <replaceable>os-type</replaceable></arg>
  68           <arg>-m <replaceable>memsize</replaceable></arg>
  69           <arg>-b <replaceable>bridge</replaceable></arg>
  70           <sbr>
  71           <arg choice="req">-t<group>
  72               <arg>diskless</arg>
  73               <arg>plain</arg>
  74               <arg>local_raid1</arg>
  75               <arg>remote_raid1</arg>
  76             </group>
  77           </arg>
  78           <arg choice="req"><replaceable>instance</replaceable></arg>
  79         </cmdsynopsis>
  80         <para>
  81           Creates a new instance on the specified
  82           host. <replaceable>instance</replaceable> must be in DNS and
  83           resolve to a IP in the same network as the nodes in the
  84           cluster.
  85         </para>
  86
  87         <para>
  88           The <option>-s</option> option specifies the disk size for
  89           the instance, in gigibytes (defaults to 20 GiB).
  90         </para>
  91
  92         <para>
  93           The <option>-o</option> options specifies the operating
  94           system to be installed. The available operating systems can
  95           be listed with <command>gnt-os list</command>.
  96         </para>
  97
  98         <para>
  99           The <option>-m</option> option specifies the memory size for
 100           the instance, in megibytes (defaults to 128 MiB).
 101         </para>
 102
 103         <para>
 104           The <option>-b</option> option specifies the bridge to which the
 105           instance will be connected. (defaults to the cluster-wide default
 106           bridge specified at cluster intialization time).
 107         </para>
 108
 109         <para>
 110           The <option>-t</option> options specifies the disk layout type for
 111           the instance. The available choices are:
 112           <variablelist>
 113             <varlistentry>
 114               <term>diskless</term>
 115               <listitem>
 116                 <para>
 117                   This creates an instance with no disks. Its useful for
 118                   testing only (or other special cases).
 119                 </para>
 120               </listitem>
 121             </varlistentry>
 122             <varlistentry>
 123               <term>plain</term>
 124               <listitem>
 125                 <para>Disk devices will be logical volumes.</para>
 126               </listitem>
 127             </varlistentry>
 128             <varlistentry>
 129               <term>local_raid1</term>
 130               <listitem>
 131                 <para>
 132                   Disk devices will be md raid1 arrays over two local
 133                   logical volumes.
 134                 </para>
 135               </listitem>
 136             </varlistentry>
 137             <varlistentry>
 138               <term>remote_raid1</term>
 139               <listitem>
 140                 <para>
 141                   Disk devices will be md raid1 arrays with one
 142                   component (so it's not actually raid1): a drbd device
 143                   between the instance's primary node and the node given
 144                   by the option <option>--secondary-node</option>.
 145                 </para>
 146               </listitem>
 147             </varlistentry>
 148           </variablelist>
 149         </para>
 150
 151         <para>
 152           The <option>--secondary-node</option> option is used with
 153           the remote raid disk template type and specifies the remote
 154           node.
 155         </para>
 156
 157         <para>
 158           If you do not want gnt-instance to wait for the disk mirror
 159           to be synced, use the <option>--no-wait-for-sync</option>
 160           option.
 161         </para>
 162
 163
 164         <para>
 165           Example:
 166           <screen>
 167 # gnt-instance add -t plain -s 30 -m 512 -n node1.example.com \
 168 > instance1.example.com
 169 # gnt-instance add -t remote_raid1 --secondary-node node3.example.com \
 170 > -s 30 -m 512 -n node1.example.com instance2.example.com
 171           </screen>
 172         </para>
 173
 174       </refsect3>
 175
 176       <refsect3>
 177         <title>REMOVE</title>
 178
 179         <cmdsynopsis>
 180           <command>remove</command>
 181           <arg choice="req"><replaceable>instance</replaceable></arg>
 182         </cmdsynopsis>
 183
 184         <para>
 185           Remove an instance. This will remove all data from the
 186           instance and there is <emphasis>no way back</emphasis>. If
 187           you are not sure if you use an instance again, use
 188           <command>shutdown</command> first and leave it in the
 189           shutdown state for a while.
 190         </para>
 191
 192         <para>
 193           Example:
 194           <screen>
 195 # gnt-instance remove instance1.example.com
 196           </screen>
 197         </para>
 198       </refsect3>
 199
 200       <refsect3>
 201         <title>LIST</title>
 202
 203         <cmdsynopsis>
 204           <command>list</command>
 205           <arg>--no-headers</arg>
 206           <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
 207           <arg>-o <replaceable>FIELD,...</replaceable></arg>
 208         </cmdsynopsis>
 209
 210         <para>
 211           Shows the currently configured instances with memory usage,
 212           disk usage, the node they are running on, and the CPU time,
 213           counted in seconds, used by each instance since its latest
 214           restart.
 215         </para>
 216
 217         <para>
 218           The <option>--no-headers</option> option will skip the
 219           initial header line. The <option>--separator</option> option
 220           takes an argument which denotes what will be used between
 221           the output fields. Both these options are to help scripting.
 222         </para>
 223
 224         <para>
 225           The <option>-o</option> option takes a comma-separated list
 226           of output fields. The available fields and their meaning
 227           are:
 228           <variablelist>
 229             <varlistentry>
 230               <term>name</term>
 231               <listitem>
 232                 <simpara>the instance name</simpara>
 233               </listitem>
 234             </varlistentry>
 235             <varlistentry>
 236               <term>os</term>
 237               <listitem>
 238                 <simpara>the OS of the instance</simpara>
 239               </listitem>
 240             </varlistentry>
 241             <varlistentry>
 242               <term>pnode</term>
 243               <listitem>
 244                 <simpara>the primary node of the instance</simpara>
 245               </listitem>
 246             </varlistentry>
 247             <varlistentry>
 248               <term>snodes</term>
 249               <listitem>
 250                 <simpara>comma-separated list of secondary-nodes for the
 251                   instance; usually this will be just one node</simpara>
 252               </listitem>
 253             </varlistentry>
 254             <varlistentry>
 255               <term>admin_state</term>
 256               <listitem>
 257                 <simpara>the desired state of the instance (either "yes"
 258                   or "no" denoting the instance should run or
 259                   not)</simpara>
 260               </listitem>
 261             </varlistentry>
 262             <varlistentry>
 263               <term>admin_ram</term>
 264               <listitem>
 265                 <simpara>the desired memory for the instance</simpara>
 266               </listitem>
 267             </varlistentry>
 268             <varlistentry>
 269               <term>disk_template</term>
 270               <listitem>
 271                 <simpara>the disk template of the instance</simpara>
 272               </listitem>
 273             </varlistentry>
 274             <varlistentry>
 275               <term>oper_state</term>
 276               <listitem>
 277                 <simpara>the actual state of the instance; can take of
 278                   the values "running", "stopped", "(node down)"</simpara>
 279               </listitem>
 280             </varlistentry>
 281             <varlistentry>
 282               <term>oper_ram</term>
 283               <listitem>
 284                 <simpara>the actual memory usage of the instance as seen
 285                   by the hypervisor</simpara>
 286               </listitem>
 287             </varlistentry>
 288             <varlistentry>
 289               <term>ip</term>
 290               <listitem>
 291                 <simpara>the ip address ganeti recognizes as associated with
 292                 the instance interface</simpara>
 293               </listitem>
 294             </varlistentry>
 295             <varlistentry>
 296               <term>mac</term>
 297               <listitem>
 298                 <simpara>the instance interface MAC address</simpara>
 299               </listitem>
 300             </varlistentry>
 301             <varlistentry>
 302               <term>bridge</term>
 303               <listitem>
 304                 <simpara>bridge the instance is connected to
 305                 </simpara>
 306               </listitem>
 307             </varlistentry>
 308           </variablelist>
 309         </para>
 310
 311         <para>
 312           There is a subtle grouping about the available output
 313           fields: all fields except for <option>oper_state</option>
 314           and <option>oper_ram</option> are configuration value and
 315           not run-time values. So if you don't select any of the
 316           <option>oper_*</option> fields, the query will be satisfied
 317           instantly from the cluster configuration, without having to
 318           ask the remote nodes for the data. This can be helpful for
 319           big clusters when you only want some data and it makes sense
 320           to specify a reduced set of output fields.
 321         </para>
 322
 323         <para>The default output field list is:
 324           <simplelist type="inline">
 325             <member>name</member>
 326             <member>os</member>
 327             <member>pnode</member>
 328             <member>admin_state</member>
 329             <member>oper_state</member>
 330             <member>oper_ram</member>
 331           </simplelist>.
 332         </para>
 333       </refsect3>
 334
 335       <refsect3>
 336         <title>INFO</title>
 337
 338         <cmdsynopsis>
 339           <command>info</command>
 340           <arg rep="repeat"><replaceable>instance</replaceable></arg>
 341         </cmdsynopsis>
 342
 343         <para>
 344           Show detailed information about the (given) instances. This
 345           is different from <command>list</command> as it shows
 346           detailed data about the instance's disks (especially useful
 347           for remote raid templates).
 348         </para>
 349       </refsect3>
 350
 351       <refsect3>
 352         <title>MODIFY</title>
 353
 354         <cmdsynopsis>
 355           <command>modify</command>
 356           <arg choice="opt">-m <replaceable>memsize</replaceable></arg>
 357           <arg choice="opt">-p <replaceable>vcpus</replaceable></arg>
 358           <arg choice="opt">-i <replaceable>ip</replaceable></arg>
 359           <arg choice="opt">-b <replaceable>bridge</replaceable></arg>
 360           <arg choice="req"><replaceable>instance</replaceable></arg>
 361         </cmdsynopsis>
 362
 363         <para>
 364           Modify the memory size, number of vcpus, ip address and/or bridge
 365           for an instance.
 366         </para>
 367
 368         <para>
 369           The memory size is given in MiB. Note that you need to give
 370           at least one of the arguments, otherwise the command
 371           complains.
 372         </para>
 373
 374         <para>
 375           All the changes take effect at the next restart. If the
 376           instance is running, there is no effect on the instance.
 377         </para>
 378       </refsect3>
 379
 380     </refsect2>
 381
 382     <refsect2>
 383       <title>Starting/stopping/connecting to console</title>
 384
 385       <refsect3>
 386         <title>STARTUP</title>
 387
 388         <cmdsynopsis>
 389           <command>startup</command>
 390           <arg>--extra=<replaceable>PARAMS</replaceable></arg>
 391           <arg choice="req"><replaceable>instance</replaceable></arg>
 392         </cmdsynopsis>
 393
 394         <para>
 395           Starts an instance. The node where to start the instance is
 396           taken from the configuration.
 397         </para>
 398
 399         <para>
 400           The <option>--extra</option> option is used to pass
 401           additional argument to the instance's kernel for this start
 402           only. Currently there is no way to specify a persistent set
 403           of arguments (beside the one hardcoded). Note that this may
 404           not apply to all virtualization types.
 405         </para>
 406
 407
 408         <para>
 409           Example:
 410           <screen>
 411 # gnt-instance start instance1.example.com
 412 # gnt-instance start --extra single test1.example.com
 413           </screen>
 414         </para>
 415       </refsect3>
 416
 417       <refsect3>
 418         <title>SHUTDOWN</title>
 419
 420         <cmdsynopsis>
 421           <command>shutdown</command>
 422           <arg choice="req"><replaceable>instance</replaceable></arg>
 423         </cmdsynopsis>
 424
 425         <para>
 426           Stops the instance. If the instance cannot be cleanly
 427           stopped during a hardcoded interval (currently 2 minutes),
 428           it will forcibly stop the instance (equivalent to switching
 429           off the power on a physical machine).
 430         </para>
 431
 432         <para>
 433           Example:
 434           <screen>
 435 # gnt-instance shutdown instance1.example.com
 436           </screen>
 437         </para>
 438       </refsect3>
 439
 440       <refsect3>
 441         <title>CONSOLE</title>
 442         <cmdsynopsis>
 443           <command>console</command>
 444           <arg choice="req"><replaceable>instance</replaceable></arg>
 445         </cmdsynopsis>
 446
 447         <para>
 448           Connects to the console of the given instance. If the instance
 449           is not up, an error is returned.
 450         </para>
 451
 452         <para>
 453           Example:
 454           <screen>
 455 # gnt-instance console instance1.example.com
 456           </screen>
 457         </para>
 458       </refsect3>
 459
 460     </refsect2>
 461
 462     <refsect2>
 463       <title>Disk management</title>
 464
 465       <refsect3>
 466         <title>REPLACE-DISKS</title>
 467
 468         <cmdsynopsis>
 469           <command>replace-disks</command>
 470           <arg choice="req">--new-secondary <replaceable>NODE</replaceable></arg>
 471           <arg choice="req"><replaceable>instance</replaceable></arg>
 472         </cmdsynopsis>
 473
 474         <para>
 475           This command does a full add and replace for both disks of
 476           an instance.  It basically does an
 477           <command>addmirror</command> and
 478           <command>removemirror</command> for both disks of the
 479           instance.
 480         </para>
 481
 482         <para>
 483           If you also want to replace the secondary node during this
 484           process (for example to fix a broken secondary node), you
 485           can do so using the <option>--new-secondary</option> option.
 486         </para>
 487       </refsect3>
 488
 489       <refsect3>
 490         <title>ADD-MIRROR</title>
 491         <cmdsynopsis>
 492           <command>add-mirror</command>
 493           <arg choice="req">-b <replaceable>sdX</replaceable></arg>
 494           <arg choice="req">-n <replaceable>node</replaceable></arg>
 495           <arg choice="req"><replaceable>instance</replaceable></arg>
 496         </cmdsynopsis>
 497         <para>
 498           Adds a new mirror to the disk layout of the instance, if the
 499           instance has a remote raid disk layout.
 500
 501           The new mirror member will be between the instance's primary
 502           node and the node given with the <option>-n</option> option.
 503         </para>
 504       </refsect3>
 505
 506       <refsect3>
 507         <title>REMOVE-MIRROR</title>
 508
 509         <cmdsynopsis>
 510           <command>removemirror</command>
 511           <arg choice="req">-b <replaceable>sdX</replaceable></arg>
 512           <arg choice="req">-p <replaceable>id</replaceable></arg>
 513           <arg choice="req"><replaceable>instance</replaceable></arg>
 514         </cmdsynopsis>
 515         <para>
 516           Removes a mirror componenent from the disk layout of the
 517           instance, if the instance has a remote raid disk layout.
 518         </para>
 519
 520         <para>
 521           You need to specifiy on which disk to act on using the
 522           <option>-b</option> option (either <filename>sda</filename>
 523           or <filename>sdb</filename>) and the mirror component, which
 524           is identified by the <option>-p</option> option. You can
 525           find the list of valid identifiers with the
 526           <command>info</command> command.
 527         </para>
 528
 529       <refsect3>
 530         <title>ACTIVATE-DISKS</title>
 531
 532         <cmdsynopsis>
 533           <command>activate-disks</command>
 534           <arg choice="req"><replaceable>instance</replaceable></arg>
 535         </cmdsynopsis>
 536         <para>
 537           Activates the block devices of the given instance. If
 538           successful, the command will show the location and name of
 539           the block devices:
 540           <screen>
 541 node1.example.com:sda:/dev/md0
 542 node1.example.com:sdb:/dev/md1
 543           </screen>
 544
 545           In this example, <emphasis>node1.example.com</emphasis> is
 546           the name of the node on which the devices have been
 547           activated. The <emphasis>sda</emphasis> and
 548           <emphasis>sdb</emphasis> are the names of the block devices
 549           inside the instance. <emphasis>/dev/md0</emphasis> and
 550           <emphasis>/dev/md1</emphasis> are the names of the block
 551           devices as visible on the node.
 552         </para>
 553
 554         <para>
 555           Note that it is safe to run this command while the instance
 556           is already running.
 557         </para>
 558       </refsect3>
 559
 560       <refsect3>
 561         <title>DEACTIVATE-DISKS</title>
 562
 563         <cmdsynopsis>
 564           <command>deactivate-disks</command>
 565           <arg choice="req"><replaceable>instance</replaceable></arg>
 566         </cmdsynopsis>
 567         <para>
 568           De-activates the block devices of the given instance. Note
 569           that if you run this command for a remote raid instance
 570           type, while it is running, it will not be able to shutdown
 571           the block devices on the primary node, but it will shutdown
 572           the block devices on the secondary nodes, thus breaking the
 573           replication.
 574         </para>
 575
 576       </refsect3>
 577
 578     </refsect2>
 579
 580     <refsect2>
 581       <title>Recovery</title>
 582
 583       <refsect3>
 584         <title>FAILOVER</title>
 585
 586         <cmdsynopsis>
 587           <command>failover</command>
 588           <arg>-f</arg>
 589           <arg>--ignore-consistency</arg>
 590           <arg choice="req"><replaceable>instance</replaceable></arg>
 591         </cmdsynopsis>
 592
 593         <para>
 594           Failover will fail the instance over its secondary
 595           node. This works only for instances having a remote raid
 596           disk layout.
 597         </para>
 598
 599         <para>
 600           Normally the failover will check the consistency of the
 601           disks before failing over the instance. If you are trying to
 602           migrate instances off a dead node, this will fail. Use the
 603           <option>--ignore-consistency</option> option for this
 604           purpose.
 605         </para>
 606
 607         <para>
 608           Example:
 609           <screen>
 610 # gnt-instance failover instance1.example.com
 611           </screen>
 612         </para>
 613       </refsect3>
 614
 615     </refsect2>
 616
 617   </refsect1>
 618
 619   &footer;
 620
 621 </refentry>
 622
 623 <!-- Keep this comment at the end of the file
 624 Local variables:
 625 mode: sgml
 626 sgml-omittag:t
 627 sgml-shorttag:t
 628 sgml-minimize-attributes:nil
 629 sgml-always-quote-attributes:t
 630 sgml-indent-step:2
 631 sgml-indent-data:t
 632 sgml-parent-document:nil
 633 sgml-default-dtd-file:nil
 634 sgml-exposed-tags:nil
 635 sgml-local-catalogs:nil
 636 sgml-local-ecat-files:nil
 637 End:
 638 -->