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>June 20, 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     </refsect2>
 240
 241     <refsect2>
 242       <title>LIST-TAGS</title>
 243
 244       <cmdsynopsis>
 245         <command>list-tags</command>
 246       </cmdsynopsis>
 247
 248       <para>List the tags of the cluster.</para>
 249     </refsect2>
 250
 251     <refsect2>
 252       <title>MASTERFAILOVER</title>
 253
 254       <cmdsynopsis>
 255         <command>masterfailover</command>
 256       </cmdsynopsis>
 257
 258       <para>
 259         Failover the master role to the current node.
 260       </para>
 261     </refsect2>
 262
 263     <refsect2>
 264       <title>REMOVE-TAGS</title>
 265
 266       <cmdsynopsis>
 267         <command>remove-tags</command>
 268         <arg choice="opt">--from <replaceable>file</replaceable></arg>
 269         <arg choice="req"
 270         rep="repeat"><replaceable>tag</replaceable></arg>
 271       </cmdsynopsis>
 272
 273       <para>
 274         Remove tags from the cluster. If any of the tags are not
 275         existing on the cluster, the entire operation will abort.
 276       </para>
 277
 278       <para>
 279         If the <option>--from</option> option is given, the list of
 280         tags will be extended with the contents of that file (each
 281         line becomes a tag). In this case, there is not need to pass
 282         tags on the command line (if you do, both sources will be
 283         used). A file name of - will be interpreted as stdin.
 284       </para>
 285     </refsect2>
 286
 287     <refsect2>
 288       <title>RENAME</title>
 289
 290       <cmdsynopsis>
 291         <command>rename</command>
 292         <arg>-f</arg>
 293         <arg choice="req"><replaceable>name</replaceable></arg>
 294       </cmdsynopsis>
 295
 296       <para>
 297         Renames the cluster and in the process updates the master IP
 298         address to the one the new name resolves to. At least one of
 299         either the name or the IP address must be different, otherwise
 300         the operation will be aborted.
 301       </para>
 302
 303       <para>
 304         Note that since this command can be dangerous (especially when
 305         run over SSH), the command will require confirmation unless
 306         run with the <option>-f</option> option.
 307       </para>
 308     </refsect2>
 309
 310     <refsect2>
 311       <title>SEARCH-TAGS</title>
 312
 313       <cmdsynopsis>
 314         <command>search-tags</command>
 315         <arg choice="req"><replaceable>pattern</replaceable></arg>
 316       </cmdsynopsis>
 317
 318       <para>
 319         Searches the tags on all objects in the cluster (the cluster
 320         itself, the nodes and the instances) for a given pattern. The
 321         pattern is interpreted as a regular expression and a search
 322         will be done on it (i.e. the given pattern is not anchored to
 323         the beggining of the string; if you want that, prefix the
 324         pattern with <literal>^</literal>).
 325       </para>
 326
 327       <para>
 328         If no tags are matching the pattern, the exit code of the
 329         command will be one. If there is at least one match, the exit
 330         code will be zero. Each match is listed on one line, the
 331         object and the tag separated by a space. The cluster will be
 332         listed as <filename>/cluster</filename>, a node will be listed
 333         as
 334         <filename>/nodes/<replaceable>name</replaceable></filename>,
 335         and an instance as
 336         <filename>/instances/<replaceable>name</replaceable></filename>.
 337         Example:
 338       </para>
 339 <screen>
 340 # gnt-cluster search time
 341 /cluster ctime:2007-09-01
 342 /nodes/node1.example.com mtime:2007-10-04
 343 </screen>
 344     </refsect2>
 345
 346     <refsect2>
 347       <title>VERIFY</title>
 348
 349       <cmdsynopsis>
 350         <command>verify</command>
 351       </cmdsynopsis>
 352
 353       <para>
 354         Verify correctness of cluster configuration. This is safe with
 355         respect to running instances, and incurs no downtime of the
 356         instances.
 357       </para>
 358     </refsect2>
 359
 360     <refsect2>
 361       <title>VERSION</title>
 362
 363       <cmdsynopsis>
 364         <command>version</command>
 365       </cmdsynopsis>
 366
 367       <para>
 368         Show the cluster version.
 369       </para>
 370     </refsect2>
 371
 372   </refsect1>
 373
 374   &footer;
 375
 376 </refentry>
 377
 378 <!-- Keep this comment at the end of the file
 379 Local variables:
 380 mode: sgml
 381 sgml-omittag:t
 382 sgml-shorttag:t
 383 sgml-minimize-attributes:nil
 384 sgml-always-quote-attributes:t
 385 sgml-indent-step:2
 386 sgml-indent-data:t
 387 sgml-parent-document:nil
 388 sgml-default-dtd-file:nil
 389 sgml-exposed-tags:nil
 390 sgml-local-catalogs:nil
 391 sgml-local-ecat-files:nil
 392 End:
 393 -->