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 constructed by concatenating all other command
 106         line arguments. For example, to list the contents of the
 107         <filename class="directory">/etc</filename> directory on all
 108         nodes, run:
 109
 110         <screen>
 111           # gnt-cluster command ls -l /etc
 112         </screen>
 113
 114         and the command which will be executed will be
 115         <computeroutput>"ls -l /etc"</computeroutput>
 116       </para>
 117     </refsect2>
 118
 119     <refsect2>
 120       <title>COPYFILE</title>
 121
 122       <cmdsynopsis>
 123         <command>copyfile</command>
 124         <arg>-n <replaceable>node</replaceable></arg>
 125         <arg choice="req"><replaceable>file</replaceable></arg>
 126       </cmdsynopsis>
 127
 128       <para>
 129         Copies a file to all or to some nodes. The argument specifies
 130         the source file (on the current system), the
 131         <option>-n</option> argument specifies the target node, or
 132         nodes if the option is given multiple times. If
 133         <option>-n</option> is not given at all, the file will be
 134         copied to all nodes.
 135
 136         Example:
 137         <screen>
 138           # gnt-cluster -n node1.example.com -n node2.example.com copyfile /tmp/test
 139         </screen>
 140
 141         This will copy the file <filename>/tmp/test</filename> from
 142         the current node to the two named nodes.
 143       </para>
 144     </refsect2>
 145
 146     <refsect2>
 147       <title>DESTROY</title>
 148
 149       <cmdsynopsis>
 150         <command>destroy</command>
 151         <arg choice="req">--yes-do-it</arg>
 152       </cmdsynopsis>
 153
 154       <para>
 155         Remove all configuration files related to the cluster, so that
 156         a <command>gnt-cluster init</command> can be done again
 157         afterwards.
 158       </para>
 159
 160       <para>
 161         Since this is a dangerous command, you are required to pass
 162         the argument <replaceable>--yes-do-it.</replaceable>
 163       </para>
 164     </refsect2>
 165
 166     <refsect2>
 167       <title>GETMASTER</title>
 168
 169       <cmdsynopsis>
 170         <command>getmaster</command>
 171       </cmdsynopsis>
 172
 173       <para>
 174         Displays the current master node.
 175       </para>
 176     </refsect2>
 177
 178     <refsect2>
 179       <title>INFO</title>
 180
 181       <cmdsynopsis>
 182         <command>info</command>
 183       </cmdsynopsis>
 184
 185       <para>
 186         Shows runtime cluster information: cluster name, architecture
 187         (32 or 64 bit), master node, node list and instance list.
 188       </para>
 189     </refsect2>
 190
 191     <refsect2>
 192       <title>INIT</title>
 193
 194       <cmdsynopsis>
 195         <command>init</command>
 196         <arg>-s <replaceable>secondary_ip</replaceable></arg>
 197         <arg>-b <replaceable>bridge</replaceable></arg>
 198         <arg choice="req"><replaceable>clustername</replaceable></arg>
 199       </cmdsynopsis>
 200
 201       <para>
 202         This commands is only run once initially on the first node of
 203         the cluster. It will initialize the cluster configuration and
 204         setup ssh-keys and more.
 205       </para>
 206
 207       <para>
 208         Note that the <replaceable>clustername</replaceable> is not
 209         any random name. It has to be resolvable to an IP address
 210         using DNS, and it is best if you give the fully-qualified
 211         domain name.
 212       </para>
 213
 214       <para>
 215         The cluster can run in two modes: single-home or
 216         dual-homed. In the first case, all traffic (both public
 217         traffic, inter-node traffic and data replication traffic) goes
 218         over the same interface. In the dual-homed case, the data
 219         replication traffic goes over the second network. The
 220         <option>-s</option> option here marks the cluster as
 221         dual-homed and its parameter represents this node's address on
 222         the second network. If you initialise the cluster with
 223         <option>-s</option>, all nodes added must have a secondary IP
 224         as well.
 225       </para>
 226
 227       <para>
 228         Note that for Ganeti it doesn't matter if the secondary
 229
 230         network is actually a separate physical network, or is done
 231         using tunneling, etc. For performance reasons, it's
 232         recommended to use a separate network, of course.
 233       </para>
 234
 235       <para>
 236         The <option>-b</option> option specifies the default bridge
 237         for instances.
 238       </para>
 239       <para>
 240         The <option>-t</option> allows to set the hypervisor type of
 241         the cluster. Available hypervisor types are: xen-3.0, fake and
 242         xen-hvm3.1. The default is the xen-3.0 hypervisor.
 243         Note that if you init the cluster with hypervisor-type
 244         xen-hvm3.1 you also need to provide the cluster VNC password
 245         file <filename>/etc/ganeti/vnc-cluster-password</filename> and
 246         the HVM boot ISO image
 247         <filename>/srv/ganeti/iso/hvm-install.iso</filename> because
 248         instances created by the experimental HVM support require them.
 249       </para>
 250     </refsect2>
 251
 252     <refsect2>
 253       <title>LIST-TAGS</title>
 254
 255       <cmdsynopsis>
 256         <command>list-tags</command>
 257       </cmdsynopsis>
 258
 259       <para>List the tags of the cluster.</para>
 260     </refsect2>
 261
 262     <refsect2>
 263       <title>MASTERFAILOVER</title>
 264
 265       <cmdsynopsis>
 266         <command>masterfailover</command>
 267       </cmdsynopsis>
 268
 269       <para>
 270         Failover the master role to the current node.
 271       </para>
 272     </refsect2>
 273
 274     <refsect2>
 275       <title>REMOVE-TAGS</title>
 276
 277       <cmdsynopsis>
 278         <command>remove-tags</command>
 279         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 280         <arg choice="req"
 281         rep="repeat"><replaceable>tag</replaceable></arg>
 282       </cmdsynopsis>
 283
 284       <para>
 285         Remove tags from the cluster. If any of the tags are not
 286         existing on the cluster, the entire operation will abort.
 287       </para>
 288
 289       <para>
 290         If the <option>--from</option> option is given, the list of
 291         tags will be extended with the contents of that file (each
 292         line becomes a tag). In this case, there is not need to pass
 293         tags on the command line (if you do, both sources will be
 294         used). A file name of - will be interpreted as stdin.
 295       </para>
 296     </refsect2>
 297
 298     <refsect2>
 299       <title>RENAME</title>
 300
 301       <cmdsynopsis>
 302         <command>rename</command>
 303         <arg>-f</arg>
 304         <arg choice="req"><replaceable>name</replaceable></arg>
 305       </cmdsynopsis>
 306
 307       <para>
 308         Renames the cluster and in the process updates the master IP
 309         address to the one the new name resolves to. At least one of
 310         either the name or the IP address must be different, otherwise
 311         the operation will be aborted.
 312       </para>
 313
 314       <para>
 315         Note that since this command can be dangerous (especially when
 316         run over SSH), the command will require confirmation unless
 317         run with the <option>-f</option> option.
 318       </para>
 319     </refsect2>
 320
 321     <refsect2>
 322       <title>SEARCH-TAGS</title>
 323
 324       <cmdsynopsis>
 325         <command>search-tags</command>
 326         <arg choice="req"><replaceable>pattern</replaceable></arg>
 327       </cmdsynopsis>
 328
 329       <para>
 330         Searches the tags on all objects in the cluster (the cluster
 331         itself, the nodes and the instances) for a given pattern. The
 332         pattern is interpreted as a regular expression and a search
 333         will be done on it (i.e. the given pattern is not anchored to
 334         the beggining of the string; if you want that, prefix the
 335         pattern with <literal>^</literal>).
 336       </para>
 337
 338       <para>
 339         If no tags are matching the pattern, the exit code of the
 340         command will be one. If there is at least one match, the exit
 341         code will be zero. Each match is listed on one line, the
 342         object and the tag separated by a space. The cluster will be
 343         listed as <filename>/cluster</filename>, a node will be listed
 344         as
 345         <filename>/nodes/<replaceable>name</replaceable></filename>,
 346         and an instance as
 347         <filename>/instances/<replaceable>name</replaceable></filename>.
 348         Example:
 349       </para>
 350 <screen>
 351 # gnt-cluster search time
 352 /cluster ctime:2007-09-01
 353 /nodes/node1.example.com mtime:2007-10-04
 354 </screen>
 355     </refsect2>
 356
 357     <refsect2>
 358       <title>VERIFY</title>
 359
 360       <cmdsynopsis>
 361         <command>verify</command>
 362       </cmdsynopsis>
 363
 364       <para>
 365         Verify correctness of cluster configuration. This is safe with
 366         respect to running instances, and incurs no downtime of the
 367         instances.
 368       </para>
 369     </refsect2>
 370
 371     <refsect2>
 372       <title>VERIFY-DISKS</title>
 373
 374       <cmdsynopsis>
 375         <command>verify-disks</command>
 376       </cmdsynopsis>
 377
 378       <para>
 379         The command checks which instances have degraded DRBD disks
 380         and activates the disks of those instances.
 381       </para>
 382
 383       <para>
 384         This command is run from the <command>ganeti-watcher</command>
 385         tool, which also has a different, complementary algorithm for
 386         doing this check. Together, these two should ensure that DRBD
 387         disks are kept consistent.
 388       </para>
 389     </refsect2>
 390
 391     <refsect2>
 392       <title>VERSION</title>
 393
 394       <cmdsynopsis>
 395         <command>version</command>
 396       </cmdsynopsis>
 397
 398       <para>
 399         Show the cluster version.
 400       </para>
 401     </refsect2>
 402
 403   </refsect1>
 404
 405   &footer;
 406
 407 </refentry>
 408
 409 <!-- Keep this comment at the end of the file
 410 Local variables:
 411 mode: sgml
 412 sgml-omittag:t
 413 sgml-shorttag:t
 414 sgml-minimize-attributes:nil
 415 sgml-always-quote-attributes:t
 416 sgml-indent-step:2
 417 sgml-indent-data:t
 418 sgml-parent-document:nil
 419 sgml-default-dtd-file:nil
 420 sgml-exposed-tags:nil
 421 sgml-local-catalogs:nil
 422 sgml-local-ecat-files:nil
 423 End:
 424 -->