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>June 20, 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-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       <holder>Google Inc.</holder>
  25     </copyright>
  26     &dhdate;
  27   </refentryinfo>
  28   <refmeta>
  29     &dhucpackage;
  30
  31     &dhsection;
  32     <refmiscinfo>ganeti 1.2</refmiscinfo>
  33   </refmeta>
  34   <refnamediv>
  35     <refname>&dhpackage;</refname>
  36
  37     <refpurpose>node administration</refpurpose>
  38   </refnamediv>
  39   <refsynopsisdiv>
  40     <cmdsynopsis>
  41       <command>&dhpackage; </command>
  42
  43       <arg choice="req">command</arg>
  44       <arg>arguments...</arg>
  45     </cmdsynopsis>
  46   </refsynopsisdiv>
  47   <refsect1>
  48     <title>DESCRIPTION</title>
  49
  50     <para>
  51       The <command>&dhpackage;</command> is used for managing the
  52       (physical) nodes in the ganeti system.
  53     </para>
  54
  55   </refsect1>
  56   <refsect1>
  57     <title>COMMANDS</title>
  58
  59     <refsect2>
  60       <title>ADD</title>
  61
  62       <cmdsynopsis>
  63         <command>add</command>
  64         <arg>--readd</arg>
  65         <arg>-s <replaceable>secondary_ip</replaceable></arg>
  66         <arg choice="req"><replaceable>nodename</replaceable></arg>
  67       </cmdsynopsis>
  68
  69       <para>
  70         Adds the given node to the cluster.
  71       </para>
  72
  73       <para>
  74         This command is used to join a new node to the cluster. You
  75         will have to provide the password for root of the node to be
  76         able to add the node in the cluster. The command needs to be
  77         run on the ganeti master.
  78       </para>
  79
  80       <para>
  81         Note that the command is potentially destructive, as it will
  82         forcibly join the specified host the cluster, not paying
  83         attention to its current status (it could be already in a
  84         cluster, etc.)
  85       </para>
  86
  87       <para>
  88         The <option>-s</option> is used in dual-home clusters and
  89         specifies the new node's IP in the secondary network. See the
  90         discussion in <citerefentry>
  91         <refentrytitle>gnt-cluster</refentrytitle>
  92         <manvolnum>8</manvolnum> </citerefentry> for more
  93         informations.
  94       </para>
  95
  96       <para>
  97         In case you're readding a node after hardware failure, you
  98         can use the <option>--readd</option> parameter.
  99       </para>
 100
 101       <para>
 102         Example:
 103         <screen>
 104 # gnt-node add node5.example.com
 105 # gnt-node add -s 192.168.44.5 node5.example.com
 106         </screen>
 107       </para>
 108     </refsect2>
 109
 110     <refsect2>
 111       <title>ADD-TAGS</title>
 112
 113       <cmdsynopsis>
 114         <command>add-tags</command>
 115         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 116         <arg choice="req"><replaceable>nodename</replaceable></arg>
 117         <arg choice="req"
 118         rep="repeat"><replaceable>tag</replaceable></arg>
 119       </cmdsynopsis>
 120
 121       <para>
 122         Add tags to the given node. If any of the tags contains
 123         invalid characters, the entire operation will abort.
 124       </para>
 125
 126       <para>
 127         If the <option>--from</option> option is given, the list of
 128         tags will be extended with the contents of that file (each
 129         line becomes a tag). In this case, there is not need to pass
 130         tags on the command line (if you do, both sources will be
 131         used). A file name of - will be interpreted as stdin.
 132       </para>
 133     </refsect2>
 134
 135     <refsect2>
 136       <title>EVACUATE</title>
 137
 138       <cmdsynopsis>
 139         <command>evacuate</command>
 140         <arg>-f</arg>
 141         <arg choice="req"><replaceable>source_node</replaceable></arg>
 142         <arg choice="req"><replaceable>destination_node</replaceable></arg>
 143       </cmdsynopsis>
 144
 145       <para>
 146         This command will change the secondary node from the source
 147         node to the destination node for all instances having the
 148         source node as secondary. It works only for instances having
 149         a drbd disk template.
 150       </para>
 151
 152       <para>
 153         Example:
 154         <screen>
 155           # gnt-node evacuate node1.example.com node2.example.com
 156         </screen>
 157       </para>
 158     </refsect2>
 159
 160     <refsect2>
 161       <title>FAILOVER</title>
 162
 163       <cmdsynopsis>
 164         <command>failover</command>
 165         <arg>-f</arg>
 166         <arg>--ignore-consistency</arg>
 167         <arg choice="req"><replaceable>node</replaceable></arg>
 168       </cmdsynopsis>
 169
 170       <para>
 171         This command will fail over all instances having the given
 172         node as primary to their secondary nodes. This works only for
 173         instances having a drbd disk template.
 174       </para>
 175
 176       <para>
 177         Normally the failover will check the consistency of the disks
 178         before failing over the instance. If you are trying to migrate
 179         instances off a dead node, this will fail. Use the
 180         <option>--ignore-consistency</option> option for this purpose.
 181       </para>
 182
 183       <para>
 184         Example:
 185         <screen>
 186           # gnt-node failover node1.example.com
 187         </screen>
 188       </para>
 189     </refsect2>
 190
 191     <refsect2>
 192       <title>INFO</title>
 193
 194       <cmdsynopsis>
 195         <command>info</command>
 196         <arg rep="repeat"><replaceable>node</replaceable></arg>
 197       </cmdsynopsis>
 198
 199       <para>
 200         Show detailed information about the nodes in the cluster. If you
 201         don't give any arguments, all nodes will be shows, otherwise the
 202         output will be restricted to the given names.
 203       </para>
 204     </refsect2>
 205
 206     <refsect2>
 207       <title>LIST</title>
 208
 209       <cmdsynopsis>
 210         <command>list</command>
 211         <arg>--no-headers</arg>
 212         <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
 213         <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>
 214       </cmdsynopsis>
 215
 216       <para>
 217         Lists the nodes in the cluster. If you give the
 218         <option>--ip-info</option> option, the output contains just
 219         the node name, primary ip and secondary ip. In case the
 220         secondary ip is the same as the primary one, it will be listed
 221         as <emphasis>"-"</emphasis>.
 222       </para>
 223
 224       <para>
 225         The <option>--no-headers</option> option will skip the initial
 226         header line. The <option>--separator</option> option takes an
 227         argument which denotes what will be used between the output
 228         fields. Both these options are to help scripting.
 229       </para>
 230
 231       <para>
 232         The <option>-o</option> option takes a comma-separated list of
 233         output fields. The available fields and their meaning are:
 234         <variablelist>
 235           <varlistentry>
 236             <term>name</term>
 237             <listitem>
 238               <simpara>the node name</simpara>
 239             </listitem>
 240           </varlistentry>
 241           <varlistentry>
 242             <term>pinst_cnt</term>
 243             <listitem>
 244               <simpara>the number of instances having this node as
 245               primary</simpara>
 246             </listitem>
 247           </varlistentry>
 248           <varlistentry>
 249             <term>pinst_list</term>
 250             <listitem>
 251               <simpara>the list of instances having this node as
 252               primary, comma separated</simpara>
 253             </listitem>
 254           </varlistentry>
 255           <varlistentry>
 256             <term>sinst_cnt</term>
 257             <listitem>
 258               <simpara>the number of instances having this node as a
 259               secondary node</simpara>
 260             </listitem>
 261           </varlistentry>
 262           <varlistentry>
 263             <term>sinst_list</term>
 264             <listitem>
 265               <simpara>the list of instances having this node as a
 266               secondary node, comma separated</simpara>
 267             </listitem>
 268           </varlistentry>
 269           <varlistentry>
 270             <term>pip</term>
 271             <listitem>
 272               <simpara>the primary ip of this node (used for cluster
 273               communication)</simpara>
 274             </listitem>
 275           </varlistentry>
 276           <varlistentry>
 277             <term>sip</term>
 278             <listitem>
 279               <simpara>
 280                 the secondary ip of this node (used for data
 281                 replication in dual-ip clusters, see <citerefentry>
 282                 <refentrytitle>gnt-cluster</refentrytitle>
 283                 <manvolnum>8</manvolnum>
 284                 </citerefentry>
 285               </simpara>
 286             </listitem>
 287           </varlistentry>
 288           <varlistentry>
 289             <term>dtotal</term>
 290             <listitem>
 291               <simpara>total disk space in the volume group used for
 292               instance disk allocations</simpara>
 293             </listitem>
 294           </varlistentry>
 295           <varlistentry>
 296             <term>dfree</term>
 297             <listitem>
 298               <simpara>available disk space in the volume group</simpara>
 299             </listitem>
 300           </varlistentry>
 301           <varlistentry>
 302             <term>mtotal</term>
 303             <listitem>
 304               <simpara>total memory on the physical node</simpara>
 305             </listitem>
 306           </varlistentry>
 307           <varlistentry>
 308             <term>mnode</term>
 309             <listitem>
 310               <simpara>the memory used by the node itself</simpara>
 311             </listitem>
 312           </varlistentry>
 313           <varlistentry>
 314             <term>mfree</term>
 315             <listitem>
 316               <simpara>memory available for instance
 317               allocations</simpara>
 318             </listitem>
 319           </varlistentry>
 320           <varlistentry>
 321             <term>bootid</term>
 322             <listitem>
 323               <simpara>the node bootid value; this is a linux specific
 324               feature that assigns a new UUID to the node at each boot
 325               and can be use to detect node reboots (by tracking
 326               changes in this value)</simpara>
 327             </listitem>
 328           </varlistentry>
 329           <varlistentry>
 330             <term>tags</term>
 331             <listitem>
 332               <simpara>comma-separated list of the node's
 333               tags</simpara>
 334             </listitem>
 335           </varlistentry>
 336           <varlistentry>
 337             <term>serial_no</term>
 338             <listitem>
 339               <simpara>the so called 'serial number' of the instance;
 340               this is a numeric field that is incremented each time
 341               the instance is modified, and it can be used to detect
 342               modifications</simpara>
 343             </listitem>
 344           </varlistentry>
 345         </variablelist>
 346       </para>
 347
 348       <para>
 349         If the value of the option starts with the character
 350         <constant>+</constant>, the new fields will be added to the
 351         default list. This allows to quickly see the default list plus
 352         a few other fields, instead of retyping the entire list of
 353         fields.
 354       </para>
 355
 356       <para>
 357         Note that some of this fields are known from the configuration
 358         of the cluster (<simplelist type="inline">
 359         <member>name</member> <member>pinst</member>
 360         <member>sinst</member> <member>pip</member>
 361         <member>sip</member> </simplelist> and thus the master does
 362         not need to contact the node for this data (making the listing
 363         fast if only fields from this set are selected), whereas the
 364         other fields are "live" fields and we need to make a query to
 365         the cluster nodes.
 366       </para>
 367
 368       <para>
 369         Depending on the virtualization type and implementation
 370         details, the mtotal, mnode and mfree may have slighly varying
 371         meanings. For example, some solutions share the node memory
 372         with the pool of memory used for instances
 373         (<acronym>UML</acronym>), whereas others have separate memory
 374         for the node and for the instances (Xen).
 375       </para>
 376     </refsect2>
 377
 378     <refsect2>
 379       <title>LIST-TAGS</title>
 380
 381       <cmdsynopsis>
 382         <command>list-tags</command>
 383         <arg choice="req"><replaceable>nodename</replaceable></arg>
 384       </cmdsynopsis>
 385
 386       <para>List the tags of the given node.</para>
 387     </refsect2>
 388
 389     <refsect2>
 390       <title>REMOVE</title>
 391
 392       <cmdsynopsis>
 393         <command>remove</command>
 394         <arg choice="req"><replaceable>nodename</replaceable></arg>
 395       </cmdsynopsis>
 396
 397       <para>
 398         Removes a node from the cluster. Instances must be removed or
 399         migrated to another cluster before.
 400       </para>
 401
 402       <para>
 403         Example:
 404         <screen>
 405 # gnt-node remove node5.example.com
 406         </screen>
 407       </para>
 408     </refsect2>
 409
 410     <refsect2>
 411       <title>REMOVE-TAGS</title>
 412       <cmdsynopsis>
 413         <command>remove-tags</command>
 414         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 415         <arg choice="req"><replaceable>nodename</replaceable></arg>
 416         <arg choice="req"
 417         rep="repeat"><replaceable>tag</replaceable></arg>
 418       </cmdsynopsis>
 419
 420       <para>
 421         Remove tags from the given node. If any of the tags are not
 422         existing on the node, the entire operation will abort.
 423       </para>
 424
 425       <para>
 426         If the <option>--from</option> option is given, the list of
 427         tags will be extended with the contents of that file (each
 428         line becomes a tag). In this case, there is not need to pass
 429         tags on the command line (if you do, both sources will be
 430         used). A file name of - will be interpreted as stdin.
 431       </para>
 432     </refsect2>
 433
 434     <refsect2>
 435       <title>VOLUMES</title>
 436
 437       <cmdsynopsis>
 438         <command>volumes</command>
 439         <arg>--no-headers</arg>
 440         <arg>--human-readable</arg>
 441         <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
 442         <arg>--output=<replaceable>FIELDS</replaceable></arg>
 443         <sbr>
 444         <arg rep="repeat"><replaceable>node</replaceable></arg>
 445       </cmdsynopsis>
 446
 447       <para>
 448         Lists all logical volumes and their physical disks from the node(s)
 449         provided.
 450       </para>
 451
 452       <para>
 453         The <option>--no-headers</option> option will skip the initial
 454         header line. The <option>--separator</option> option takes an
 455         argument which denotes what will be used between the output
 456         fields. Both these options are to help scripting.
 457       </para>
 458
 459       <para>
 460         The <option>-o</option> option takes a comma-separated list of
 461         output fields. The available fields and their meaning are:
 462         <variablelist>
 463           <varlistentry>
 464             <term>node</term>
 465             <listitem>
 466               <simpara>the node name on which the volume exists</simpara>
 467             </listitem>
 468           </varlistentry>
 469           <varlistentry>
 470             <term>phys</term>
 471             <listitem>
 472               <simpara>the physical drive (on which the LVM physical
 473               volume lives)</simpara>
 474             </listitem>
 475           </varlistentry>
 476           <varlistentry>
 477             <term>vg</term>
 478             <listitem>
 479               <simpara>the volume group name</simpara>
 480             </listitem>
 481           </varlistentry>
 482           <varlistentry>
 483             <term>name</term>
 484             <listitem>
 485               <simpara>the logical volume name</simpara>
 486             </listitem>
 487           </varlistentry>
 488           <varlistentry>
 489             <term>size</term>
 490             <listitem>
 491               <simpara>the logical volume size</simpara>
 492             </listitem>
 493           </varlistentry>
 494           <varlistentry>
 495             <term>instance</term>
 496             <listitem>
 497               <simpara>The name of the instance to which this volume
 498               belongs, or (in case it's an orphan volume) the
 499               character <quote>-</quote></simpara>
 500             </listitem>
 501           </varlistentry>
 502         </variablelist>
 503       </para>
 504
 505       <para>
 506         Example:
 507         <screen>
 508 # gnt-node volumes node5.example.com
 509 Node              PhysDev   VG    Name                                 Size Instance
 510 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11000.meta 128  instance1.example.com
 511 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  instance1.example.com
 512         </screen>
 513       </para>
 514     </refsect2>
 515
 516   </refsect1>
 517
 518   &footer;
 519
 520 </refentry>
 521
 522 <!-- Keep this comment at the end of the file
 523 Local variables:
 524 mode: sgml
 525 sgml-omittag:t
 526 sgml-shorttag:t
 527 sgml-minimize-attributes:nil
 528 sgml-always-quote-attributes:t
 529 sgml-indent-step:2
 530 sgml-indent-data:t
 531 sgml-parent-document:nil
 532 sgml-default-dtd-file:nil
 533 sgml-exposed-tags:nil
 534 sgml-local-catalogs:nil
 535 sgml-local-ecat-files:nil
 536 End:
 537 -->