code.grnet.gr Git - ganeti-local/blob - man/gnt-cluster.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>December 12, 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-cluster</refentrytitle>">
  10   <!ENTITY dhpackage   "gnt-cluster">
  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       <holder>Google Inc.</holder>
  24     </copyright>
  25     &dhdate;
  26   </refentryinfo>
  27   <refmeta>
  28     &dhucpackage;
  29
  30     &dhsection;
  31     <refmiscinfo>ganeti 1.2</refmiscinfo>
  32   </refmeta>
  33   <refnamediv>
  34     <refname>&dhpackage;</refname>
  35
  36     <refpurpose>ganeti administration, cluster-wide</refpurpose>
  37   </refnamediv>
  38   <refsynopsisdiv>
  39     <cmdsynopsis>
  40       <command>&dhpackage; </command>
  41
  42       <arg choice="req">command</arg>
  43       <arg>arguments...</arg>
  44     </cmdsynopsis>
  45   </refsynopsisdiv>
  46   <refsect1>
  47     <title>DESCRIPTION</title>
  48
  49     <para>
  50       The <command>&dhpackage;</command> is used for cluster-wide
  51       administration in the ganeti system.
  52     </para>
  53
  54   </refsect1>
  55   <refsect1>
  56     <title>COMMANDS</title>
  57
  58     <refsect2>
  59       <title>ADD-TAGS</title>
  60
  61       <cmdsynopsis>
  62         <command>add-tags</command>
  63         <arg choice="opt">--from <replaceable>file</replaceable></arg>
  64         <arg choice="req"
  65         rep="repeat"><replaceable>tag</replaceable></arg>
  66       </cmdsynopsis>
  67
  68       <para>
  69         Add tags to the cluster. If any of the tags contains invalid
  70         characters, the entire operation will abort.
  71       </para>
  72
  73       <para>
  74         If the <option>--from</option> option is given, the list of
  75         tags will be extended with the contents of that file (each
  76         line becomes a tag). In this case, there is not need to pass
  77         tags on the command line (if you do, both sources will be
  78         used). A file name of - will be interpreted as stdin.
  79       </para>
  80     </refsect2>
  81
  82     <refsect2>
  83       <title>COMMAND</title>
  84
  85       <cmdsynopsis>
  86         <command>command</command>
  87         <arg>-n <replaceable>node</replaceable></arg>
  88         <arg choice="req"><replaceable>command</replaceable></arg>
  89       </cmdsynopsis>
  90
  91       <para>
  92         Executes a command on all nodes. If the option
  93         <option>-n</option> is not given, the command will be executed
  94         on all nodes, otherwise it will be executed only on the
  95         node(s) specified. Use the option multiple times for running
  96         it on multiple nodes, like:
  97
  98         <screen>
  99           # gnt-cluster command -n node1.example.com -n node2.example.com date
 100         </screen>
 101
 102       </para>
 103
 104       <para>
 105         The command is executed serially on the selected nodes. If the
 106         master node is present in the list, the command will be
 107         executed last on the master. Regarding the other nodes, the
 108         execution order is somewhat alphabetic (it's smarter so that
 109         node2.example.com will be earlier than node10.example.com but
 110         after node1.example.com).
 111       </para>
 112
 113       <para>
 114         So given the node names node1, node2, node3, node10, node11,
 115         with node3 being the master, the order will be: node1, node2,
 116         node10, node11, node3.
 117       </para>
 118
 119       <para>
 120         The command is constructed by concatenating all other command
 121         line arguments. For example, to list the contents of the
 122         <filename class="directory">/etc</filename> directory on all
 123         nodes, run:
 124
 125         <screen>
 126           # gnt-cluster command ls -l /etc
 127         </screen>
 128
 129         and the command which will be executed will be
 130         <computeroutput>"ls -l /etc"</computeroutput>
 131       </para>
 132     </refsect2>
 133
 134     <refsect2>
 135       <title>COPYFILE</title>
 136
 137       <cmdsynopsis>
 138         <command>copyfile</command>
 139         <arg>-n <replaceable>node</replaceable></arg>
 140         <arg choice="req"><replaceable>file</replaceable></arg>
 141       </cmdsynopsis>
 142
 143       <para>
 144         Copies a file to all or to some nodes. The argument specifies
 145         the source file (on the current system), the
 146         <option>-n</option> argument specifies the target node, or
 147         nodes if the option is given multiple times. If
 148         <option>-n</option> is not given at all, the file will be
 149         copied to all nodes.
 150
 151         Example:
 152         <screen>
 153           # gnt-cluster -n node1.example.com -n node2.example.com copyfile /tmp/test
 154         </screen>
 155
 156         This will copy the file <filename>/tmp/test</filename> from
 157         the current node to the two named nodes.
 158       </para>
 159     </refsect2>
 160
 161     <refsect2>
 162       <title>DESTROY</title>
 163
 164       <cmdsynopsis>
 165         <command>destroy</command>
 166         <arg choice="req">--yes-do-it</arg>
 167       </cmdsynopsis>
 168
 169       <para>
 170         Remove all configuration files related to the cluster, so that
 171         a <command>gnt-cluster init</command> can be done again
 172         afterwards.
 173       </para>
 174
 175       <para>
 176         Since this is a dangerous command, you are required to pass
 177         the argument <replaceable>--yes-do-it.</replaceable>
 178       </para>
 179     </refsect2>
 180
 181     <refsect2>
 182       <title>GETMASTER</title>
 183
 184       <cmdsynopsis>
 185         <command>getmaster</command>
 186       </cmdsynopsis>
 187
 188       <para>
 189         Displays the current master node.
 190       </para>
 191     </refsect2>
 192
 193     <refsect2>
 194       <title>INFO</title>
 195
 196       <cmdsynopsis>
 197         <command>info</command>
 198       </cmdsynopsis>
 199
 200       <para>
 201         Shows runtime cluster information: cluster name, architecture
 202         (32 or 64 bit), master node, node list and instance list.
 203       </para>
 204     </refsect2>
 205
 206     <refsect2>
 207       <title>INIT</title>
 208
 209       <cmdsynopsis>
 210         <command>init</command>
 211         <arg>-s <replaceable>secondary_ip</replaceable></arg>
 212         <arg>-b <replaceable>bridge</replaceable></arg>
 213         <arg>-t <replaceable>hypervisor-type</replaceable></arg>
 214         <arg>-g <replaceable>vg-name</replaceable></arg>
 215         <arg>--master-netdev <replaceable>vg-name</replaceable></arg>
 216         <arg>-m <replaceable>mac-prefix</replaceable></arg>
 217         <arg choice="req"><replaceable>clustername</replaceable></arg>
 218       </cmdsynopsis>
 219
 220       <para>
 221         This commands is only run once initially on the first node of
 222         the cluster. It will initialize the cluster configuration and
 223         setup ssh-keys and more.
 224       </para>
 225
 226       <para>
 227         Note that the <replaceable>clustername</replaceable> is not
 228         any random name. It has to be resolvable to an IP address
 229         using DNS, and it is best if you give the fully-qualified
 230         domain name. This hostname must resolve to an IP address
 231         reserved exclusively for this purpose.
 232       </para>
 233
 234       <para>
 235         The cluster can run in two modes: single-home or
 236         dual-homed. In the first case, all traffic (both public
 237         traffic, inter-node traffic and data replication traffic) goes
 238         over the same interface. In the dual-homed case, the data
 239         replication traffic goes over the second network. The
 240         <option>-s</option> option here marks the cluster as
 241         dual-homed and its parameter represents this node's address on
 242         the second network. If you initialise the cluster with
 243         <option>-s</option>, all nodes added must have a secondary IP
 244         as well.
 245       </para>
 246
 247       <para>
 248         Note that for Ganeti it doesn't matter if the secondary
 249         network is actually a separate physical network, or is done
 250         using tunneling, etc. For performance reasons, it's
 251         recommended to use a separate network, of course.
 252       </para>
 253
 254       <para>
 255         The <option>-b</option> option specifies the default bridge
 256         for instances.
 257       </para>
 258
 259       <para>
 260         The <option>-t</option> allows to set the hypervisor type of
 261         the cluster. Available hypervisor types are: xen-3.0, fake and
 262         xen-hvm3.1. The default is the xen-3.0 hypervisor.
 263         Note that if you init the cluster with hypervisor-type
 264         xen-hvm3.1 you also need to provide the cluster VNC password
 265         file <filename>/etc/ganeti/vnc-cluster-password</filename> and
 266         the HVM boot ISO image
 267         <filename>/srv/ganeti/iso/hvm-install.iso</filename> because
 268         instances created by the experimental HVM support require them.
 269       </para>
 270
 271       <para>
 272         The <option>-g</option> option will let you specify a volume group
 273         different than xenvg for ganeti to use when creating instance disks.
 274         This volume group must have the same name on all nodes.
 275       </para>
 276
 277       <para>
 278         The <option>--master-netdev</option> option is useful for specifying a
 279         different interface on which the master will activate its IP address.
 280         It's important that all nodes have this interface because you'll need
 281         it for a master failover.
 282       </para>
 283
 284       <para>
 285         The <option>-m</option> option will let you specify a three byte prefix
 286         under which the virtual MAC addresses of your instances will be
 287         generated. The prefix must be specified in the format XX:XX:XX and the
 288         default is aa:00:00.
 289       </para>
 290
 291     </refsect2>
 292
 293     <refsect2>
 294       <title>LIST-TAGS</title>
 295
 296       <cmdsynopsis>
 297         <command>list-tags</command>
 298       </cmdsynopsis>
 299
 300       <para>List the tags of the cluster.</para>
 301     </refsect2>
 302
 303     <refsect2>
 304       <title>MASTERFAILOVER</title>
 305
 306       <cmdsynopsis>
 307         <command>masterfailover</command>
 308       </cmdsynopsis>
 309
 310       <para>
 311         Failover the master role to the current node.
 312       </para>
 313     </refsect2>
 314
 315     <refsect2>
 316       <title>REMOVE-TAGS</title>
 317
 318       <cmdsynopsis>
 319         <command>remove-tags</command>
 320         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 321         <arg choice="req"
 322         rep="repeat"><replaceable>tag</replaceable></arg>
 323       </cmdsynopsis>
 324
 325       <para>
 326         Remove tags from the cluster. If any of the tags are not
 327         existing on the cluster, the entire operation will abort.
 328       </para>
 329
 330       <para>
 331         If the <option>--from</option> option is given, the list of
 332         tags will be extended with the contents of that file (each
 333         line becomes a tag). In this case, there is not need to pass
 334         tags on the command line (if you do, both sources will be
 335         used). A file name of - will be interpreted as stdin.
 336       </para>
 337     </refsect2>
 338
 339     <refsect2>
 340       <title>RENAME</title>
 341
 342       <cmdsynopsis>
 343         <command>rename</command>
 344         <arg>-f</arg>
 345         <arg choice="req"><replaceable>name</replaceable></arg>
 346       </cmdsynopsis>
 347
 348       <para>
 349         Renames the cluster and in the process updates the master IP
 350         address to the one the new name resolves to. At least one of
 351         either the name or the IP address must be different, otherwise
 352         the operation will be aborted.
 353       </para>
 354
 355       <para>
 356         Note that since this command can be dangerous (especially when
 357         run over SSH), the command will require confirmation unless
 358         run with the <option>-f</option> option.
 359       </para>
 360     </refsect2>
 361
 362     <refsect2>
 363       <title>SEARCH-TAGS</title>
 364
 365       <cmdsynopsis>
 366         <command>search-tags</command>
 367         <arg choice="req"><replaceable>pattern</replaceable></arg>
 368       </cmdsynopsis>
 369
 370       <para>
 371         Searches the tags on all objects in the cluster (the cluster
 372         itself, the nodes and the instances) for a given pattern. The
 373         pattern is interpreted as a regular expression and a search
 374         will be done on it (i.e. the given pattern is not anchored to
 375         the beggining of the string; if you want that, prefix the
 376         pattern with <literal>^</literal>).
 377       </para>
 378
 379       <para>
 380         If no tags are matching the pattern, the exit code of the
 381         command will be one. If there is at least one match, the exit
 382         code will be zero. Each match is listed on one line, the
 383         object and the tag separated by a space. The cluster will be
 384         listed as <filename>/cluster</filename>, a node will be listed
 385         as
 386         <filename>/nodes/<replaceable>name</replaceable></filename>,
 387         and an instance as
 388         <filename>/instances/<replaceable>name</replaceable></filename>.
 389         Example:
 390       </para>
 391 <screen>
 392 # gnt-cluster search time
 393 /cluster ctime:2007-09-01
 394 /nodes/node1.example.com mtime:2007-10-04
 395 </screen>
 396     </refsect2>
 397
 398     <refsect2>
 399       <title>VERIFY</title>
 400
 401       <cmdsynopsis>
 402         <command>verify</command>
 403         <arg choice="opt">--no-nplus1-mem</arg>
 404       </cmdsynopsis>
 405
 406       <para>
 407         Verify correctness of cluster configuration. This is safe with
 408         respect to running instances, and incurs no downtime of the
 409         instances.
 410       </para>
 411
 412       <para>
 413         If the <option>--no-nplus1-mem</option> option is given, ganeti won't
 414         check whether if it loses a node it can restart all the instances on
 415         their secondaries (and report an error otherwise).
 416       </para>
 417     </refsect2>
 418
 419     <refsect2>
 420       <title>VERIFY-DISKS</title>
 421
 422       <cmdsynopsis>
 423         <command>verify-disks</command>
 424       </cmdsynopsis>
 425
 426       <para>
 427         The command checks which instances have degraded DRBD disks
 428         and activates the disks of those instances.
 429       </para>
 430
 431       <para>
 432         This command is run from the <command>ganeti-watcher</command>
 433         tool, which also has a different, complementary algorithm for
 434         doing this check. Together, these two should ensure that DRBD
 435         disks are kept consistent.
 436       </para>
 437     </refsect2>
 438
 439     <refsect2>
 440       <title>VERSION</title>
 441
 442       <cmdsynopsis>
 443         <command>version</command>
 444       </cmdsynopsis>
 445
 446       <para>
 447         Show the cluster version.
 448       </para>
 449     </refsect2>
 450
 451   </refsect1>
 452
 453   &footer;
 454
 455 </refentry>
 456
 457 <!-- Keep this comment at the end of the file
 458 Local variables:
 459 mode: sgml
 460 sgml-omittag:t
 461 sgml-shorttag:t
 462 sgml-minimize-attributes:nil
 463 sgml-always-quote-attributes:t
 464 sgml-indent-step:2
 465 sgml-indent-data:t
 466 sgml-parent-document:nil
 467 sgml-default-dtd-file:nil
 468 sgml-exposed-tags:nil
 469 sgml-local-catalogs:nil
 470 sgml-local-ecat-files:nil
 471 End:
 472 -->