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>February 12, 2009</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       <year>2008</year>
  24       <year>2009</year>
  25       <holder>Google Inc.</holder>
  26     </copyright>
  27     &dhdate;
  28   </refentryinfo>
  29   <refmeta>
  30     &dhucpackage;
  31
  32     &dhsection;
  33     <refmiscinfo>ganeti 2.0</refmiscinfo>
  34   </refmeta>
  35   <refnamediv>
  36     <refname>&dhpackage;</refname>
  37
  38     <refpurpose>ganeti administration, cluster-wide</refpurpose>
  39   </refnamediv>
  40   <refsynopsisdiv>
  41     <cmdsynopsis>
  42       <command>&dhpackage; </command>
  43
  44       <arg choice="req">command</arg>
  45       <arg>arguments...</arg>
  46     </cmdsynopsis>
  47   </refsynopsisdiv>
  48   <refsect1>
  49     <title>DESCRIPTION</title>
  50
  51     <para>
  52       The <command>&dhpackage;</command> is used for cluster-wide
  53       administration in the ganeti system.
  54     </para>
  55
  56   </refsect1>
  57   <refsect1>
  58     <title>COMMANDS</title>
  59
  60     <refsect2>
  61       <title>ADD-TAGS</title>
  62
  63       <cmdsynopsis>
  64         <command>add-tags</command>
  65         <arg choice="opt">--from <replaceable>file</replaceable></arg>
  66         <arg choice="req"
  67         rep="repeat"><replaceable>tag</replaceable></arg>
  68       </cmdsynopsis>
  69
  70       <para>
  71         Add tags to the cluster. If any of the tags contains invalid
  72         characters, the entire operation will abort.
  73       </para>
  74
  75       <para>
  76         If the <option>--from</option> option is given, the list of
  77         tags will be extended with the contents of that file (each
  78         line becomes a tag). In this case, there is not need to pass
  79         tags on the command line (if you do, both sources will be
  80         used). A file name of - will be interpreted as stdin.
  81       </para>
  82     </refsect2>
  83
  84     <refsect2>
  85       <title>COMMAND</title>
  86
  87       <cmdsynopsis>
  88         <command>command</command>
  89         <arg>-n <replaceable>node</replaceable></arg>
  90         <arg choice="req"><replaceable>command</replaceable></arg>
  91       </cmdsynopsis>
  92
  93       <para>
  94         Executes a command on all nodes. If the option
  95         <option>-n</option> is not given, the command will be executed
  96         on all nodes, otherwise it will be executed only on the
  97         node(s) specified. Use the option multiple times for running
  98         it on multiple nodes, like:
  99
 100         <screen>
 101           # gnt-cluster command -n node1.example.com -n node2.example.com date
 102         </screen>
 103
 104       </para>
 105
 106       <para>
 107         The command is executed serially on the selected nodes. If the
 108         master node is present in the list, the command will be
 109         executed last on the master. Regarding the other nodes, the
 110         execution order is somewhat alphabetic, so that
 111         node2.example.com will be earlier than node10.example.com but
 112         after node1.example.com.
 113       </para>
 114
 115       <para>
 116         So given the node names node1, node2, node3, node10, node11,
 117         with node3 being the master, the order will be: node1, node2,
 118         node10, node11, node3.
 119       </para>
 120
 121       <para>
 122         The command is constructed by concatenating all other command
 123         line arguments. For example, to list the contents of the
 124         <filename class="directory">/etc</filename> directory on all
 125         nodes, run:
 126
 127         <screen>
 128           # gnt-cluster command ls -l /etc
 129         </screen>
 130
 131         and the command which will be executed will be
 132         <computeroutput>"ls -l /etc"</computeroutput>
 133       </para>
 134     </refsect2>
 135
 136     <refsect2>
 137       <title>COPYFILE</title>
 138
 139       <cmdsynopsis>
 140         <command>copyfile</command>
 141         <arg>-n <replaceable>node</replaceable></arg>
 142         <arg choice="req"><replaceable>file</replaceable></arg>
 143       </cmdsynopsis>
 144
 145       <para>
 146         Copies a file to all or to some nodes. The argument specifies
 147         the source file (on the current system), the
 148         <option>-n</option> argument specifies the target node, or
 149         nodes if the option is given multiple times. If
 150         <option>-n</option> is not given at all, the file will be
 151         copied to all nodes.
 152
 153         Example:
 154         <screen>
 155           # gnt-cluster -n node1.example.com -n node2.example.com copyfile /tmp/test
 156         </screen>
 157
 158         This will copy the file <filename>/tmp/test</filename> from
 159         the current node to the two named nodes.
 160       </para>
 161     </refsect2>
 162
 163     <refsect2>
 164       <title>DESTROY</title>
 165
 166       <cmdsynopsis>
 167         <command>destroy</command>
 168         <arg choice="req">--yes-do-it</arg>
 169       </cmdsynopsis>
 170
 171       <para>
 172         Remove all configuration files related to the cluster, so that
 173         a <command>gnt-cluster init</command> can be done again
 174         afterwards.
 175       </para>
 176
 177       <para>
 178         Since this is a dangerous command, you are required to pass
 179         the argument <replaceable>--yes-do-it.</replaceable>
 180       </para>
 181     </refsect2>
 182
 183     <refsect2>
 184       <title>GETMASTER</title>
 185
 186       <cmdsynopsis>
 187         <command>getmaster</command>
 188       </cmdsynopsis>
 189
 190       <para>
 191         Displays the current master node.
 192       </para>
 193     </refsect2>
 194
 195     <refsect2>
 196       <title>INFO</title>
 197
 198       <cmdsynopsis>
 199         <command>info</command>
 200       </cmdsynopsis>
 201
 202       <para>
 203         Shows runtime cluster information: cluster name, architecture
 204         (32 or 64 bit), master node, node list and instance list.
 205       </para>
 206     </refsect2>
 207
 208     <refsect2>
 209       <title>INIT</title>
 210
 211       <cmdsynopsis>
 212         <command>init</command>
 213         <sbr>
 214         <arg>-s <replaceable>secondary_ip</replaceable></arg>
 215         <sbr>
 216         <arg>-b <replaceable>bridge</replaceable></arg>
 217         <sbr>
 218         <arg>-g <replaceable>vg-name</replaceable></arg>
 219         <sbr>
 220         <arg>--master-netdev <replaceable>vg-name</replaceable></arg>
 221         <sbr>
 222         <arg>-m <replaceable>mac-prefix</replaceable></arg>
 223         <sbr>
 224         <arg>--no-lvm-storage</arg>
 225         <sbr>
 226         <arg>--file-storage-dir <replaceable>dir</replaceable></arg>
 227         <sbr>
 228         <arg>--enabled-hypervisors <replaceable>hypervisors</replaceable></arg>
 229         <sbr>
 230         <arg>-t <replaceable>hypervisor name</replaceable></arg>
 231         <sbr>
 232         <arg>--hypervisor-parameters <replaceable>hypervisor</replaceable>:<replaceable>hv-param</replaceable>=<replaceable>value</replaceable><arg rep="repeat" choice="opt">,<replaceable>hv-param</replaceable>=<replaceable>value</replaceable></arg></arg>
 233         <sbr>
 234         <arg>--backend-parameters <replaceable>be-param</replaceable>=<replaceable>value</replaceable><arg rep="repeat" choice="opt">,<replaceable>be-param</replaceable>=<replaceable>value</replaceable></arg></arg>
 235         <sbr>
 236         <arg choice="req"><replaceable>clustername</replaceable></arg>
 237       </cmdsynopsis>
 238
 239       <para>
 240         This commands is only run once initially on the first node of
 241         the cluster. It will initialize the cluster configuration and
 242         setup ssh-keys and more.
 243       </para>
 244
 245       <para>
 246         Note that the <replaceable>clustername</replaceable> is not
 247         any random name. It has to be resolvable to an IP address
 248         using DNS, and it is best if you give the fully-qualified
 249         domain name. This hostname must resolve to an IP address
 250         reserved exclusively for this purpose.
 251       </para>
 252
 253       <para>
 254         The cluster can run in two modes: single-home or
 255         dual-homed. In the first case, all traffic (both public
 256         traffic, inter-node traffic and data replication traffic) goes
 257         over the same interface. In the dual-homed case, the data
 258         replication traffic goes over the second network. The
 259         <option>-s</option> option here marks the cluster as
 260         dual-homed and its parameter represents this node's address on
 261         the second network. If you initialise the cluster with
 262         <option>-s</option>, all nodes added must have a secondary IP
 263         as well.
 264       </para>
 265
 266       <para>
 267         Note that for Ganeti it doesn't matter if the secondary
 268         network is actually a separate physical network, or is done
 269         using tunneling, etc. For performance reasons, it's
 270         recommended to use a separate network, of course.
 271       </para>
 272
 273       <para>
 274         The <option>-b</option> option specifies the default bridge
 275         for instances.
 276       </para>
 277
 278       <para>
 279         The <option>-g</option> option will let you specify a volume group
 280         different than 'xenvg' for ganeti to use when creating instance disks.
 281         This volume group must have the same name on all nodes. Once the
 282         cluster is initialized this can be altered by using the
 283         <command>modify</command> command. If you don't want to use lvm
 284         storage at all use the <option>--no-lvm-storage</option> option.
 285         Once the cluster is initialized you can change this setup with the
 286         <command>modify</command> command.
 287       </para>
 288
 289       <para>
 290         The <option>--master-netdev</option> option is useful for specifying a
 291         different interface on which the master will activate its IP address.
 292         It's important that all nodes have this interface because you'll need
 293         it for a master failover.
 294       </para>
 295
 296       <para>
 297         The <option>-m</option> option will let you specify a three byte prefix
 298         under which the virtual MAC addresses of your instances will be
 299         generated. The prefix must be specified in the format XX:XX:XX and the
 300         default is aa:00:00.
 301       </para>
 302
 303       <para>
 304         The <option>--no-lvm-storage</option> allows you to initialize the
 305         cluster without lvm support. This means that only instances using
 306         files as storage backend will be possible to create. Once the cluster
 307         is initialized you can change this setup with the
 308         <command>modify</command> command.
 309       </para>
 310
 311       <para>
 312         The <option>--file-storage-dir</option> option allows you
 313         set the directory to use for storing the instance disk
 314         files when using file storage as backend for instance disks.
 315       </para>
 316
 317       <para>
 318         The <option>--enabled-hypervisors</option> option allows you
 319         to set the list of hypervisors that will be enabled for
 320         this cluster. Instance hypervisors can only be choosen from
 321         the list of enabled hypervisors. Currently, the following
 322         hypervisors are available:
 323       </para>
 324
 325       <para>
 326         <variablelist>
 327           <varlistentry>
 328             <term>xen-pvm</term>
 329             <listitem>
 330               <para>
 331                 Xen PVM hypervisor
 332               </para>
 333             </listitem>
 334           </varlistentry>
 335           <varlistentry>
 336             <term>xen-hvm</term>
 337             <listitem>
 338               <para>
 339                 Xen HVM hypervisor
 340               </para>
 341             </listitem>
 342           </varlistentry>
 343           <varlistentry>
 344             <term>kvm</term>
 345             <listitem>
 346               <para>
 347                 Linux KVM hypervisor
 348               </para>
 349             </listitem>
 350           </varlistentry>
 351           <varlistentry>
 352             <term>fake</term>
 353             <listitem>
 354               <para>
 355                 fake hypervisor for development/testing
 356               </para>
 357             </listitem>
 358           </varlistentry>
 359         </variablelist>
 360       </para>
 361
 362       <para>
 363         Either a single hypervisor name or a comma-separated list of
 364         hypervisor names can be specified. If this option is not
 365         specified, only the xen-pvm hypervisor is enabled by default.
 366       </para>
 367
 368       <para>
 369         With the <option>-t</option> option, the default hypervisor
 370         can be set. It has to be a member of the list of enabled
 371         hypervisors. If not specified, the first entry on the list of
 372         enabled hypervisors will be used by default.
 373       </para>
 374
 375       <para>
 376         The <option>--backend</option> option allows you to set
 377         the default backend parameters for the cluster. The parameter
 378         format is a comma-separated list of key=value pairs with the
 379         following supported keys:
 380       </para>
 381
 382       <para>
 383         <variablelist>
 384           <varlistentry>
 385             <term>vcpus</term>
 386             <listitem>
 387               <para>
 388                 Number of VCPUs to set for an instance by default, must
 389                 be an integer, will be set to 1 if no specified.
 390               </para>
 391             </listitem>
 392           </varlistentry>
 393           <varlistentry>
 394             <term>memory</term>
 395             <listitem>
 396               <para>
 397                 Amount of memory to allocate for an instance by default,
 398                 can be either an integer or an integer followed by a
 399                 unit (M for mebibytes and G for gibibytes are
 400                 supported), will be set to 128M if not specified.
 401               </para>
 402             </listitem>
 403           </varlistentry>
 404           <varlistentry>
 405             <term>auto_balance</term>
 406             <listitem>
 407               <para>
 408                 Value of the auto_balance flag for instances to use by
 409                 default, will be set to true if not specified.
 410               </para>
 411             </listitem>
 412           </varlistentry>
 413         </variablelist>
 414       </para>
 415
 416       <para>
 417         The <option>--hypervisor-parameters</option> option allows you
 418         to set default hypervisor specific parameters for the
 419         cluster. The format of this option is the name of the
 420         hypervisor, followed by a colon and a comma-separated list of
 421         key=value pairs. The keys available for each hypervisors are
 422         detailed int the <citerefentry>
 423         <refentrytitle>gnt-instance</refentrytitle>
 424         <manvolnum>8</manvolnum> </citerefentry> man page, in the
 425         <command>add</command> command.
 426       </para>
 427
 428     </refsect2>
 429
 430     <refsect2>
 431       <title>LIST-TAGS</title>
 432
 433       <cmdsynopsis>
 434         <command>list-tags</command>
 435       </cmdsynopsis>
 436
 437       <para>List the tags of the cluster.</para>
 438     </refsect2>
 439
 440     <refsect2>
 441       <title>MASTERFAILOVER</title>
 442
 443       <cmdsynopsis>
 444         <command>masterfailover</command>
 445       </cmdsynopsis>
 446
 447       <para>
 448         Failover the master role to the current node.
 449       </para>
 450     </refsect2>
 451
 452     <refsect2>
 453       <title>MODIFY</title>
 454
 455       <cmdsynopsis>
 456         <command>modify</command>
 457         <sbr>
 458         <arg choice="opt">-g <replaceable>vg-name</replaceable></arg>
 459         <sbr>
 460         <arg choice="opt">--no-lvm-storage</arg>
 461         <sbr>
 462         <arg choice="opt">--enabled-hypervisors
 463         <replaceable>hypervisors</replaceable></arg>
 464         <sbr>
 465         <arg choice="opt">--hypervisor-parameters <replaceable>hypervisor</replaceable>:<replaceable>hv-param</replaceable>=<replaceable>value</replaceable><arg rep="repeat" choice="opt">,<replaceable>hv-param</replaceable>=<replaceable>value</replaceable></arg></arg>
 466         <sbr>
 467         <arg choice="opt">--backend-parameters <replaceable>be-param</replaceable>=<replaceable>value</replaceable><arg rep="repeat" choice="opt">,<replaceable>be-param</replaceable>=<replaceable>value</replaceable></arg></arg>
 468         <sbr>
 469         <arg>-C <replaceable>candidate_pool_size</replaceable></arg>
 470
 471       </cmdsynopsis>
 472
 473         <para>
 474           Modify the options for the cluster.
 475         </para>
 476
 477         <para>
 478           The <option>-g</option>, <option>--no-lvm-storarge</option>,
 479           <option>--enabled-hypervisors</option>,
 480           <option>--hypervisor-parameters</option> and
 481           <option>--backend-parameters</option> options are
 482           described in the <command>init</command> command.
 483         </para>
 484
 485       <para>
 486         The <option>-C</option> options specifies the
 487         <varname>candidate_pool_size</varname> cluster parameter. This
 488         is the number of nodes that the master will try to keep as
 489         <literal>master_candidates</literal>. For more details about
 490         this role and other node roles, see the <citerefentry>
 491         <refentrytitle>ganeti</refentrytitle><manvolnum>7</manvolnum>
 492         </citerefentry>. If you increase the size, the master will
 493         automatically promote as many nodes as required and possible
 494         to reach the intended number.
 495       </para>
 496     </refsect2>
 497
 498     <refsect2>
 499       <title>QUEUE</title>
 500
 501       <cmdsynopsis>
 502         <command>queue</command>
 503         <arg choice="opt">drain</arg>
 504         <arg choice="opt">undrain</arg>
 505         <arg choice="opt">info</arg>
 506
 507       </cmdsynopsis>
 508
 509       <para>
 510         Change job queue properties.
 511       </para>
 512
 513       <para>
 514         The <option>drain</option> option sets the drain flag on the
 515         job queue. No new jobs will be accepted, but jobs already in
 516         the queue will be processed.
 517       </para>
 518
 519       <para>
 520         The <option>undrain</option> will unset the drain flag on the
 521         job queue. New jobs will be accepted.
 522       </para>
 523
 524       <para>
 525         The <option>info</option> option shows the properties of the
 526         job queue.
 527       </para>
 528     </refsect2>
 529
 530     <refsect2>
 531       <title>redist-conf</title>
 532       <cmdsynopsis>
 533         <command>redist-conf</command>
 534           <arg>--submit</arg>
 535       </cmdsynopsis>
 536
 537       <para>
 538         This command forces a full push of configuration files from
 539         the master node to the other nodes in the cluster. This is
 540         normally not needed, but can be run if the
 541         <command>verify</command> complains about configuration
 542         mismatches.
 543       </para>
 544
 545       <para>
 546         The <option>--submit</option> option is used to send the job
 547         to the master daemon but not wait for its completion. The job
 548         ID will be shown so that it can be examined via
 549         <command>gnt-job info</command>.
 550       </para>
 551
 552     </refsect2>
 553     <refsect2>
 554       <title>REMOVE-TAGS</title>
 555
 556       <cmdsynopsis>
 557         <command>remove-tags</command>
 558         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 559         <arg choice="req"
 560         rep="repeat"><replaceable>tag</replaceable></arg>
 561       </cmdsynopsis>
 562
 563       <para>
 564         Remove tags from the cluster. If any of the tags are not
 565         existing on the cluster, the entire operation will abort.
 566       </para>
 567
 568       <para>
 569         If the <option>--from</option> option is given, the list of
 570         tags will be extended with the contents of that file (each
 571         line becomes a tag). In this case, there is not need to pass
 572         tags on the command line (if you do, both sources will be
 573         used). A file name of - will be interpreted as stdin.
 574       </para>
 575     </refsect2>
 576
 577     <refsect2>
 578       <title>RENAME</title>
 579
 580       <cmdsynopsis>
 581         <command>rename</command>
 582         <arg>-f</arg>
 583         <arg choice="req"><replaceable>name</replaceable></arg>
 584       </cmdsynopsis>
 585
 586       <para>
 587         Renames the cluster and in the process updates the master IP
 588         address to the one the new name resolves to. At least one of
 589         either the name or the IP address must be different, otherwise
 590         the operation will be aborted.
 591       </para>
 592
 593       <para>
 594         Note that since this command can be dangerous (especially when
 595         run over SSH), the command will require confirmation unless
 596         run with the <option>-f</option> option.
 597       </para>
 598     </refsect2>
 599
 600     <refsect2>
 601       <title>SEARCH-TAGS</title>
 602
 603       <cmdsynopsis>
 604         <command>search-tags</command>
 605         <arg choice="req"><replaceable>pattern</replaceable></arg>
 606       </cmdsynopsis>
 607
 608       <para>
 609         Searches the tags on all objects in the cluster (the cluster
 610         itself, the nodes and the instances) for a given pattern. The
 611         pattern is interpreted as a regular expression and a search
 612         will be done on it (i.e. the given pattern is not anchored to
 613         the beggining of the string; if you want that, prefix the
 614         pattern with <literal>^</literal>).
 615       </para>
 616
 617       <para>
 618         If no tags are matching the pattern, the exit code of the
 619         command will be one. If there is at least one match, the exit
 620         code will be zero. Each match is listed on one line, the
 621         object and the tag separated by a space. The cluster will be
 622         listed as <filename>/cluster</filename>, a node will be listed
 623         as
 624         <filename>/nodes/<replaceable>name</replaceable></filename>,
 625         and an instance as
 626         <filename>/instances/<replaceable>name</replaceable></filename>.
 627         Example:
 628       </para>
 629 <screen>
 630 # gnt-cluster search time
 631 /cluster ctime:2007-09-01
 632 /nodes/node1.example.com mtime:2007-10-04
 633 </screen>
 634     </refsect2>
 635
 636     <refsect2>
 637       <title>VERIFY</title>
 638
 639       <cmdsynopsis>
 640         <command>verify</command>
 641         <arg choice="opt">--no-nplus1-mem</arg>
 642       </cmdsynopsis>
 643
 644       <para>
 645         Verify correctness of cluster configuration. This is safe with
 646         respect to running instances, and incurs no downtime of the
 647         instances.
 648       </para>
 649
 650       <para>
 651         If the <option>--no-nplus1-mem</option> option is given, ganeti won't
 652         check whether if it loses a node it can restart all the instances on
 653         their secondaries (and report an error otherwise).
 654       </para>
 655     </refsect2>
 656
 657     <refsect2>
 658       <title>VERIFY-DISKS</title>
 659
 660       <cmdsynopsis>
 661         <command>verify-disks</command>
 662       </cmdsynopsis>
 663
 664       <para>
 665         The command checks which instances have degraded DRBD disks
 666         and activates the disks of those instances.
 667       </para>
 668
 669       <para>
 670         This command is run from the <command>ganeti-watcher</command>
 671         tool, which also has a different, complementary algorithm for
 672         doing this check. Together, these two should ensure that DRBD
 673         disks are kept consistent.
 674       </para>
 675     </refsect2>
 676
 677     <refsect2>
 678       <title>VERSION</title>
 679
 680       <cmdsynopsis>
 681         <command>version</command>
 682       </cmdsynopsis>
 683
 684       <para>
 685         Show the cluster version.
 686       </para>
 687     </refsect2>
 688
 689   </refsect1>
 690
 691   &footer;
 692
 693 </refentry>
 694
 695 <!-- Keep this comment at the end of the file
 696 Local variables:
 697 mode: sgml
 698 sgml-omittag:t
 699 sgml-shorttag:t
 700 sgml-minimize-attributes:nil
 701 sgml-always-quote-attributes:t
 702 sgml-indent-step:2
 703 sgml-indent-data:t
 704 sgml-parent-document:nil
 705 sgml-default-dtd-file:nil
 706 sgml-exposed-tags:nil
 707 sgml-local-catalogs:nil
 708 sgml-local-ecat-files:nil
 709 End:
 710 -->