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         information.
  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; the cluster
 418               still communicates with drained nodes but excludes them
 419               from allocation operations</simpara>
 420             </listitem>
 421           </varlistentry>
 422           <varlistentry>
 423             <term>offline</term>
 424             <listitem>
 425               <simpara>whether the node is offline or not; if offline,
 426               the cluster does not communicate with offline nodes;
 427               useful for nodes that are not reachable in order to
 428               avoid delays</simpara>
 429             </listitem>
 430           </varlistentry>
 431           <varlistentry>
 432             <term>role</term>
 433             <listitem>
 434               <para>
 435                 A condensed version of the node flags; this field will
 436                 output a one-character field, with the following
 437                 possible values:
 438                 <itemizedlist>
 439                   <listitem>
 440                     <simpara><emphasis>M</emphasis> for the master
 441                     node</simpara>
 442                   </listitem>
 443                   <listitem>
 444                     <simpara><emphasis>C</emphasis> for a master
 445                     candidate</simpara>
 446                   </listitem>
 447                   <listitem>
 448                     <simpara><emphasis>R</emphasis> for a regular
 449                     node</simpara>
 450                   </listitem>
 451                   <listitem>
 452                     <simpara><emphasis>D</emphasis> for a drained
 453                     node</simpara>
 454                   </listitem>
 455                   <listitem>
 456                     <simpara><emphasis>O</emphasis> for an offline
 457                     node</simpara>
 458                   </listitem>
 459                 </itemizedlist>
 460               </para>
 461             </listitem>
 462           </varlistentry>
 463         </variablelist>
 464       </para>
 465
 466       <para>
 467         If the value of the option starts with the character
 468         <constant>+</constant>, the new fields will be added to the
 469         default list. This allows to quickly see the default list plus
 470         a few other fields, instead of retyping the entire list of
 471         fields.
 472       </para>
 473
 474       <para>
 475         Note that some of this fields are known from the configuration
 476         of the cluster (e.g. <simplelist type="inline">
 477         <member>name</member> <member>pinst</member>
 478         <member>sinst</member> <member>pip</member>
 479         <member>sip</member> </simplelist> and thus the master does
 480         not need to contact the node for this data (making the listing
 481         fast if only fields from this set are selected), whereas the
 482         other fields are "live" fields and we need to make a query to
 483         the cluster nodes.
 484       </para>
 485
 486       <para>
 487         Depending on the virtualization type and implementation
 488         details, the mtotal, mnode and mfree may have slighly varying
 489         meanings. For example, some solutions share the node memory
 490         with the pool of memory used for instances
 491         (<acronym>KVM</acronym>), whereas others have separate memory
 492         for the node and for the instances (Xen).
 493       </para>
 494
 495       <para>
 496         If no node names are given, then all nodes are
 497         queried. Otherwise, only the given nodes will be listed.
 498       </para>
 499     </refsect2>
 500
 501     <refsect2>
 502       <title>LIST-TAGS</title>
 503
 504       <cmdsynopsis>
 505         <command>list-tags</command>
 506         <arg choice="req"><replaceable>nodename</replaceable></arg>
 507       </cmdsynopsis>
 508
 509       <para>List the tags of the given node.</para>
 510     </refsect2>
 511
 512     <refsect2>
 513       <title>MIGRATE</title>
 514       <cmdsynopsis>
 515         <command>migrate</command>
 516         <arg>-f</arg>
 517         <arg>--non-live</arg>
 518         <arg choice="req"><replaceable>node</replaceable></arg>
 519       </cmdsynopsis>
 520
 521       <para>
 522         This command will migrate all instances having the given
 523         node as primary to their secondary nodes. This works only for
 524         instances having a drbd disk template.
 525       </para>
 526
 527       <para>
 528         As for the <command>gnt-instance migrate</command> command,
 529         the <option>--no-live</option> option can be given to do a
 530         non-live migration.
 531       </para>
 532
 533       <para>
 534         Example:
 535         <screen>
 536           # gnt-node migrate node1.example.com
 537         </screen>
 538       </para>
 539
 540     </refsect2>
 541
 542     <refsect2>
 543       <title>MODIFY</title>
 544       <cmdsynopsis>
 545         <command>modify</command>
 546         <arg>-f</arg>
 547         <arg>--submit</arg>
 548         <arg>--master-candidate=<option>yes|no</option></arg>
 549         <arg>--drained=<option>yes|no</option></arg>
 550         <arg>--offline=<option>yes|no</option></arg>
 551         <arg choice="req"><replaceable>node</replaceable></arg>
 552       </cmdsynopsis>
 553
 554       <para>
 555         This command changes the role of the node. Each options takes
 556         either a literal <literal>yes</literal> or
 557         <literal>no</literal>, and only one option should be given as
 558         <literal>yes</literal>. The meaning of the roles are described
 559         in the manpage <citerefentry>
 560         <refentrytitle>ganeti</refentrytitle> <manvolnum>7</manvolnum>
 561         </citerefentry>.
 562       </para>
 563
 564       <para>
 565         In case a node is demoted from the master candidate role, but
 566         there are not enough new nodes for this case, the operation
 567         will be refused. To override this check, pass the
 568         <option>--force</option> option.
 569       </para>
 570
 571       <para>
 572         Example (setting a node offline, which will demote it from
 573         master candidate role if is in that role):
 574         <screen>
 575 # gnt-node modify --offline=yes node1.example.com
 576         </screen>
 577       </para>
 578
 579       <para>Example (setting the node back to online and master candidate):
 580         <screen>
 581 # gnt-node modify --offline=no --master-candidate=yes node1.example.com
 582         </screen>
 583       </para>
 584
 585     </refsect2>
 586
 587     <refsect2>
 588       <title>REMOVE</title>
 589
 590       <cmdsynopsis>
 591         <command>remove</command>
 592         <arg choice="req"><replaceable>nodename</replaceable></arg>
 593       </cmdsynopsis>
 594
 595       <para>
 596         Removes a node from the cluster. Instances must be removed or
 597         migrated to another cluster before.
 598       </para>
 599
 600       <para>
 601         Example:
 602         <screen>
 603 # gnt-node remove node5.example.com
 604         </screen>
 605       </para>
 606     </refsect2>
 607
 608     <refsect2>
 609       <title>REMOVE-TAGS</title>
 610       <cmdsynopsis>
 611         <command>remove-tags</command>
 612         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 613         <arg choice="req"><replaceable>nodename</replaceable></arg>
 614         <arg choice="req"
 615         rep="repeat"><replaceable>tag</replaceable></arg>
 616       </cmdsynopsis>
 617
 618       <para>
 619         Remove tags from the given node. If any of the tags are not
 620         existing on the node, the entire operation will abort.
 621       </para>
 622
 623       <para>
 624         If the <option>--from</option> option is given, the list of
 625         tags will be extended with the contents of that file (each
 626         line becomes a tag). In this case, there is not need to pass
 627         tags on the command line (if you do, both sources will be
 628         used). A file name of - will be interpreted as stdin.
 629       </para>
 630     </refsect2>
 631
 632     <refsect2>
 633       <title>VOLUMES</title>
 634
 635       <cmdsynopsis>
 636         <command>volumes</command>
 637         <arg>--no-headers</arg>
 638         <arg>--human-readable</arg>
 639         <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
 640         <arg>--output=<replaceable>FIELDS</replaceable></arg>
 641         <sbr>
 642         <arg rep="repeat"><replaceable>node</replaceable></arg>
 643       </cmdsynopsis>
 644
 645       <para>
 646         Lists all logical volumes and their physical disks from the node(s)
 647         provided.
 648       </para>
 649
 650       <para>
 651         The <option>--no-headers</option> option will skip the initial
 652         header line. The <option>--separator</option> option takes an
 653         argument which denotes what will be used between the output
 654         fields. Both these options are to help scripting.
 655       </para>
 656
 657       <para>
 658         The units used to display the numeric values in the output
 659         varies, depending on the options given. By default, the values
 660         will be formatted in the most appropriate unit. If the
 661         <option>--separator</option> option is given, then the values
 662         are shown in mebibytes to allow parsing by scripts. In both
 663         cases, the <option>--units</option> option can be used to
 664         enforce a given output unit.
 665       </para>
 666
 667       <para>
 668         The <option>-o</option> option takes a comma-separated list of
 669         output fields. The available fields and their meaning are:
 670         <variablelist>
 671           <varlistentry>
 672             <term>node</term>
 673             <listitem>
 674               <simpara>the node name on which the volume exists</simpara>
 675             </listitem>
 676           </varlistentry>
 677           <varlistentry>
 678             <term>phys</term>
 679             <listitem>
 680               <simpara>the physical drive (on which the LVM physical
 681               volume lives)</simpara>
 682             </listitem>
 683           </varlistentry>
 684           <varlistentry>
 685             <term>vg</term>
 686             <listitem>
 687               <simpara>the volume group name</simpara>
 688             </listitem>
 689           </varlistentry>
 690           <varlistentry>
 691             <term>name</term>
 692             <listitem>
 693               <simpara>the logical volume name</simpara>
 694             </listitem>
 695           </varlistentry>
 696           <varlistentry>
 697             <term>size</term>
 698             <listitem>
 699               <simpara>the logical volume size</simpara>
 700             </listitem>
 701           </varlistentry>
 702           <varlistentry>
 703             <term>instance</term>
 704             <listitem>
 705               <simpara>The name of the instance to which this volume
 706               belongs, or (in case it's an orphan volume) the
 707               character <quote>-</quote></simpara>
 708             </listitem>
 709           </varlistentry>
 710         </variablelist>
 711       </para>
 712
 713       <para>
 714         Example:
 715         <screen>
 716 # gnt-node volumes node5.example.com
 717 Node              PhysDev   VG    Name                                 Size Instance
 718 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11000.meta 128  instance1.example.com
 719 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  instance1.example.com
 720         </screen>
 721       </para>
 722     </refsect2>
 723
 724   </refsect1>
 725
 726   &footer;
 727
 728 </refentry>
 729
 730 <!-- Keep this comment at the end of the file
 731 Local variables:
 732 mode: sgml
 733 sgml-omittag:t
 734 sgml-shorttag:t
 735 sgml-minimize-attributes:nil
 736 sgml-always-quote-attributes:t
 737 sgml-indent-step:2
 738 sgml-indent-data:t
 739 sgml-parent-document:nil
 740 sgml-default-dtd-file:nil
 741 sgml-exposed-tags:nil
 742 sgml-local-catalogs:nil
 743 sgml-local-ecat-files:nil
 744 End:
 745 -->