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>REMOVE</title>
 507
 508       <cmdsynopsis>
 509         <command>remove</command>
 510         <arg choice="req"><replaceable>nodename</replaceable></arg>
 511       </cmdsynopsis>
 512
 513       <para>
 514         Removes a node from the cluster. Instances must be removed or
 515         migrated to another cluster before.
 516       </para>
 517
 518       <para>
 519         Example:
 520         <screen>
 521 # gnt-node remove node5.example.com
 522         </screen>
 523       </para>
 524     </refsect2>
 525
 526     <refsect2>
 527       <title>REMOVE-TAGS</title>
 528       <cmdsynopsis>
 529         <command>remove-tags</command>
 530         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 531         <arg choice="req"><replaceable>nodename</replaceable></arg>
 532         <arg choice="req"
 533         rep="repeat"><replaceable>tag</replaceable></arg>
 534       </cmdsynopsis>
 535
 536       <para>
 537         Remove tags from the given node. If any of the tags are not
 538         existing on the node, the entire operation will abort.
 539       </para>
 540
 541       <para>
 542         If the <option>--from</option> option is given, the list of
 543         tags will be extended with the contents of that file (each
 544         line becomes a tag). In this case, there is not need to pass
 545         tags on the command line (if you do, both sources will be
 546         used). A file name of - will be interpreted as stdin.
 547       </para>
 548     </refsect2>
 549
 550     <refsect2>
 551       <title>VOLUMES</title>
 552
 553       <cmdsynopsis>
 554         <command>volumes</command>
 555         <arg>--no-headers</arg>
 556         <arg>--human-readable</arg>
 557         <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
 558         <arg>--output=<replaceable>FIELDS</replaceable></arg>
 559         <sbr>
 560         <arg rep="repeat"><replaceable>node</replaceable></arg>
 561       </cmdsynopsis>
 562
 563       <para>
 564         Lists all logical volumes and their physical disks from the node(s)
 565         provided.
 566       </para>
 567
 568       <para>
 569         The <option>--no-headers</option> option will skip the initial
 570         header line. The <option>--separator</option> option takes an
 571         argument which denotes what will be used between the output
 572         fields. Both these options are to help scripting.
 573       </para>
 574
 575       <para>
 576         The units used to display the numeric values in the output
 577         varies, depending on the options given. By default, the values
 578         will be formatted in the most appropriate unit. If the
 579         <option>--separator</option> option is given, then the values
 580         are shown in mebibytes to allow parsing by scripts. In both
 581         cases, the <option>--units</option> option can be used to
 582         enforce a given output unit.
 583       </para>
 584
 585       <para>
 586         The <option>-o</option> option takes a comma-separated list of
 587         output fields. The available fields and their meaning are:
 588         <variablelist>
 589           <varlistentry>
 590             <term>node</term>
 591             <listitem>
 592               <simpara>the node name on which the volume exists</simpara>
 593             </listitem>
 594           </varlistentry>
 595           <varlistentry>
 596             <term>phys</term>
 597             <listitem>
 598               <simpara>the physical drive (on which the LVM physical
 599               volume lives)</simpara>
 600             </listitem>
 601           </varlistentry>
 602           <varlistentry>
 603             <term>vg</term>
 604             <listitem>
 605               <simpara>the volume group name</simpara>
 606             </listitem>
 607           </varlistentry>
 608           <varlistentry>
 609             <term>name</term>
 610             <listitem>
 611               <simpara>the logical volume name</simpara>
 612             </listitem>
 613           </varlistentry>
 614           <varlistentry>
 615             <term>size</term>
 616             <listitem>
 617               <simpara>the logical volume size</simpara>
 618             </listitem>
 619           </varlistentry>
 620           <varlistentry>
 621             <term>instance</term>
 622             <listitem>
 623               <simpara>The name of the instance to which this volume
 624               belongs, or (in case it's an orphan volume) the
 625               character <quote>-</quote></simpara>
 626             </listitem>
 627           </varlistentry>
 628         </variablelist>
 629       </para>
 630
 631       <para>
 632         Example:
 633         <screen>
 634 # gnt-node volumes node5.example.com
 635 Node              PhysDev   VG    Name                                 Size Instance
 636 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11000.meta 128  instance1.example.com
 637 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  instance1.example.com
 638         </screen>
 639       </para>
 640     </refsect2>
 641
 642   </refsect1>
 643
 644   &footer;
 645
 646 </refentry>
 647
 648 <!-- Keep this comment at the end of the file
 649 Local variables:
 650 mode: sgml
 651 sgml-omittag:t
 652 sgml-shorttag:t
 653 sgml-minimize-attributes:nil
 654 sgml-always-quote-attributes:t
 655 sgml-indent-step:2
 656 sgml-indent-data:t
 657 sgml-parent-document:nil
 658 sgml-default-dtd-file:nil
 659 sgml-exposed-tags:nil
 660 sgml-local-catalogs:nil
 661 sgml-local-ecat-files:nil
 662 End:
 663 -->