gnt-cluster.sgml 35.9 KB
Newer Older
Iustin Pop's avatar
Iustin Pop committed
1
2
3
4
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!-- Please adjust the date whenever revising the manpage. -->
5
  <!ENTITY dhdate      "<date>June 08, 2010</date>">
Iustin Pop's avatar
Iustin Pop committed
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
  <!ENTITY dhucpackage "<refentrytitle>gnt-cluster</refentrytitle>">
  <!ENTITY dhpackage   "gnt-cluster">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  <!ENTITY footer SYSTEM "footer.sgml">
]>

<refentry>
  <refentryinfo>
    <copyright>
      <year>2006</year>
      <year>2007</year>
23
24
      <year>2008</year>
      <year>2009</year>
Iustin Pop's avatar
Iustin Pop committed
25
26
27
28
29
30
31
32
      <holder>Google Inc.</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
33
    <refmiscinfo>Ganeti 2.2</refmiscinfo>
Iustin Pop's avatar
Iustin Pop committed
34
35
36
37
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

38
    <refpurpose>Ganeti administration, cluster-wide</refpurpose>
Iustin Pop's avatar
Iustin Pop committed
39
40
41
42
43
44
45
46
47
48
49
50
51
52
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage; </command>

      <arg choice="req">command</arg>
      <arg>arguments...</arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      The <command>&dhpackage;</command> is used for cluster-wide
53
      administration in the Ganeti system.
Iustin Pop's avatar
Iustin Pop committed
54
55
56
57
58
59
    </para>

  </refsect1>
  <refsect1>
    <title>COMMANDS</title>

60
61
62
63
64
    <refsect2>
      <title>ADD-TAGS</title>

      <cmdsynopsis>
        <command>add-tags</command>
65
        <arg choice="opt">--from <replaceable>file</replaceable></arg>
66
67
68
69
70
71
72
73
        <arg choice="req"
        rep="repeat"><replaceable>tag</replaceable></arg>
      </cmdsynopsis>

      <para>
        Add tags to the cluster. If any of the tags contains invalid
        characters, the entire operation will abort.
      </para>
74
75
76
77
78
79
80
81

      <para>
        If the <option>--from</option> option is given, the list of
        tags will be extended with the contents of that file (each
        line becomes a tag). In this case, there is not need to pass
        tags on the command line (if you do, both sources will be
        used). A file name of - will be interpreted as stdin.
      </para>
82
83
    </refsect2>

84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
    <refsect2>
      <title>COMMAND</title>

      <cmdsynopsis>
        <command>command</command>
        <arg>-n <replaceable>node</replaceable></arg>
        <arg choice="req"><replaceable>command</replaceable></arg>
      </cmdsynopsis>

      <para>
        Executes a command on all nodes. If the option
        <option>-n</option> is not given, the command will be executed
        on all nodes, otherwise it will be executed only on the
        node(s) specified. Use the option multiple times for running
        it on multiple nodes, like:

        <screen>
          # gnt-cluster command -n node1.example.com -n node2.example.com date
        </screen>

      </para>

106
107
108
109
      <para>
        The command is executed serially on the selected nodes. If the
        master node is present in the list, the command will be
        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
114
115
116
117
118
119
120
      </para>

      <para>
        So given the node names node1, node2, node3, node10, node11,
        with node3 being the master, the order will be: node1, node2,
        node10, node11, node3.
      </para>

121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
      <para>
        The command is constructed by concatenating all other command
        line arguments. For example, to list the contents of the
        <filename class="directory">/etc</filename> directory on all
        nodes, run:

        <screen>
          # gnt-cluster command ls -l /etc
        </screen>

        and the command which will be executed will be
        <computeroutput>"ls -l /etc"</computeroutput>
      </para>
    </refsect2>

    <refsect2>
      <title>COPYFILE</title>

      <cmdsynopsis>
        <command>copyfile</command>
141
        <arg>--use-replication-network</arg>
142
143
144
145
146
147
148
149
150
151
152
153
        <arg>-n <replaceable>node</replaceable></arg>
        <arg choice="req"><replaceable>file</replaceable></arg>
      </cmdsynopsis>

      <para>
        Copies a file to all or to some nodes. The argument specifies
        the source file (on the current system), the
        <option>-n</option> argument specifies the target node, or
        nodes if the option is given multiple times. If
        <option>-n</option> is not given at all, the file will be
        copied to all nodes.

154
155
156
157
        Passing the <option>--use-replication-network</option> option
        will cause the copy to be done over the replication network
        (only matters if the primary/secondary IPs are different).

158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
        Example:
        <screen>
          # gnt-cluster -n node1.example.com -n node2.example.com copyfile /tmp/test
        </screen>

        This will copy the file <filename>/tmp/test</filename> from
        the current node to the two named nodes.
      </para>
    </refsect2>

    <refsect2>
      <title>DESTROY</title>

      <cmdsynopsis>
        <command>destroy</command>
Iustin Pop's avatar
Iustin Pop committed
173
        <arg choice="req">--yes-do-it</arg>
174
175
176
177
178
179
180
      </cmdsynopsis>

      <para>
        Remove all configuration files related to the cluster, so that
        a <command>gnt-cluster init</command> can be done again
        afterwards.
      </para>
Iustin Pop's avatar
Iustin Pop committed
181
182
183
184
185

      <para>
        Since this is a dangerous command, you are required to pass
        the argument <replaceable>--yes-do-it.</replaceable>
      </para>
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
    </refsect2>

    <refsect2>
      <title>GETMASTER</title>

      <cmdsynopsis>
        <command>getmaster</command>
      </cmdsynopsis>

      <para>
        Displays the current master node.
      </para>
    </refsect2>

    <refsect2>
      <title>INFO</title>

      <cmdsynopsis>
        <command>info</command>
Guido Trotter's avatar
Guido Trotter committed
205
        <arg>--roman</arg>
206
207
208
209
210
211
      </cmdsynopsis>

      <para>
        Shows runtime cluster information: cluster name, architecture
        (32 or 64 bit), master node, node list and instance list.
      </para>
Guido Trotter's avatar
Guido Trotter committed
212
213
214
215
216
217
218

      <para>
        Passing the <option>--roman</option> option gnt-cluster info will try
        to print its integer fields in a latin friendly way. This allows
        further diffusion of Ganeti among ancient cultures.
      </para>

219
220
221
222
223
224
225
    </refsect2>

    <refsect2>
      <title>INIT</title>

      <cmdsynopsis>
        <command>init</command>
226
        <sbr>
227
        <arg>-s <replaceable>secondary_ip</replaceable></arg>
228
        <sbr>
229
        <arg>--vg-name <replaceable>vg-name</replaceable></arg>
230
        <sbr>
231
        <arg>--master-netdev <replaceable>interface-name</replaceable></arg>
232
        <sbr>
233
        <arg>-m <replaceable>mac-prefix</replaceable></arg>
234
        <sbr>
235
        <arg>--no-lvm-storage</arg>
236
        <sbr>
237
238
239
240
        <arg>--no-etc-hosts</arg>
        <sbr>
        <arg>--no-ssh-init</arg>
        <sbr>
241
        <arg>--file-storage-dir <replaceable>dir</replaceable></arg>
242
        <sbr>
243
        <arg>--enabled-hypervisors <replaceable>hypervisors</replaceable></arg>
244
        <sbr>
245
        <arg>-t <replaceable>hypervisor name</replaceable></arg>
246
        <sbr>
247
        <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>
248
        <sbr>
249
        <arg>--backend-parameters <replaceable>be-param</replaceable>=<replaceable>value</replaceable><arg rep="repeat" choice="opt">,<replaceable>be-param</replaceable>=<replaceable>value</replaceable></arg></arg>
250
        <sbr>
251
252
        <arg>--nic-parameters <replaceable>nic-param</replaceable>=<replaceable>value</replaceable><arg rep="repeat" choice="opt">,<replaceable>nic-param</replaceable>=<replaceable>value</replaceable></arg></arg>
        <sbr>
253
254
        <arg>--maintain-node-health <group choice="req"><arg>yes</arg><arg>no</arg></group></arg>
        <sbr>
255
256
        <arg>--uid-pool <replaceable>user-id pool definition</replaceable></arg>
        <sbr>
257
258
        <arg>-I <replaceable>default instance allocator</replaceable></arg>
        <sbr>
259
260
        <arg>--primary-ip-version <replaceable>version</replaceable></arg>
        <sbr>
261
        <arg>--prealloc-wipe-disks <group choice="req"><arg>yes</arg><arg>no</arg></group></arg>
262
        <sbr>
263
264
265
266
267
268
269
270
271
272
273
274
275
        <arg choice="req"><replaceable>clustername</replaceable></arg>
      </cmdsynopsis>

      <para>
        This commands is only run once initially on the first node of
        the cluster. It will initialize the cluster configuration and
        setup ssh-keys and more.
      </para>

      <para>
        Note that the <replaceable>clustername</replaceable> is not
        any random name. It has to be resolvable to an IP address
        using DNS, and it is best if you give the fully-qualified
276
277
        domain name. This hostname must resolve to an IP address
        reserved exclusively for this purpose.
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
      </para>

      <para>
        The cluster can run in two modes: single-home or
        dual-homed. In the first case, all traffic (both public
        traffic, inter-node traffic and data replication traffic) goes
        over the same interface. In the dual-homed case, the data
        replication traffic goes over the second network. The
        <option>-s</option> option here marks the cluster as
        dual-homed and its parameter represents this node's address on
        the second network. If you initialise the cluster with
        <option>-s</option>, all nodes added must have a secondary IP
        as well.
      </para>

      <para>
        Note that for Ganeti it doesn't matter if the secondary
        network is actually a separate physical network, or is done
        using tunneling, etc. For performance reasons, it's
        recommended to use a separate network, of course.
      </para>

300
      <para>
301
        The <option>--vg-name</option> option will let you specify a volume group
302
        different than "xenvg" for Ganeti to use when creating instance disks.
303
304
305
306
307
308
        This volume group must have the same name on all nodes. Once the
        cluster is initialized this can be altered by using the
        <command>modify</command> command. If you don't want to use lvm
        storage at all use the <option>--no-lvm-storage</option> option.
        Once the cluster is initialized you can change this setup with the
        <command>modify</command> command.
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
      </para>

      <para>
        The <option>--master-netdev</option> option is useful for specifying a
        different interface on which the master will activate its IP address.
        It's important that all nodes have this interface because you'll need
        it for a master failover.
      </para>

      <para>
        The <option>-m</option> option will let you specify a three byte prefix
        under which the virtual MAC addresses of your instances will be
        generated. The prefix must be specified in the format XX:XX:XX and the
        default is aa:00:00.
      </para>

325
      <para>
326
327
        The <option>--no-lvm-storage</option> option allows you to initialize
        the cluster without lvm support. This means that only instances using
328
329
330
331
        files as storage backend will be possible to create. Once the cluster
        is initialized you can change this setup with the
        <command>modify</command> command.
      </para>
332

333
334
335
336
337
338
339
340
341
342
      <para>
        The <option>--no-etc-hosts</option> option allows you to initialize the
        cluster without modifying the <filename>/etc/hosts</filename> file.
      </para>

      <para>
        The <option>--no-ssh-init</option> option allows you to initialize the
        cluster without creating or distributing SSH key pairs.
      </para>

343
344
345
346
347
348
349
350
351
      <para>
        The <option>--file-storage-dir</option> option allows you
        set the directory to use for storing the instance disk
        files when using file storage as backend for instance disks.
      </para>

      <para>
        The <option>--enabled-hypervisors</option> option allows you
        to set the list of hypervisors that will be enabled for
Iustin Pop's avatar
Iustin Pop committed
352
        this cluster. Instance hypervisors can only be chosen from
353
354
355
        the list of enabled hypervisors, and the first entry of this list
        will be used by default. Currently, the following hypervisors are
        available:
356
357
      </para>

358
359
360
361
362
363
364
      <para>
        The <option>--prealloc-wipe-disks</option> sets a cluster wide
        configuration value for wiping disks prior to allocation. This
        increases security on instance level as the instance can't
        access untouched data from it's underlying storage.
      </para>

365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
      <para>
        <variablelist>
          <varlistentry>
            <term>xen-pvm</term>
            <listitem>
              <para>
                Xen PVM hypervisor
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>xen-hvm</term>
            <listitem>
              <para>
                Xen HVM hypervisor
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>kvm</term>
            <listitem>
              <para>
                Linux KVM hypervisor
              </para>
            </listitem>
          </varlistentry>
391
392
393
394
395
396
397
          <varlistentry>
            <term>chroot</term>
            <listitem>
              <para>
                a simple chroot manager that starts chroot based on a
                script at the root of the filesystem holding the
                chroot
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
          <varlistentry>
            <term>fake</term>
            <listitem>
              <para>
                fake hypervisor for development/testing
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>

      <para>
        Either a single hypervisor name or a comma-separated list of
        hypervisor names can be specified. If this option is not
        specified, only the xen-pvm hypervisor is enabled by default.
      </para>

415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
      <para>
        The <option>--hypervisor-parameters</option> option allows you
        to set default hypervisor specific parameters for the
        cluster. The format of this option is the name of the
        hypervisor, followed by a colon and a comma-separated list of
        key=value pairs. The keys available for each hypervisors are
        detailed in the <citerefentry>
        <refentrytitle>gnt-instance</refentrytitle>
        <manvolnum>8</manvolnum> </citerefentry> man page, in the
        <command>add</command> command plus the following parameters
        which are only configurable globally (at cluster level):

        <variablelist>
          <varlistentry>
            <term>migration_port</term>
            <listitem>
              <simpara>Valid for the Xen PVM and KVM hypervisors.</simpara>

              <para>
                This options specifies the TCP port to use for
                live-migration. For Xen, the same port should be
                configured on all nodes in
                the <filename>/etc/xen/xend-config.sxp</filename>
                file, under the
                key <quote>xend-relocation-port</quote>.
              </para>
            </listitem>
          </varlistentry>
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
          <varlistentry>
            <term>migration_bandwidth</term>
            <listitem>
              <simpara>Valid for the KVM hypervisor.</simpara>

              <para>
                This option specifies the maximum bandwidth that KVM will
                use for instance live migrations. The value is in MiB/s.
              </para>

              <simpara>This option is only effective with kvm versions >= 78
              and qemu-kvm versions >= 0.10.0.
              </simpara>
            </listitem>
          </varlistentry>
458
459
460
461
        </variablelist>

      </para>

462
      <para>
463
        The <option>--backend-parameters</option> option allows you to set
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
        the default backend parameters for the cluster. The parameter
        format is a comma-separated list of key=value pairs with the
        following supported keys:
      </para>

      <para>
        <variablelist>
          <varlistentry>
            <term>vcpus</term>
            <listitem>
              <para>
                Number of VCPUs to set for an instance by default, must
                be an integer, will be set to 1 if no specified.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>memory</term>
            <listitem>
              <para>
                Amount of memory to allocate for an instance by default,
                can be either an integer or an integer followed by a
                unit (M for mebibytes and G for gibibytes are
                supported), will be set to 128M if not specified.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>auto_balance</term>
            <listitem>
              <para>
                Value of the auto_balance flag for instances to use by
                default, will be set to true if not specified.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>

503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
      <para>
        The <option>--nic-parameters</option> option allows you to set
        the default nic parameters for the cluster. The parameter
        format is a comma-separated list of key=value pairs with the
        following supported keys:
        <variablelist>
          <varlistentry>
            <term>mode</term>
            <listitem>
              <para>
                The default nic mode, 'routed' or 'bridged'.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>link</term>
            <listitem>
              <para>
521
522
523
524
525
                In bridged mode the default NIC bridge. In routed mode it
                represents an hypervisor-vif-script dependent value to allow
                different instance groups. For example under the KVM default
                network script it is interpreted as a routing table number or
                name.
526
527
528
529
530
531
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>

532
533
534
535
536
537
538
539
540
      <para>
        The option <option>--maintain-node-health</option> allows to
        enable/disable automatic maintenance actions on
        nodes. Currently these include automatic shutdown of instances
        and deactivation of DRBD devices on offline nodes; in the
        future it might be extended to automatic removal of unknown
        LVM volumes, etc.
      </para>

541
542
543
544
545
546
547
548
549
550
551
552
      <para>
        The <option>--uid-pool</option> option initializes the user-id pool.
        The <replaceable>user-id pool definition</replaceable> can contain a
        list of user-ids and/or a list of user-id ranges. The parameter format
        is a comma-separated list of numeric user-ids or user-id ranges.
        The ranges are defined by a lower and higher boundary, separated
        by a dash. The boundaries are inclusive.
        If the <option>--uid-pool</option> option is not supplied, the
        user-id pool is initialized to an empty list. An empty list means that
        the user-id pool feature is disabled.
      </para>

553
      <para>
554
555
556
557
558
559
        The <option>-I (--default-iallocator)</option> option specifies the
        default instance allocator. The instance allocator will be used for
        operations like instance creation, instance and node migration, etc.
        when no manual override is specified. If this option is not specified,
        the default instance allocator will be blank, which means that relevant
        operations will require the administrator to manually specify either an
560
        instance allocator, or a set of nodes.
561
        The default iallocator can be changed later using the
562
563
564
        <command>modify</command> command.
      </para>

565
566
567
568
569
570
571
      <para>
        The <option>--primary-ip-version</option> option specifies the
        IP version used for the primary address. Possible values are 4 and
        6 for IPv4 and IPv6, respectively. This option is used when resolving
        node names and the cluster name.
      </para>

572
573
    </refsect2>

574
575
576
577
578
579
580
581
582
583
    <refsect2>
      <title>LIST-TAGS</title>

      <cmdsynopsis>
        <command>list-tags</command>
      </cmdsynopsis>

      <para>List the tags of the cluster.</para>
    </refsect2>

584
    <refsect2>
585
      <title>MASTER-FAILOVER</title>
586
587

      <cmdsynopsis>
588
        <command>master-failover</command>
589
        <arg>--no-voting</arg>
590
591
592
593
594
      </cmdsynopsis>

      <para>
        Failover the master role to the current node.
      </para>
595
596
597
598

      <para>
        The <option>--no-voting</option> option skips the remote node agreement
        checks. This is dangerous, but necessary in some cases (for example
599
600
601
602
603
604
605
606
        failing over the master role in a 2 node cluster with the original
        master down). If the original master then comes up, it won't be able to
        start its master daemon because it won't have enough votes, but so
        won't the new master, if the master daemon ever needs a restart. You
        can pass <option>--no-voting</option> to
        <command>ganeti-masterd</command> on the new master to solve this
        problem, and run <command>gnt-cluster redist-conf</command> to make
        sure the cluster is consistent again.
607
608
      </para>

609
610
    </refsect2>

Iustin Pop's avatar
Iustin Pop committed
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
    <refsect2>
      <title>MASTER-PING</title>

      <cmdsynopsis>
        <command>master-ping</command>
      </cmdsynopsis>

      <para>
        Checks if the master daemon is alive.
      </para>

      <para>
        If the master daemon is alive and can respond to a basic query
        (the equivalent of <command>gnt-cluster info</command>), then
        the exit code of the command will be 0. If the master daemon
        is not alive (either due to a crash or because this is not the
        master node), the exit code will be 1.
      </para>

    </refsect2>

632
633
634
635
636
    <refsect2>
      <title>MODIFY</title>

      <cmdsynopsis>
        <command>modify</command>
637
        <sbr>
638
        <arg choice="opt">--vg-name <replaceable>vg-name</replaceable></arg>
639
        <sbr>
640
        <arg choice="opt">--no-lvm-storage</arg>
641
        <sbr>
642
643
        <arg choice="opt">--enabled-hypervisors
        <replaceable>hypervisors</replaceable></arg>
644
        <sbr>
645
        <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>
646
        <sbr>
647
        <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>
648
        <sbr>
649
650
        <arg choice="opt">--nic-parameters <replaceable>nic-param</replaceable>=<replaceable>value</replaceable><arg rep="repeat" choice="opt">,<replaceable>nic-param</replaceable>=<replaceable>value</replaceable></arg></arg>
        <sbr>
651
652
653
654
655
656
        <arg choice="opt">--uid-pool <replaceable>user-id pool definition</replaceable></arg>
        <sbr>
        <arg choice="opt">--add-uids <replaceable>user-id pool definition</replaceable></arg>
        <sbr>
        <arg choice="opt">--remove-uids <replaceable>user-id pool definition</replaceable></arg>
        <sbr>
657
        <arg choice="opt">-C <replaceable>candidate_pool_size</replaceable></arg>
658
659
        <sbr>
        <arg>--maintain-node-health <group choice="req"><arg>yes</arg><arg>no</arg></group></arg>
660
        <sbr>
661
662
        <arg choice="opt">--prealloc-wipe-disks <group choice="req"><arg>yes</arg><arg>no</arg></group></arg>
        <sbr>
663
        <arg choice="opt">-I <replaceable>default instance allocator</replaceable></arg>
664

665
666
667
        <sbr>
        <arg>--reserved-lvs=<replaceable>NAMES</replaceable></arg>

668
669
670
671
672
673
674
      </cmdsynopsis>

        <para>
          Modify the options for the cluster.
        </para>

        <para>
675
          The <option>--vg-name</option>, <option>--no-lvm-storarge</option>,
676
          <option>--enabled-hypervisors</option>,
677
          <option>--hypervisor-parameters</option>,
678
679
          <option>--backend-parameters</option>,
          <option>--nic-parameters</option>,
680
          <option>--maintain-node-health</option>,
681
          <option>--prealloc-wipe-disks</option>,
682
683
          <option>--uid-pool</option> options are described in
          the <command>init</command> command.
684
        </para>
685
686

      <para>
687
        The <option>-C</option> option specifies the
688
689
690
691
692
693
694
695
696
        <varname>candidate_pool_size</varname> cluster parameter. This
        is the number of nodes that the master will try to keep as
        <literal>master_candidates</literal>. For more details about
        this role and other node roles, see the <citerefentry>
        <refentrytitle>ganeti</refentrytitle><manvolnum>7</manvolnum>
        </citerefentry>. If you increase the size, the master will
        automatically promote as many nodes as required and possible
        to reach the intended number.
      </para>
697
698
699
700
701

      <para>
        The <option>--add-uids</option> and <option>--remove-uids</option>
        options can be used to modify the user-id pool by adding/removing
        a list of user-ids or user-id ranges.
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
      </para>

      <para>
        The option <option>--reserved-lvs</option> specifies a list
        (comma-separated) of logical volume group names (regular
        expressions) that will be ignored by the cluster verify
        operation. This is useful if the volume group used for Ganeti
        is shared with the system for other uses. Note that it's not
        recommended to create and mark as ignored logical volume names
        which match Ganeti's own name format (starting with UUID and
        then <literal>.diskN</literal>), as this option only skips the
        verification, but not the actual use of the names given.
      </para>

      <para>
        To remove all reserved logical volumes, pass in an empty
        argument to the option, as in <option>--reserved-lvs=</option>
        or <option>--reserved-lvs ''</option>.
      </para>

722
723
724
725
726
727
      <para>
        The <option>-I</option> is described in
        the <command>init</command> command. To clear the default
        iallocator, just pass an empty string (<literal>''</literal>).
      </para>

728
729
    </refsect2>

730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
    <refsect2>
      <title>QUEUE</title>

      <cmdsynopsis>
        <command>queue</command>
        <arg choice="opt">drain</arg>
        <arg choice="opt">undrain</arg>
        <arg choice="opt">info</arg>

      </cmdsynopsis>

      <para>
        Change job queue properties.
      </para>

      <para>
        The <option>drain</option> option sets the drain flag on the
        job queue. No new jobs will be accepted, but jobs already in
        the queue will be processed.
      </para>

      <para>
        The <option>undrain</option> will unset the drain flag on the
        job queue. New jobs will be accepted.
      </para>

      <para>
        The <option>info</option> option shows the properties of the
        job queue.
      </para>
    </refsect2>

762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
    <refsect2>
      <title>WATCHER</title>

      <cmdsynopsis>
        <command>watcher</command>
        <group choice="req">
          <arg>pause <replaceable>duration</replaceable></arg>
          <arg>continue</arg>
          <arg>info</arg>
        </group>
      </cmdsynopsis>

      <para>
        Make the watcher pause or let it continue.
      </para>

      <para>
        The <option>pause</option> option causes the watcher to pause for
        <replaceable>duration</replaceable> seconds.
      </para>

      <para>
        The <option>continue</option> option will let the watcher continue.
      </para>

      <para>
        The <option>info</option> option shows whether the watcher is currently
        paused.
      </para>
    </refsect2>

793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
    <refsect2>
      <title>redist-conf</title>
      <cmdsynopsis>
        <command>redist-conf</command>
          <arg>--submit</arg>
      </cmdsynopsis>

      <para>
        This command forces a full push of configuration files from
        the master node to the other nodes in the cluster. This is
        normally not needed, but can be run if the
        <command>verify</command> complains about configuration
        mismatches.
      </para>

      <para>
        The <option>--submit</option> option is used to send the job
        to the master daemon but not wait for its completion. The job
        ID will be shown so that it can be examined via
        <command>gnt-job info</command>.
      </para>

    </refsect2>
816
817
818
819
820
    <refsect2>
      <title>REMOVE-TAGS</title>

      <cmdsynopsis>
        <command>remove-tags</command>
821
        <arg choice="opt">--from <replaceable>file</replaceable></arg>
822
823
824
825
826
827
828
829
        <arg choice="req"
        rep="repeat"><replaceable>tag</replaceable></arg>
      </cmdsynopsis>

      <para>
        Remove tags from the cluster. If any of the tags are not
        existing on the cluster, the entire operation will abort.
      </para>
830
831
832
833
834
835
836
837

      <para>
        If the <option>--from</option> option is given, the list of
        tags will be extended with the contents of that file (each
        line becomes a tag). In this case, there is not need to pass
        tags on the command line (if you do, both sources will be
        used). A file name of - will be interpreted as stdin.
      </para>
838
839
    </refsect2>

840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
    <refsect2>
      <title>RENAME</title>

      <cmdsynopsis>
        <command>rename</command>
        <arg>-f</arg>
        <arg choice="req"><replaceable>name</replaceable></arg>
      </cmdsynopsis>

      <para>
        Renames the cluster and in the process updates the master IP
        address to the one the new name resolves to. At least one of
        either the name or the IP address must be different, otherwise
        the operation will be aborted.
      </para>

      <para>
        Note that since this command can be dangerous (especially when
        run over SSH), the command will require confirmation unless
        run with the <option>-f</option> option.
      </para>
    </refsect2>
862

863
864
865
866
867
868
869
870
    <refsect2>
      <title>RENEW-CRYPTO</title>

      <cmdsynopsis>
        <command>renew-crypto</command>
        <arg>-f</arg>
        <sbr>
        <arg choice="opt">--new-cluster-certificate</arg>
871
        <arg choice="opt">--new-confd-hmac-key</arg>
872
873
874
        <sbr>
        <arg choice="opt">--new-rapi-certificate</arg>
        <arg choice="opt">--rapi-certificate <replaceable>rapi-cert</replaceable></arg>
Michael Hanselmann's avatar
Michael Hanselmann committed
875
876
877
        <sbr>
        <arg choice="opt">--new-cluster-domain-secret</arg>
        <arg choice="opt">--cluster-domain-secret <replaceable>filename</replaceable></arg>
878
879
880
881
882
883
884
      </cmdsynopsis>

      <para>
        This command will stop all
        Ganeti daemons in the cluster and start them again once the new
        certificates and keys are replicated. The options
        <option>--new-cluster-certificate</option> and
885
        <option>--new-confd-hmac-key</option> can be used to regenerate the
886
887
888
        cluster-internal SSL certificate respective the HMAC key used by
        <citerefentry>
        <refentrytitle>ganeti-confd</refentrytitle><manvolnum>8</manvolnum>
Michael Hanselmann's avatar
Michael Hanselmann committed
889
890
891
892
893
        </citerefentry>.
      </para>

      <para>
        To generate a new self-signed RAPI certificate (used by <citerefentry>
894
895
896
897
898
899
        <refentrytitle>ganeti-rapi</refentrytitle><manvolnum>8</manvolnum>
        </citerefentry>) specify <option>--new-rapi-certificate</option>. If
        you want to use your own certificate, e.g. one signed by a certificate
        authority (CA), pass its filename to
        <option>--rapi-certificate</option>.
      </para>
Michael Hanselmann's avatar
Michael Hanselmann committed
900
901
902
903
904
905
906

      <para>
        <option>--new-cluster-domain-secret</option> generates a new, random
        cluster domain secret. <option>--cluster-domain-secret</option> reads
        the secret from a file. The cluster domain secret is used to sign
        information exchanged between separate clusters via a third party.
      </para>
907
908
    </refsect2>

909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
    <refsect2>
      <title>REPAIR-DISK-SIZES</title>

      <cmdsynopsis>
        <command>repair-disk-sizes</command>
        <arg rep="repeat">instance</arg>
      </cmdsynopsis>

      <para>
        This command checks that the recorded size of the given
        instance's disks matches the actual size and updates any
        mismatches found. This is needed if the Ganeti configuration
        is no longer consistent with reality, as it will impact some
        disk operations. If no arguments are given, all instances will
        be checked.
      </para>

      <para>
        Note that only active disks can be checked by this command; in
        case a disk cannot be activated it's advised to use
929
930
        <command>gnt-instance activate-disks --ignore-size ...</command> to
        force activation without regard to the
931
932
933
934
935
936
937
938
939
        current size.
      </para>

      <para>
        When the all disk sizes are consistent, the command will
        return no output. Otherwise it will log details about the
        inconsistencies in the configuration.
      </para>
    </refsect2>
940

Iustin Pop's avatar
Iustin Pop committed
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
    <refsect2>
      <title>SEARCH-TAGS</title>

      <cmdsynopsis>
        <command>search-tags</command>
        <arg choice="req"><replaceable>pattern</replaceable></arg>
      </cmdsynopsis>

      <para>
        Searches the tags on all objects in the cluster (the cluster
        itself, the nodes and the instances) for a given pattern. The
        pattern is interpreted as a regular expression and a search
        will be done on it (i.e. the given pattern is not anchored to
        the beggining of the string; if you want that, prefix the
        pattern with <literal>^</literal>).
      </para>

      <para>
        If no tags are matching the pattern, the exit code of the
        command will be one. If there is at least one match, the exit
        code will be zero. Each match is listed on one line, the
        object and the tag separated by a space. The cluster will be
        listed as <filename>/cluster</filename>, a node will be listed
        as
        <filename>/nodes/<replaceable>name</replaceable></filename>,
        and an instance as
        <filename>/instances/<replaceable>name</replaceable></filename>.
        Example:
      </para>
<screen>
971
# gnt-cluster search-tags time
Iustin Pop's avatar
Iustin Pop committed
972
973
974
975
976
/cluster ctime:2007-09-01
/nodes/node1.example.com mtime:2007-10-04
</screen>
    </refsect2>

977
978
979
980
981
    <refsect2>
      <title>VERIFY</title>

      <cmdsynopsis>
        <command>verify</command>
982
        <arg choice="opt">--no-nplus1-mem</arg>
983
984
985
986
987
988
989
      </cmdsynopsis>

      <para>
        Verify correctness of cluster configuration. This is safe with
        respect to running instances, and incurs no downtime of the
        instances.
      </para>
990
991

      <para>
992
        If the <option>--no-nplus1-mem</option> option is given, Ganeti won't
993
994
995
        check whether if it loses a node it can restart all the instances on
        their secondaries (and report an error otherwise).
      </para>
996
997
    </refsect2>

998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
    <refsect2>
      <title>VERIFY-DISKS</title>

      <cmdsynopsis>
        <command>verify-disks</command>
      </cmdsynopsis>

      <para>
        The command checks which instances have degraded DRBD disks
        and activates the disks of those instances.
      </para>

      <para>
        This command is run from the <command>ganeti-watcher</command>
        tool, which also has a different, complementary algorithm for
        doing this check. Together, these two should ensure that DRBD
        disks are kept consistent.
      </para>
    </refsect2>

1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
    <refsect2>
      <title>VERSION</title>

      <cmdsynopsis>
        <command>version</command>
      </cmdsynopsis>

      <para>
        Show the cluster version.
      </para>
    </refsect2>
Iustin Pop's avatar
Iustin Pop committed
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051

  </refsect1>

  &footer;

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->