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         </variablelist>
 330       </para>
 331
 332       <para>
 333         If the value of the option starts with the character
 334         <constant>+</constant>, the new fields will be added to the
 335         default list. This allows to quickly see the default list plus
 336         a few other fields, instead of retyping the entire list of
 337         fields.
 338       </para>
 339
 340       <para>
 341         Note that some of this fields are known from the configuration
 342         of the cluster (<simplelist type="inline">
 343         <member>name</member> <member>pinst</member>
 344         <member>sinst</member> <member>pip</member>
 345         <member>sip</member> </simplelist> and thus the master does
 346         not need to contact the node for this data (making the listing
 347         fast if only fields from this set are selected), whereas the
 348         other fields are "live" fields and we need to make a query to
 349         the cluster nodes.
 350       </para>
 351
 352       <para>
 353         Depending on the virtualization type and implementation
 354         details, the mtotal, mnode and mfree may have slighly varying
 355         meanings. For example, some solutions share the node memory
 356         with the pool of memory used for instances
 357         (<acronym>UML</acronym>), whereas others have separate memory
 358         for the node and for the instances (Xen).
 359       </para>
 360     </refsect2>
 361
 362     <refsect2>
 363       <title>LIST-TAGS</title>
 364
 365       <cmdsynopsis>
 366         <command>list-tags</command>
 367         <arg choice="req"><replaceable>nodename</replaceable></arg>
 368       </cmdsynopsis>
 369
 370       <para>List the tags of the given node.</para>
 371     </refsect2>
 372
 373     <refsect2>
 374       <title>REMOVE</title>
 375
 376       <cmdsynopsis>
 377         <command>remove</command>
 378         <arg choice="req"><replaceable>nodename</replaceable></arg>
 379       </cmdsynopsis>
 380
 381       <para>
 382         Removes a node from the cluster. Instances must be removed or
 383         migrated to another cluster before.
 384       </para>
 385
 386       <para>
 387         Example:
 388         <screen>
 389 # gnt-node remove node5.example.com
 390         </screen>
 391       </para>
 392     </refsect2>
 393
 394     <refsect2>
 395       <title>REMOVE-TAGS</title>
 396       <cmdsynopsis>
 397         <command>remove-tags</command>
 398         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 399         <arg choice="req"><replaceable>nodename</replaceable></arg>
 400         <arg choice="req"
 401         rep="repeat"><replaceable>tag</replaceable></arg>
 402       </cmdsynopsis>
 403
 404       <para>
 405         Remove tags from the given node. If any of the tags are not
 406         existing on the node, the entire operation will abort.
 407       </para>
 408
 409       <para>
 410         If the <option>--from</option> option is given, the list of
 411         tags will be extended with the contents of that file (each
 412         line becomes a tag). In this case, there is not need to pass
 413         tags on the command line (if you do, both sources will be
 414         used). A file name of - will be interpreted as stdin.
 415       </para>
 416     </refsect2>
 417
 418     <refsect2>
 419       <title>VOLUMES</title>
 420
 421       <cmdsynopsis>
 422         <command>volumes</command>
 423         <arg>--no-headers</arg>
 424         <arg>--human-readable</arg>
 425         <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
 426         <arg>--output=<replaceable>FIELDS</replaceable></arg>
 427         <sbr>
 428         <arg rep="repeat"><replaceable>node</replaceable></arg>
 429       </cmdsynopsis>
 430
 431       <para>
 432         Lists all logical volumes and their physical disks from the node(s)
 433         provided.
 434       </para>
 435
 436       <para>
 437         The <option>--no-headers</option> option will skip the initial
 438         header line. The <option>--separator</option> option takes an
 439         argument which denotes what will be used between the output
 440         fields. Both these options are to help scripting.
 441       </para>
 442
 443       <para>
 444         The <option>-o</option> option takes a comma-separated list of
 445         output fields. The available fields and their meaning are:
 446         <variablelist>
 447           <varlistentry>
 448             <term>node</term>
 449             <listitem>
 450               <simpara>the node name on which the volume exists</simpara>
 451             </listitem>
 452           </varlistentry>
 453           <varlistentry>
 454             <term>phys</term>
 455             <listitem>
 456               <simpara>the physical drive (on which the LVM physical
 457               volume lives)</simpara>
 458             </listitem>
 459           </varlistentry>
 460           <varlistentry>
 461             <term>vg</term>
 462             <listitem>
 463               <simpara>the volume group name</simpara>
 464             </listitem>
 465           </varlistentry>
 466           <varlistentry>
 467             <term>name</term>
 468             <listitem>
 469               <simpara>the logical volume name</simpara>
 470             </listitem>
 471           </varlistentry>
 472           <varlistentry>
 473             <term>size</term>
 474             <listitem>
 475               <simpara>the logical volume size</simpara>
 476             </listitem>
 477           </varlistentry>
 478           <varlistentry>
 479             <term>instance</term>
 480             <listitem>
 481               <simpara>The name of the instance to which this volume
 482               belongs, or (in case it's an orphan volume) the
 483               character <quote>-</quote></simpara>
 484             </listitem>
 485           </varlistentry>
 486         </variablelist>
 487       </para>
 488
 489       <para>
 490         Example:
 491         <screen>
 492 # gnt-node volumes node5.example.com
 493 Node              PhysDev   VG    Name                                 Size Instance
 494 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11000.meta 128  instance1.example.com
 495 node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  instance1.example.com
 496         </screen>
 497       </para>
 498     </refsect2>
 499
 500   </refsect1>
 501
 502   &footer;
 503
 504 </refentry>
 505
 506 <!-- Keep this comment at the end of the file
 507 Local variables:
 508 mode: sgml
 509 sgml-omittag:t
 510 sgml-shorttag:t
 511 sgml-minimize-attributes:nil
 512 sgml-always-quote-attributes:t
 513 sgml-indent-step:2
 514 sgml-indent-data:t
 515 sgml-parent-document:nil
 516 sgml-default-dtd-file:nil
 517 sgml-exposed-tags:nil
 518 sgml-local-catalogs:nil
 519 sgml-local-ecat-files:nil
 520 End:
 521 -->