code.grnet.gr Git - ganeti-local/blob - man/gnt-node.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>February 12, 2009</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-node</refentrytitle>">
  10   <!ENTITY dhpackage   "gnt-node">
  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       <year>2008</year>
  24       <year>2009</year>
  25       <holder>Google Inc.</holder>
  26     </copyright>
  27     &dhdate;
  28   </refentryinfo>
  29   <refmeta>
  30     &dhucpackage;
  31
  32     &dhsection;
  33     <refmiscinfo>ganeti 2.0</refmiscinfo>
  34   </refmeta>
  35   <refnamediv>
  36     <refname>&dhpackage;</refname>
  37
  38     <refpurpose>node administration</refpurpose>
  39   </refnamediv>
  40   <refsynopsisdiv>
  41     <cmdsynopsis>
  42       <command>&dhpackage; </command>
  43
  44       <arg choice="req">command</arg>
  45       <arg>arguments...</arg>
  46     </cmdsynopsis>
  47   </refsynopsisdiv>
  48   <refsect1>
  49     <title>DESCRIPTION</title>
  50
  51     <para>
  52       The <command>&dhpackage;</command> is used for managing the
  53       (physical) nodes in the ganeti system.
  54     </para>
  55
  56   </refsect1>
  57   <refsect1>
  58     <title>COMMANDS</title>
  59
  60     <refsect2>
  61       <title>ADD</title>
  62
  63       <cmdsynopsis>
  64         <command>add</command>
  65         <arg>--readd</arg>
  66         <arg>-s <replaceable>secondary_ip</replaceable></arg>
  67         <arg choice="req"><replaceable>nodename</replaceable></arg>
  68       </cmdsynopsis>
  69
  70       <para>
  71         Adds the given node to the cluster.
  72       </para>
  73
  74       <para>
  75         This command is used to join a new node to the cluster. You
  76         will have to provide the password for root of the node to be
  77         able to add the node in the cluster. The command needs to be
  78         run on the ganeti master.
  79       </para>
  80
  81       <para>
  82         Note that the command is potentially destructive, as it will
  83         forcibly join the specified host the cluster, not paying
  84         attention to its current status (it could be already in a
  85         cluster, etc.)
  86       </para>
  87
  88       <para>
  89         The <option>-s</option> is used in dual-home clusters and
  90         specifies the new node's IP in the secondary network. See the
  91         discussion in <citerefentry>
  92         <refentrytitle>gnt-cluster</refentrytitle>
  93         <manvolnum>8</manvolnum> </citerefentry> for more
  94         informations.
  95       </para>
  96
  97       <para>
  98         In case you're readding a node after hardware failure, you can
  99         use the <option>--readd</option> parameter. In this case, you
 100         don't need to pass the secondary IP again, it will reused from
 101         the cluster. Also, the <literal>drained</literal> and
 102         <literal>offline</literal> flags of the node will be cleared
 103         before re-adding it.
 104       </para>
 105
 106       <para>
 107         Example:
 108         <screen>
 109 # gnt-node add node5.example.com
 110 # gnt-node add -s 192.168.44.5 node5.example.com
 111         </screen>
 112       </para>
 113     </refsect2>
 114
 115     <refsect2>
 116       <title>ADD-TAGS</title>
 117
 118       <cmdsynopsis>
 119         <command>add-tags</command>
 120         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 121         <arg choice="req"><replaceable>nodename</replaceable></arg>
 122         <arg choice="req"
 123         rep="repeat"><replaceable>tag</replaceable></arg>
 124       </cmdsynopsis>
 125
 126       <para>
 127         Add tags to the given node. If any of the tags contains
 128         invalid characters, the entire operation will abort.
 129       </para>
 130
 131       <para>
 132         If the <option>--from</option> option is given, the list of
 133         tags will be extended with the contents of that file (each
 134         line becomes a tag). In this case, there is not need to pass
 135         tags on the command line (if you do, both sources will be
 136         used). A file name of - will be interpreted as stdin.
 137       </para>
 138     </refsect2>
 139
 140     <refsect2>
 141       <title>EVACUATE</title>
 142
 143       <cmdsynopsis>
 144         <command>evacuate</command>
 145         <arg>-f</arg>
 146         <group>
 147           <arg>--iallocator <replaceable>NAME</replaceable></arg>
 148           <arg>--new-secondary <replaceable>destination_node</replaceable></arg>
 149         </group>
 150         <arg choice="req"><replaceable>node</replaceable></arg>
 151       </cmdsynopsis>
 152
 153       <para>
 154         This command will move all secondary instances away from the
 155         given node. It works only for instances having a drbd disk
 156         template.
 157       </para>
 158
 159       <para>
 160         The new location for the instances can be specified in two ways:
 161         <itemizedlist>
 162           <listitem>
 163             <simpara>as a single node for all instances, via the
 164             <option>--new-secondary</option> option</simpara>
 165           </listitem>
 166           <listitem>
 167             <simpara>or via the <option>--iallocator</option> option,
 168             giving a script name as parameter, so each instance will
 169             be in turn placed on the (per the script) optimal
 170             node</simpara>
 171           </listitem>
 172         </itemizedlist>
 173       </para>
 174
 175       <para>
 176         Example:
 177         <screen>
 178           # gnt-node evacuate -I dumb node3.example.com
 179         </screen>
 180       </para>
 181     </refsect2>
 182
 183     <refsect2>
 184       <title>FAILOVER</title>
 185
 186       <cmdsynopsis>
 187         <command>failover</command>
 188         <arg>-f</arg>
 189         <arg>--ignore-consistency</arg>
 190         <arg choice="req"><replaceable>node</replaceable></arg>
 191       </cmdsynopsis>
 192
 193       <para>
 194         This command will fail over all instances having the given
 195         node as primary to their secondary nodes. This works only for
 196         instances having a drbd disk template.
 197       </para>
 198
 199       <para>
 200         Normally the failover will check the consistency of the disks
 201         before failing over the instance. If you are trying to migrate
 202         instances off a dead node, this will fail. Use the
 203         <option>--ignore-consistency</option> option for this purpose.
 204       </para>
 205
 206       <para>
 207         Example:
 208         <screen>
 209           # gnt-node failover node1.example.com
 210         </screen>
 211       </para>
 212     </refsect2>
 213
 214     <refsect2>
 215       <title>INFO</title>
 216
 217       <cmdsynopsis>
 218         <command>info</command>
 219         <arg rep="repeat"><replaceable>node</replaceable></arg>
 220       </cmdsynopsis>
 221
 222       <para>
 223         Show detailed information about the nodes in the cluster. If you
 224         don't give any arguments, all nodes will be shows, otherwise the
 225         output will be restricted to the given names.
 226       </para>
 227     </refsect2>
 228
 229     <refsect2>
 230       <title>LIST</title>
 231
 232       <cmdsynopsis>
 233         <command>list</command>
 234         <arg>--sync</arg>
 235         <sbr>
 236         <arg>--no-headers</arg>
 237         <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
 238         <sbr>
 239         <arg>--units=<replaceable>UNITS</replaceable></arg>
 240         <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>
 241         <sbr>
 242         <arg rep="repeat">node</arg>
 243       </cmdsynopsis>
 244
 245       <para>
 246         Lists the nodes in the cluster.
 247       </para>
 248
 249       <para>
 250         The <option>--no-headers</option> option will skip the initial
 251         header line. The <option>--separator</option> option takes an
 252         argument which denotes what will be used between the output
 253         fields. Both these options are to help scripting.
 254       </para>
 255
 256       <para>
 257         The units used to display the numeric values in the output
 258         varies, depending on the options given. By default, the values
 259         will be formatted in the most appropriate unit. If the
 260         <option>--separator</option> option is given, then the values
 261         are shown in mebibytes to allow parsing by scripts. In both
 262         cases, the <option>--units</option> option can be used to
 263         enforce a given output unit.
 264       </para>
 265
 266       <para>
 267         By default, the query of nodes will be done in parallel with
 268         any running jobs. This might give inconsistent results for the
 269         free disk/memory. The <option>--sync</option> can be used to
 270         grab locks for all the nodes and ensure consistent view of the
 271         cluster (but this might stall the query for a long time).
 272       </para>
 273
 274       <para>
 275         The <option>-o</option> option takes a comma-separated list of
 276         output fields. The available fields and their meaning are:
 277         <variablelist>
 278           <varlistentry>
 279             <term>name</term>
 280             <listitem>
 281               <simpara>the node name</simpara>
 282             </listitem>
 283           </varlistentry>
 284           <varlistentry>
 285             <term>pinst_cnt</term>
 286             <listitem>
 287               <simpara>the number of instances having this node as
 288               primary</simpara>
 289             </listitem>
 290           </varlistentry>
 291           <varlistentry>
 292             <term>pinst_list</term>
 293             <listitem>
 294               <simpara>the list of instances having this node as
 295               primary, comma separated</simpara>
 296             </listitem>
 297           </varlistentry>
 298           <varlistentry>
 299             <term>sinst_cnt</term>
 300             <listitem>
 301               <simpara>the number of instances having this node as a
 302               secondary node</simpara>
 303             </listitem>
 304           </varlistentry>
 305           <varlistentry>
 306             <term>sinst_list</term>
 307             <listitem>
 308               <simpara>the list of instances having this node as a
 309               secondary node, comma separated</simpara>
 310             </listitem>
 311           </varlistentry>
 312           <varlistentry>
 313             <term>pip</term>
 314             <listitem>
 315               <simpara>the primary ip of this node (used for cluster
 316               communication)</simpara>
 317             </listitem>
 318           </varlistentry>
 319           <varlistentry>
 320             <term>sip</term>
 321             <listitem>
 322               <simpara>
 323                 the secondary ip of this node (used for data
 324                 replication in dual-ip clusters, see <citerefentry>
 325                 <refentrytitle>gnt-cluster</refentrytitle>
 326                 <manvolnum>8</manvolnum>
 327                 </citerefentry>
 328               </simpara>
 329             </listitem>
 330           </varlistentry>
 331           <varlistentry>
 332             <term>dtotal</term>
 333             <listitem>
 334               <simpara>total disk space in the volume group used for
 335               instance disk allocations</simpara>
 336             </listitem>
 337           </varlistentry>
 338           <varlistentry>
 339             <term>dfree</term>
 340             <listitem>
 341               <simpara>available disk space in the volume group</simpara>
 342             </listitem>
 343           </varlistentry>
 344           <varlistentry>
 345             <term>mtotal</term>
 346             <listitem>
 347               <simpara>total memory on the physical node</simpara>
 348             </listitem>
 349           </varlistentry>
 350           <varlistentry>
 351             <term>mnode</term>
 352             <listitem>
 353               <simpara>the memory used by the node itself</simpara>
 354             </listitem>
 355           </varlistentry>
 356           <varlistentry>
 357             <term>mfree</term>
 358             <listitem>
 359               <simpara>memory available for instance
 360               allocations</simpara>
 361             </listitem>
 362           </varlistentry>
 363           <varlistentry>
 364             <term>bootid</term>
 365             <listitem>
 366               <simpara>the node bootid value; this is a linux specific
 367               feature that assigns a new UUID to the node at each boot
 368               and can be use to detect node reboots (by tracking
 369               changes in this value)</simpara>
 370             </listitem>
 371           </varlistentry>
 372           <varlistentry>
 373             <term>tags</term>
 374             <listitem>
 375               <simpara>comma-separated list of the node's
 376               tags</simpara>
 377             </listitem>
 378           </varlistentry>
 379           <varlistentry>
 380             <term>serial_no</term>
 381             <listitem>
 382               <simpara>the so called 'serial number' of the instance;
 383               this is a numeric field that is incremented each time
 384               the instance is modified, and it can be used to detect
 385               modifications</simpara>
 386             </listitem>
 387           </varlistentry>
 388           <varlistentry>
 389             <term>ctotal</term>
 390             <listitem>
 391               <simpara>the toal number of logical processors</simpara>
 392             </listitem>
 393           </varlistentry>
 394           <varlistentry>
 395             <term>cnodes</term>
 396             <listitem>
 397               <simpara>the number of NUMA domains on the node, if the
 398               hypervisor can export this information</simpara>
 399             </listitem>
 400           </varlistentry>
 401           <varlistentry>
 402             <term>csockets</term>
 403             <listitem>
 404               <simpara>the number of physical CPU sockets, if the
 405               hypervisor can export this information</simpara>
 406             </listitem>
 407           </varlistentry>
 408           <varlistentry>
 409             <term>master_candidate</term>
 410             <listitem>
 411               <simpara>whether the node is a master candidate or not</simpara>
 412             </listitem>
 413           </varlistentry>
 414           <varlistentry>
 415             <term>drained</term>
 416             <listitem>
 417               <simpara>whether the node is drained or not</simpara>
 418             </listitem>
 419           </varlistentry>
 420           <varlistentry>
 421             <term>offline</term>
 422             <listitem>
 423               <simpara>whether the node is offline or not</simpara>
 424             </listitem>
 425           </varlistentry>
 426         </variablelist>
 427       </para>
 428
 429       <para>
 430         If the value of the option starts with the character
 431         <constant>+</constant>, the new fields will be added to the
 432         default list. This allows to quickly see the default list plus
 433         a few other fields, instead of retyping the entire list of
 434         fields.
 435       </para>
 436
 437       <para>
 438         Note that some of this fields are known from the configuration
 439         of the cluster (e.g. <simplelist type="inline">
 440         <member>name</member> <member>pinst</member>
 441         <member>sinst</member> <member>pip</member>
 442         <member>sip</member> </simplelist> and thus the master does
 443         not need to contact the node for this data (making the listing
 444         fast if only fields from this set are selected), whereas the
 445         other fields are "live" fields and we need to make a query to
 446         the cluster nodes.
 447       </para>
 448
 449       <para>
 450         Depending on the virtualization type and implementation
 451         details, the mtotal, mnode and mfree may have slighly varying
 452         meanings. For example, some solutions share the node memory
 453         with the pool of memory used for instances
 454         (<acronym>KVM</acronym>), whereas others have separate memory
 455         for the node and for the instances (Xen).
 456       </para>
 457
 458       <para>
 459         If no node names are given, then all nodes are
 460         queried. Otherwise, only the given nodes will be listed.
 461       </para>
 462     </refsect2>
 463
 464     <refsect2>
 465       <title>LIST-TAGS</title>
 466
 467       <cmdsynopsis>
 468         <command>list-tags</command>
 469         <arg choice="req"><replaceable>nodename</replaceable></arg>
 470       </cmdsynopsis>
 471
 472       <para>List the tags of the given node.</para>
 473     </refsect2>
 474
 475     <refsect2>
 476       <title>MIGRATE</title>
 477       <cmdsynopsis>
 478         <command>migrate</command>
 479         <arg>-f</arg>
 480         <arg>--non-live</arg>
 481         <arg choice="req"><replaceable>node</replaceable></arg>
 482       </cmdsynopsis>
 483
 484       <para>
 485         This command will migrate all instances having the given
 486         node as primary to their secondary nodes. This works only for
 487         instances having a drbd disk template.
 488       </para>
 489
 490       <para>
 491         As for the <command>gnt-instance migrate</command> command,
 492         the <option>--no-live</option> option can be given to do a
 493         non-live migration.
 494       </para>
 495
 496       <para>
 497         Example:
 498         <screen>
 499           # gnt-node migrate node1.example.com
 500         </screen>
 501       </para>
 502
 503     </refsect2>
 504
 505     <refsect2>
 506       <title>MODIFY</title>
 507       <cmdsynopsis>
 508         <command>modify</command>
 509         <arg>-f</arg>
 510         <arg>--submit</arg>
 511         <arg>--master-candidate=<option>yes|no</option></arg>
 512         <arg>--drained=<option>yes|no</option></arg>
 513         <arg>--offline=<option>yes|no</option></arg>
 514         <arg choice="req"><replaceable>node</replaceable></arg>
 515       </cmdsynopsis>
 516
 517       <para>
 518         This command changes the role of the node. Each options takes
 519         either a literal <literal>yes</literal> or
 520         <literal>no</literal>, and only one option should be given as
 521         <literal>yes</literal>. The meaning of the roles are described
 522         in the manpage <citerefentry>
 523         <refentrytitle>ganeti</refentrytitle> <manvolnum>7</manvolnum>
 524         </citerefentry>.
 525       </para>
 526
 527       <para>
 528         In case a node is demoted from the master candidate role, but
 529         there are not enough new nodes for this case, the operation
 530         will be refused. To override this check, pass the
 531         <option>--force</option> option.
 532       </para>
 533
 534       <para>
 535         Example (setting a node offline, which will demote it from
 536         master candidate role if is in that role):
 537         <screen>
 538 # gnt-node modify --offline=yes node1.example.com
 539         </screen>
 540       </para>
 541
 542       <para>Example (setting the node back to online and master candidate):
 543         <screen>
 544 # gnt-node modify --offline=no --master-candidate=yes node1.example.com
 545         </screen>
 546       </para>
 547
 548     </refsect2>
 549
 550     <refsect2>
 551       <title>REMOVE</title>
 552
 553       <cmdsynopsis>
 554         <command>remove</command>
 555         <arg choice="req"><replaceable>nodename</replaceable></arg>
 556       </cmdsynopsis>
 557
 558       <para>
 559         Removes a node from the cluster. Instances must be removed or
 560         migrated to another cluster before.
 561       </para>
 562
 563       <para>
 564         Example:
 565         <screen>
 566 # gnt-node remove node5.example.com
 567         </screen>
 568       </para>
 569     </refsect2>
 570
 571     <refsect2>
 572       <title>REMOVE-TAGS</title>
 573       <cmdsynopsis>
 574         <command>remove-tags</command>
 575         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 576         <arg choice="req"><replaceable>nodename</replaceable></arg>
 577         <arg choice="req"
 578         rep="repeat"><replaceable>tag</replaceable></arg>
 579       </cmdsynopsis>
 580
 581       <para>
 582         Remove tags from the given node. If any of the tags are not
 583         existing on the node, the entire operation will abort.
 584       </para>
 585
 586       <para>
 587         If the <option>--from</option> option is given, the list of
 588         tags will be extended with the contents of that file (each
 589         line becomes a tag). In this case, there is not need to pass
 590         tags on the command line (if you do, both sources will be
 591         used). A file name of - will be interpreted as stdin.
 592       </para>
 593     </refsect2>
 594
 595     <refsect2>
 596       <title>VOLUMES</title>
 597
 598       <cmdsynopsis>
 599         <command>volumes</command>
 600         <arg>--no-headers</arg>
 601         <arg>--human-readable</arg>
 602         <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
 603         <arg>--output=<replaceable>FIELDS</replaceable></arg>
 604         <sbr>
 605         <arg rep="repeat"><replaceable>node</replaceable></arg>
 606       </cmdsynopsis>
 607
 608       <para>
 609         Lists all logical volumes and their physical disks from the node(s)
 610         provided.
 611       </para>
 612
 613       <para>
 614         The <option>--no-headers</option> option will skip the initial
 615         header line. The <option>--separator</option> option takes an
 616         argument which denotes what will be used between the output
 617         fields. Both these options are to help scripting.
 618       </para>
 619
 620       <para>
 621         The units used to display the numeric values in the output
 622         varies, depending on the options given. By default, the values
 623         will be formatted in the most appropriate unit. If the
 624         <option>--separator</option> option is given, then the values
 625         are shown in mebibytes to allow parsing by scripts. In both
 626         cases, the <option>--units</option> option can be used to
 627         enforce a given output unit.
 628       </para>
 629
 630       <para>
 631         The <option>-o</option> option takes a comma-separated list of
 632         output fields. The available fields and their meaning are:
 633         <variablelist>
 634           <varlistentry>
 635             <term>node</term>
 636             <listitem>
 637               <simpara>the node name on which the volume exists</simpara>
 638             </listitem>
 639           </varlistentry>
 640           <varlistentry>
 641             <term>phys</term>
 642             <listitem>
 643               <simpara>the physical drive (on which the LVM physical
 644               volume lives)</simpara>
 645             </listitem>
 646           </varlistentry>
 647           <varlistentry>
 648             <term>vg</term>
 649             <listitem>
 650               <simpara>the volume group name</simpara>
 651             </listitem>
 652           </varlistentry>
 653           <varlistentry>
 654             <term>name</term>
 655             <listitem>
 656               <simpara>the logical volume name</simpara>
 657             </listitem>
 658           </varlistentry>
 659           <varlistentry>
 660             <term>size</term>
 661             <listitem>
 662               <simpara>the logical volume size</simpara>
 663             </listitem>
 664           </varlistentry>
 665           <varlistentry>
 666             <term>instance</term>
 667             <listitem>
 668               <simpara>The name of the instance to which this volume
 669               belongs, or (in case it's an orphan volume) the
 670               character <quote>-</quote></simpara>
 671             </listitem>
 672           </varlistentry>
 673         </variablelist>
 674       </para>
 675
 676       <para>
 677         Example:
 678         <screen>
 679 # gnt-node volumes node5.example.com
 680 Node              PhysDev   VG    Name                                 Size Instance
 681 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11000.meta 128  instance1.example.com
 682 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  instance1.example.com
 683         </screen>
 684       </para>
 685     </refsect2>
 686
 687   </refsect1>
 688
 689   &footer;
 690
 691 </refentry>
 692
 693 <!-- Keep this comment at the end of the file
 694 Local variables:
 695 mode: sgml
 696 sgml-omittag:t
 697 sgml-shorttag:t
 698 sgml-minimize-attributes:nil
 699 sgml-always-quote-attributes:t
 700 sgml-indent-step:2
 701 sgml-indent-data:t
 702 sgml-parent-document:nil
 703 sgml-default-dtd-file:nil
 704 sgml-exposed-tags:nil
 705 sgml-local-catalogs:nil
 706 sgml-local-ecat-files:nil
 707 End:
 708 -->