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>hv-params</replaceable></arg>
 233         <sbr>
 234         <arg>--backend-parameters <replaceable>be-params</replaceable></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
 466         <replaceable>hv-params</replaceable></arg>
 467         <sbr>
 468         <arg choice="opt">--backend-parameters
 469         <replaceable>be-params</replaceable></arg>
 470         <sbr>
 471         <arg>-C <replaceable>candidate_pool_size</replaceable></arg>
 472
 473       </cmdsynopsis>
 474
 475         <para>
 476           Modify the options for the cluster.
 477         </para>
 478
 479         <para>
 480           The <option>-g</option>, <option>--no-lvm-storarge</option>,
 481           <option>--enabled-hypervisors</option>,
 482           <option>--hypervisor-parameters</option> and
 483           <option>--backend-parameters</option> options are
 484           described in the <command>init</command> command.
 485         </para>
 486
 487       <para>
 488         The <option>-C</option> options specifies the
 489         <varname>candidate_pool_size</varname> cluster parameter. This
 490         is the number of nodes that the master will try to keep as
 491         <literal>master_candidates</literal>. For more details about
 492         this role and other node roles, see the <citerefentry>
 493         <refentrytitle>ganeti</refentrytitle><manvolnum>7</manvolnum>
 494         </citerefentry>. If you increase the size, the master will
 495         automatically promote as many nodes as required and possible
 496         to reach the intended number.
 497       </para>
 498     </refsect2>
 499
 500     <refsect2>
 501       <title>QUEUE</title>
 502
 503       <cmdsynopsis>
 504         <command>queue</command>
 505         <arg choice="opt">drain</arg>
 506         <arg choice="opt">undrain</arg>
 507         <arg choice="opt">info</arg>
 508
 509       </cmdsynopsis>
 510
 511       <para>
 512         Change job queue properties.
 513       </para>
 514
 515       <para>
 516         The <option>drain</option> option sets the drain flag on the
 517         job queue. No new jobs will be accepted, but jobs already in
 518         the queue will be processed.
 519       </para>
 520
 521       <para>
 522         The <option>undrain</option> will unset the drain flag on the
 523         job queue. New jobs will be accepted.
 524       </para>
 525
 526       <para>
 527         The <option>info</option> option shows the properties of the
 528         job queue.
 529       </para>
 530     </refsect2>
 531
 532     <refsect2>
 533       <title>redist-conf</title>
 534       <cmdsynopsis>
 535         <command>redist-conf</command>
 536           <arg>--submit</arg>
 537       </cmdsynopsis>
 538
 539       <para>
 540         This command forces a full push of configuration files from
 541         the master node to the other nodes in the cluster. This is
 542         normally not needed, but can be run if the
 543         <command>verify</command> complains about configuration
 544         mismatches.
 545       </para>
 546
 547       <para>
 548         The <option>--submit</option> option is used to send the job
 549         to the master daemon but not wait for its completion. The job
 550         ID will be shown so that it can be examined via
 551         <command>gnt-job info</command>.
 552       </para>
 553
 554     </refsect2>
 555     <refsect2>
 556       <title>REMOVE-TAGS</title>
 557
 558       <cmdsynopsis>
 559         <command>remove-tags</command>
 560         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 561         <arg choice="req"
 562         rep="repeat"><replaceable>tag</replaceable></arg>
 563       </cmdsynopsis>
 564
 565       <para>
 566         Remove tags from the cluster. If any of the tags are not
 567         existing on the cluster, the entire operation will abort.
 568       </para>
 569
 570       <para>
 571         If the <option>--from</option> option is given, the list of
 572         tags will be extended with the contents of that file (each
 573         line becomes a tag). In this case, there is not need to pass
 574         tags on the command line (if you do, both sources will be
 575         used). A file name of - will be interpreted as stdin.
 576       </para>
 577     </refsect2>
 578
 579     <refsect2>
 580       <title>RENAME</title>
 581
 582       <cmdsynopsis>
 583         <command>rename</command>
 584         <arg>-f</arg>
 585         <arg choice="req"><replaceable>name</replaceable></arg>
 586       </cmdsynopsis>
 587
 588       <para>
 589         Renames the cluster and in the process updates the master IP
 590         address to the one the new name resolves to. At least one of
 591         either the name or the IP address must be different, otherwise
 592         the operation will be aborted.
 593       </para>
 594
 595       <para>
 596         Note that since this command can be dangerous (especially when
 597         run over SSH), the command will require confirmation unless
 598         run with the <option>-f</option> option.
 599       </para>
 600     </refsect2>
 601
 602     <refsect2>
 603       <title>SEARCH-TAGS</title>
 604
 605       <cmdsynopsis>
 606         <command>search-tags</command>
 607         <arg choice="req"><replaceable>pattern</replaceable></arg>
 608       </cmdsynopsis>
 609
 610       <para>
 611         Searches the tags on all objects in the cluster (the cluster
 612         itself, the nodes and the instances) for a given pattern. The
 613         pattern is interpreted as a regular expression and a search
 614         will be done on it (i.e. the given pattern is not anchored to
 615         the beggining of the string; if you want that, prefix the
 616         pattern with <literal>^</literal>).
 617       </para>
 618
 619       <para>
 620         If no tags are matching the pattern, the exit code of the
 621         command will be one. If there is at least one match, the exit
 622         code will be zero. Each match is listed on one line, the
 623         object and the tag separated by a space. The cluster will be
 624         listed as <filename>/cluster</filename>, a node will be listed
 625         as
 626         <filename>/nodes/<replaceable>name</replaceable></filename>,
 627         and an instance as
 628         <filename>/instances/<replaceable>name</replaceable></filename>.
 629         Example:
 630       </para>
 631 <screen>
 632 # gnt-cluster search time
 633 /cluster ctime:2007-09-01
 634 /nodes/node1.example.com mtime:2007-10-04
 635 </screen>
 636     </refsect2>
 637
 638     <refsect2>
 639       <title>VERIFY</title>
 640
 641       <cmdsynopsis>
 642         <command>verify</command>
 643         <arg choice="opt">--no-nplus1-mem</arg>
 644       </cmdsynopsis>
 645
 646       <para>
 647         Verify correctness of cluster configuration. This is safe with
 648         respect to running instances, and incurs no downtime of the
 649         instances.
 650       </para>
 651
 652       <para>
 653         If the <option>--no-nplus1-mem</option> option is given, ganeti won't
 654         check whether if it loses a node it can restart all the instances on
 655         their secondaries (and report an error otherwise).
 656       </para>
 657     </refsect2>
 658
 659     <refsect2>
 660       <title>VERIFY-DISKS</title>
 661
 662       <cmdsynopsis>
 663         <command>verify-disks</command>
 664       </cmdsynopsis>
 665
 666       <para>
 667         The command checks which instances have degraded DRBD disks
 668         and activates the disks of those instances.
 669       </para>
 670
 671       <para>
 672         This command is run from the <command>ganeti-watcher</command>
 673         tool, which also has a different, complementary algorithm for
 674         doing this check. Together, these two should ensure that DRBD
 675         disks are kept consistent.
 676       </para>
 677     </refsect2>
 678
 679     <refsect2>
 680       <title>VERSION</title>
 681
 682       <cmdsynopsis>
 683         <command>version</command>
 684       </cmdsynopsis>
 685
 686       <para>
 687         Show the cluster version.
 688       </para>
 689     </refsect2>
 690
 691   </refsect1>
 692
 693   &footer;
 694
 695 </refentry>
 696
 697 <!-- Keep this comment at the end of the file
 698 Local variables:
 699 mode: sgml
 700 sgml-omittag:t
 701 sgml-shorttag:t
 702 sgml-minimize-attributes:nil
 703 sgml-always-quote-attributes:t
 704 sgml-indent-step:2
 705 sgml-indent-data:t
 706 sgml-parent-document:nil
 707 sgml-default-dtd-file:nil
 708 sgml-exposed-tags:nil
 709 sgml-local-catalogs:nil
 710 sgml-local-ecat-files:nil
 711 End:
 712 -->