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