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>--no-lvm-storage</arg>
 218         <arg choice="req"><replaceable>clustername</replaceable></arg>
 219       </cmdsynopsis>
 220
 221       <para>
 222         This commands is only run once initially on the first node of
 223         the cluster. It will initialize the cluster configuration and
 224         setup ssh-keys and more.
 225       </para>
 226
 227       <para>
 228         Note that the <replaceable>clustername</replaceable> is not
 229         any random name. It has to be resolvable to an IP address
 230         using DNS, and it is best if you give the fully-qualified
 231         domain name. This hostname must resolve to an IP address
 232         reserved exclusively for this purpose.
 233       </para>
 234
 235       <para>
 236         The cluster can run in two modes: single-home or
 237         dual-homed. In the first case, all traffic (both public
 238         traffic, inter-node traffic and data replication traffic) goes
 239         over the same interface. In the dual-homed case, the data
 240         replication traffic goes over the second network. The
 241         <option>-s</option> option here marks the cluster as
 242         dual-homed and its parameter represents this node's address on
 243         the second network. If you initialise the cluster with
 244         <option>-s</option>, all nodes added must have a secondary IP
 245         as well.
 246       </para>
 247
 248       <para>
 249         Note that for Ganeti it doesn't matter if the secondary
 250         network is actually a separate physical network, or is done
 251         using tunneling, etc. For performance reasons, it's
 252         recommended to use a separate network, of course.
 253       </para>
 254
 255       <para>
 256         The <option>-b</option> option specifies the default bridge
 257         for instances.
 258       </para>
 259
 260       <para>
 261         The <option>-t</option> allows to set the hypervisor type of
 262         the cluster. Available hypervisor types are: xen-pvm, fake and
 263         xen-hvm. The default is the xen-pvm hypervisor.
 264         Note that if you init the cluster with hypervisor-type
 265         xen-hvm you also need to provide the cluster VNC password
 266         file <filename>/etc/ganeti/vnc-cluster-password</filename>
 267         because HVM instances require it for VNC console
 268         authentication.
 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. Once the
 275         cluster is initialized this can be altered by using the
 276         <command>modify</command> command. If you don't want to use lvm
 277         storage at all use the <option>--no-lvm-storage</option> option.
 278         Once the cluster is initialized you can change this setup with the
 279         <command>modify</command> command.
 280       </para>
 281
 282       <para>
 283         The <option>--master-netdev</option> option is useful for specifying a
 284         different interface on which the master will activate its IP address.
 285         It's important that all nodes have this interface because you'll need
 286         it for a master failover.
 287       </para>
 288
 289       <para>
 290         The <option>-m</option> option will let you specify a three byte prefix
 291         under which the virtual MAC addresses of your instances will be
 292         generated. The prefix must be specified in the format XX:XX:XX and the
 293         default is aa:00:00.
 294       </para>
 295
 296       <para>
 297         The <option>--no-lvm-storage</option> allows you to initialize the
 298         cluster without lvm support. This means that only instances using
 299         files as storage backend will be possible to create. Once the cluster
 300         is initialized you can change this setup with the
 301         <command>modify</command> command.
 302       </para>
 303     </refsect2>
 304
 305     <refsect2>
 306       <title>LIST-TAGS</title>
 307
 308       <cmdsynopsis>
 309         <command>list-tags</command>
 310       </cmdsynopsis>
 311
 312       <para>List the tags of the cluster.</para>
 313     </refsect2>
 314
 315     <refsect2>
 316       <title>MASTERFAILOVER</title>
 317
 318       <cmdsynopsis>
 319         <command>masterfailover</command>
 320       </cmdsynopsis>
 321
 322       <para>
 323         Failover the master role to the current node.
 324       </para>
 325     </refsect2>
 326
 327     <refsect2>
 328       <title>MODIFY</title>
 329
 330       <cmdsynopsis>
 331         <command>modify</command>
 332         <arg choice="opt">-g <replaceable>vg-name</replaceable></arg>
 333         <arg choice="opt">--no-lvm-storage</arg>
 334       </cmdsynopsis>
 335
 336         <para>
 337           Modify the options for the cluster.
 338         </para>
 339
 340         <para>
 341           The <option>-g</option> and <option>--no-lvm-stoarge</option> are
 342           described in the <command>init</command> command.
 343         </para>
 344     </refsect2>
 345
 346     <refsect2>
 347       <title>REMOVE-TAGS</title>
 348
 349       <cmdsynopsis>
 350         <command>remove-tags</command>
 351         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 352         <arg choice="req"
 353         rep="repeat"><replaceable>tag</replaceable></arg>
 354       </cmdsynopsis>
 355
 356       <para>
 357         Remove tags from the cluster. If any of the tags are not
 358         existing on the cluster, the entire operation will abort.
 359       </para>
 360
 361       <para>
 362         If the <option>--from</option> option is given, the list of
 363         tags will be extended with the contents of that file (each
 364         line becomes a tag). In this case, there is not need to pass
 365         tags on the command line (if you do, both sources will be
 366         used). A file name of - will be interpreted as stdin.
 367       </para>
 368     </refsect2>
 369
 370     <refsect2>
 371       <title>RENAME</title>
 372
 373       <cmdsynopsis>
 374         <command>rename</command>
 375         <arg>-f</arg>
 376         <arg choice="req"><replaceable>name</replaceable></arg>
 377       </cmdsynopsis>
 378
 379       <para>
 380         Renames the cluster and in the process updates the master IP
 381         address to the one the new name resolves to. At least one of
 382         either the name or the IP address must be different, otherwise
 383         the operation will be aborted.
 384       </para>
 385
 386       <para>
 387         Note that since this command can be dangerous (especially when
 388         run over SSH), the command will require confirmation unless
 389         run with the <option>-f</option> option.
 390       </para>
 391     </refsect2>
 392
 393     <refsect2>
 394       <title>SEARCH-TAGS</title>
 395
 396       <cmdsynopsis>
 397         <command>search-tags</command>
 398         <arg choice="req"><replaceable>pattern</replaceable></arg>
 399       </cmdsynopsis>
 400
 401       <para>
 402         Searches the tags on all objects in the cluster (the cluster
 403         itself, the nodes and the instances) for a given pattern. The
 404         pattern is interpreted as a regular expression and a search
 405         will be done on it (i.e. the given pattern is not anchored to
 406         the beggining of the string; if you want that, prefix the
 407         pattern with <literal>^</literal>).
 408       </para>
 409
 410       <para>
 411         If no tags are matching the pattern, the exit code of the
 412         command will be one. If there is at least one match, the exit
 413         code will be zero. Each match is listed on one line, the
 414         object and the tag separated by a space. The cluster will be
 415         listed as <filename>/cluster</filename>, a node will be listed
 416         as
 417         <filename>/nodes/<replaceable>name</replaceable></filename>,
 418         and an instance as
 419         <filename>/instances/<replaceable>name</replaceable></filename>.
 420         Example:
 421       </para>
 422 <screen>
 423 # gnt-cluster search time
 424 /cluster ctime:2007-09-01
 425 /nodes/node1.example.com mtime:2007-10-04
 426 </screen>
 427     </refsect2>
 428
 429     <refsect2>
 430       <title>VERIFY</title>
 431
 432       <cmdsynopsis>
 433         <command>verify</command>
 434         <arg choice="opt">--no-nplus1-mem</arg>
 435       </cmdsynopsis>
 436
 437       <para>
 438         Verify correctness of cluster configuration. This is safe with
 439         respect to running instances, and incurs no downtime of the
 440         instances.
 441       </para>
 442
 443       <para>
 444         If the <option>--no-nplus1-mem</option> option is given, ganeti won't
 445         check whether if it loses a node it can restart all the instances on
 446         their secondaries (and report an error otherwise).
 447       </para>
 448     </refsect2>
 449
 450     <refsect2>
 451       <title>VERIFY-DISKS</title>
 452
 453       <cmdsynopsis>
 454         <command>verify-disks</command>
 455       </cmdsynopsis>
 456
 457       <para>
 458         The command checks which instances have degraded DRBD disks
 459         and activates the disks of those instances.
 460       </para>
 461
 462       <para>
 463         This command is run from the <command>ganeti-watcher</command>
 464         tool, which also has a different, complementary algorithm for
 465         doing this check. Together, these two should ensure that DRBD
 466         disks are kept consistent.
 467       </para>
 468     </refsect2>
 469
 470     <refsect2>
 471       <title>VERSION</title>
 472
 473       <cmdsynopsis>
 474         <command>version</command>
 475       </cmdsynopsis>
 476
 477       <para>
 478         Show the cluster version.
 479       </para>
 480     </refsect2>
 481
 482   </refsect1>
 483
 484   &footer;
 485
 486 </refentry>
 487
 488 <!-- Keep this comment at the end of the file
 489 Local variables:
 490 mode: sgml
 491 sgml-omittag:t
 492 sgml-shorttag:t
 493 sgml-minimize-attributes:nil
 494 sgml-always-quote-attributes:t
 495 sgml-indent-step:2
 496 sgml-indent-data:t
 497 sgml-parent-document:nil
 498 sgml-default-dtd-file:nil
 499 sgml-exposed-tags:nil
 500 sgml-local-catalogs:nil
 501 sgml-local-ecat-files:nil
 502 End:
 503 -->