Statistics
| Branch: | Tag: | Revision:

root / man / gnt-cluster.rst @ 66d1f035

History | View | Annotate | Download (20.6 kB)

1
gnt-cluster(8) Ganeti | Version @GANETI_VERSION@
2
================================================
3

    
4
Name
5
----
6

    
7
gnt-cluster - Ganeti administration, cluster-wide
8

    
9
Synopsis
10
--------
11

    
12
**gnt-cluster** {command} [arguments...]
13

    
14
DESCRIPTION
15
-----------
16

    
17
The **gnt-cluster** is used for cluster-wide administration in the
18
Ganeti system.
19

    
20
COMMANDS
21
--------
22

    
23
ADD-TAGS
24
~~~~~~~~
25

    
26
**add-tags** [--from *file*] {*tag*...}
27

    
28
Add tags to the cluster. If any of the tags contains invalid
29
characters, the entire operation will abort.
30

    
31
If the ``--from`` option is given, the list of tags will be
32
extended with the contents of that file (each line becomes a tag).
33
In this case, there is not need to pass tags on the command line
34
(if you do, both sources will be used). A file name of - will be
35
interpreted as stdin.
36

    
37
COMMAND
38
~~~~~~~
39

    
40
**command** [-n *node*] {*command*}
41

    
42
Executes a command on all nodes. If the option ``-n`` is not given,
43
the command will be executed on all nodes, otherwise it will be
44
executed only on the node(s) specified. Use the option multiple
45
times for running it on multiple nodes, like::
46

    
47
    # gnt-cluster command -n node1.example.com -n node2.example.com date
48

    
49
The command is executed serially on the selected nodes. If the
50
master node is present in the list, the command will be executed
51
last on the master. Regarding the other nodes, the execution order
52
is somewhat alphabetic, so that node2.example.com will be earlier
53
than node10.example.com but after node1.example.com.
54

    
55
So given the node names node1, node2, node3, node10, node11, with
56
node3 being the master, the order will be: node1, node2, node10,
57
node11, node3.
58

    
59
The command is constructed by concatenating all other command line
60
arguments. For example, to list the contents of the /etc directory
61
on all nodes, run::
62

    
63
    # gnt-cluster command ls -l /etc
64

    
65
and the command which will be executed will be ``ls -l /etc``.
66

    
67
COPYFILE
68
~~~~~~~~
69

    
70
**copyfile** [--use-replication-network] [-n *node*] {*file*}
71

    
72
Copies a file to all or to some nodes. The argument specifies the
73
source file (on the current system), the ``-n`` argument specifies
74
the target node, or nodes if the option is given multiple times. If
75
``-n`` is not given at all, the file will be copied to all nodes.
76
Passing the ``--use-replication-network`` option will cause the
77
copy to be done over the replication network (only matters if the
78
primary/secondary IPs are different). Example::
79

    
80
    # gnt-cluster -n node1.example.com -n node2.example.com copyfile /tmp/test
81

    
82
This will copy the file /tmp/test from the current node to the two
83
named nodes.
84

    
85
DESTROY
86
~~~~~~~
87

    
88
**destroy** {--yes-do-it}
89

    
90
Remove all configuration files related to the cluster, so that a
91
**gnt-cluster init** can be done again afterwards.
92

    
93
Since this is a dangerous command, you are required to pass the
94
argument *--yes-do-it.*
95

    
96
EPO
97
~~~
98

    
99
**epo** [--on] [--groups|--all] *arguments*
100

    
101
Performs an emergency power-off on nodes given as arguments. If ``--groups``
102
is given, arguments are node groups. If ``--all`` is provided, the whole
103
cluster will be shut down.
104

    
105
The ``--on`` flag recovers the cluster after an emergency power-off
106

    
107
Please note that the master node will not be turned down or up automatically.
108
It will just be left in a state, where you can manully perform the shutdown of
109
that one node. If the master is in the list of affected nodes and this is not a
110
complete cluster emergency power-off (e.g. using ``--all``), you're required to
111
do a master failover to another node not affected.
112

    
113
GETMASTER
114
~~~~~~~~~
115

    
116
**getmaster**
117

    
118
Displays the current master node.
119

    
120
INFO
121
~~~~
122

    
123
**info** [--roman]
124

    
125
Shows runtime cluster information: cluster name, architecture (32
126
or 64 bit), master node, node list and instance list.
127

    
128
Passing the ``--roman`` option gnt-cluster info will try to print
129
its integer fields in a latin friendly way. This allows further
130
diffusion of Ganeti among ancient cultures.
131

    
132
INIT
133
~~~~
134

    
135
| **init**
136
| [-s *secondary\_ip*]
137
| [--vg-name *vg-name*]
138
| [--master-netdev *interface-name*]
139
| [-m *mac-prefix*]
140
| [--no-lvm-storage]
141
| [--no-etc-hosts]
142
| [--no-ssh-init]
143
| [--file-storage-dir *dir*]
144
| [--enabled-hypervisors *hypervisors*]
145
| [-t *hypervisor name*]
146
| [--hypervisor-parameters *hypervisor*:*hv-param*=*value*[,*hv-param*=*value*...]]
147
| [--backend-parameters *be-param*=*value* [,*be-param*=*value*...]]
148
| [--nic-parameters *nic-param*=*value* [,*nic-param*=*value*...]]
149
| [--maintain-node-health {yes \| no}]
150
| [--uid-pool *user-id pool definition*]
151
| [-I *default instance allocator*]
152
| [--primary-ip-version *version*]
153
| [--prealloc-wipe-disks {yes \| no}]
154
| [--node-parameters *ndparams*]
155
| {*clustername*}
156

    
157
This commands is only run once initially on the first node of the
158
cluster. It will initialize the cluster configuration, setup the
159
ssh-keys, start the daemons on the master node, etc. in order to have
160
a working one-node cluster.
161

    
162
Note that the *clustername* is not any random name. It has to be
163
resolvable to an IP address using DNS, and it is best if you give the
164
fully-qualified domain name. This hostname must resolve to an IP
165
address reserved exclusively for this purpose, i.e. not already in
166
use.
167

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

    
177
Note that for Ganeti it doesn't matter if the secondary network is
178
actually a separate physical network, or is done using tunneling,
179
etc. For performance reasons, it's recommended to use a separate
180
network, of course.
181

    
182
The ``--vg-name`` option will let you specify a volume group
183
different than "xenvg" for Ganeti to use when creating instance
184
disks. This volume group must have the same name on all nodes. Once
185
the cluster is initialized this can be altered by using the
186
**modify** command. If you don't want to use lvm storage at all use
187
the ``--no-lvm-storage`` option. Once the cluster is initialized
188
you can change this setup with the **modify** command.
189

    
190
The ``--master-netdev`` option is useful for specifying a different
191
interface on which the master will activate its IP address. It's
192
important that all nodes have this interface because you'll need it
193
for a master failover.
194

    
195
The ``-m`` option will let you specify a three byte prefix under
196
which the virtual MAC addresses of your instances will be
197
generated. The prefix must be specified in the format XX:XX:XX and
198
the default is aa:00:00.
199

    
200
The ``--no-lvm-storage`` option allows you to initialize the
201
cluster without lvm support. This means that only instances using
202
files as storage backend will be possible to create. Once the
203
cluster is initialized you can change this setup with the
204
**modify** command.
205

    
206
The ``--no-etc-hosts`` option allows you to initialize the cluster
207
without modifying the /etc/hosts file.
208

    
209
The ``--no-ssh-init`` option allows you to initialize the cluster
210
without creating or distributing SSH key pairs.
211

    
212
The ``--file-storage-dir`` option allows you set the directory to
213
use for storing the instance disk files when using file storage as
214
backend for instance disks.
215

    
216
The ``--enabled-hypervisors`` option allows you to set the list of
217
hypervisors that will be enabled for this cluster. Instance
218
hypervisors can only be chosen from the list of enabled
219
hypervisors, and the first entry of this list will be used by
220
default. Currently, the following hypervisors are available:
221

    
222
The ``--prealloc-wipe-disks`` sets a cluster wide configuration
223
value for wiping disks prior to allocation. This increases security
224
on instance level as the instance can't access untouched data from
225
it's underlying storage.
226

    
227

    
228

    
229

    
230

    
231
xen-pvm
232
    Xen PVM hypervisor
233

    
234
xen-hvm
235
    Xen HVM hypervisor
236

    
237
kvm
238
    Linux KVM hypervisor
239

    
240
chroot
241
    a simple chroot manager that starts chroot based on a script at the
242
    root of the filesystem holding the chroot
243

    
244
fake
245
    fake hypervisor for development/testing
246

    
247

    
248
Either a single hypervisor name or a comma-separated list of
249
hypervisor names can be specified. If this option is not specified,
250
only the xen-pvm hypervisor is enabled by default.
251

    
252
The ``--hypervisor-parameters`` option allows you to set default
253
hypervisor specific parameters for the cluster. The format of this
254
option is the name of the hypervisor, followed by a colon and a
255
comma-separated list of key=value pairs. The keys available for
256
each hypervisors are detailed in the gnt-instance(8) man page, in
257
the **add** command plus the following parameters which are only
258
configurable globally (at cluster level):
259

    
260
migration\_port
261
    Valid for the Xen PVM and KVM hypervisors.
262

    
263
    This options specifies the TCP port to use for live-migration. For
264
    Xen, the same port should be configured on all nodes in the
265
    ``/etc/xen/xend-config.sxp`` file, under the key
266
    "xend-relocation-port".
267

    
268
migration\_bandwidth
269
    Valid for the KVM hypervisor.
270

    
271
    This option specifies the maximum bandwidth that KVM will use for
272
    instance live migrations. The value is in MiB/s.
273

    
274
    This option is only effective with kvm versions >= 78 and qemu-kvm
275
    versions >= 0.10.0.
276

    
277

    
278
The ``--backend-parameters`` option allows you to set the default
279
backend parameters for the cluster. The parameter format is a
280
comma-separated list of key=value pairs with the following
281
supported keys:
282

    
283
vcpus
284
    Number of VCPUs to set for an instance by default, must be an
285
    integer, will be set to 1 if no specified.
286

    
287
memory
288
    Amount of memory to allocate for an instance by default, can be
289
    either an integer or an integer followed by a unit (M for mebibytes
290
    and G for gibibytes are supported), will be set to 128M if not
291
    specified.
292

    
293
auto\_balance
294
    Value of the auto\_balance flag for instances to use by default,
295
    will be set to true if not specified.
296

    
297

    
298
The ``--nic-parameters`` option allows you to set the default nic
299
parameters for the cluster. The parameter format is a
300
comma-separated list of key=value pairs with the following
301
supported keys:
302

    
303
mode
304
    The default nic mode, 'routed' or 'bridged'.
305

    
306
link
307
    In bridged mode the default NIC bridge. In routed mode it
308
    represents an hypervisor-vif-script dependent value to allow
309
    different instance groups. For example under the KVM default
310
    network script it is interpreted as a routing table number or
311
    name.
312

    
313

    
314
The option ``--maintain-node-health`` allows to enable/disable
315
automatic maintenance actions on nodes. Currently these include
316
automatic shutdown of instances and deactivation of DRBD devices on
317
offline nodes; in the future it might be extended to automatic
318
removal of unknown LVM volumes, etc.
319

    
320
The ``--uid-pool`` option initializes the user-id pool. The
321
*user-id pool definition* can contain a list of user-ids and/or a
322
list of user-id ranges. The parameter format is a comma-separated
323
list of numeric user-ids or user-id ranges. The ranges are defined
324
by a lower and higher boundary, separated by a dash. The boundaries
325
are inclusive. If the ``--uid-pool`` option is not supplied, the
326
user-id pool is initialized to an empty list. An empty list means
327
that the user-id pool feature is disabled.
328

    
329
The ``-I (--default-iallocator)`` option specifies the default
330
instance allocator. The instance allocator will be used for
331
operations like instance creation, instance and node migration,
332
etc. when no manual override is specified. If this option is not
333
specified, the default instance allocator will be blank, which
334
means that relevant operations will require the administrator to
335
manually specify either an instance allocator, or a set of nodes.
336
The default iallocator can be changed later using the **modify**
337
command.
338

    
339
The ``--primary-ip-version`` option specifies the IP version used
340
for the primary address. Possible values are 4 and 6 for IPv4 and
341
IPv6, respectively. This option is used when resolving node names
342
and the cluster name.
343

    
344
The ``--node-parameters`` option allows you to set default node
345
parameters for the cluster. Please see **ganeti**(7) for more
346
information about supported key=value pairs.
347

    
348
LIST-TAGS
349
~~~~~~~~~
350

    
351
**list-tags**
352

    
353
List the tags of the cluster.
354

    
355
MASTER-FAILOVER
356
~~~~~~~~~~~~~~~
357

    
358
**master-failover** [--no-voting]
359

    
360
Failover the master role to the current node.
361

    
362
The ``--no-voting`` option skips the remote node agreement checks.
363
This is dangerous, but necessary in some cases (for example failing
364
over the master role in a 2 node cluster with the original master
365
down). If the original master then comes up, it won't be able to
366
start its master daemon because it won't have enough votes, but so
367
won't the new master, if the master daemon ever needs a restart.
368
You can pass ``--no-voting`` to **ganeti-masterd** on the new
369
master to solve this problem, and run **gnt-cluster redist-conf**
370
to make sure the cluster is consistent again.
371

    
372
MASTER-PING
373
~~~~~~~~~~~
374

    
375
**master-ping**
376

    
377
Checks if the master daemon is alive.
378

    
379
If the master daemon is alive and can respond to a basic query (the
380
equivalent of **gnt-cluster info**), then the exit code of the
381
command will be 0. If the master daemon is not alive (either due to
382
a crash or because this is not the master node), the exit code will
383
be 1.
384

    
385
MODIFY
386
~~~~~~
387

    
388
| **modify**
389
| [--vg-name *vg-name*]
390
| [--no-lvm-storage]
391
| [--enabled-hypervisors *hypervisors*]
392
| [--hypervisor-parameters *hypervisor*:*hv-param*=*value*[,*hv-param*=*value*...]]
393
| [--backend-parameters *be-param*=*value* [,*be-param*=*value*...]]
394
| [--nic-parameters *nic-param*=*value* [,*nic-param*=*value*...]]
395
| [--uid-pool *user-id pool definition*]
396
| [--add-uids *user-id pool definition*]
397
| [--remove-uids *user-id pool definition*]
398
| [-C *candidate\_pool\_size*]
399
| [--maintain-node-health {yes \| no}]
400
| [--prealloc-wipe-disks {yes \| no}]
401
| [-I *default instance allocator*]
402
| [--reserved-lvs=*NAMES*]
403
| [--node-parameters *ndparams*]
404
| [--master-netdev *interface-name*]
405

    
406
Modify the options for the cluster.
407

    
408
The ``--vg-name``, ``--no-lvm-storarge``, ``--enabled-hypervisors``,
409
``--hypervisor-parameters``, ``--backend-parameters``,
410
``--nic-parameters``, ``--maintain-node-health``,
411
``--prealloc-wipe-disks``, ``--uid-pool``, ``--node-parameters``,
412
``--master-netdev`` options are described in the **init** command.
413

    
414
The ``-C`` option specifies the ``candidate_pool_size`` cluster
415
parameter. This is the number of nodes that the master will try to
416
keep as master\_candidates. For more details about this role and
417
other node roles, see the ganeti(7). If you increase the size, the
418
master will automatically promote as many nodes as required and
419
possible to reach the intended number.
420

    
421
The ``--add-uids`` and ``--remove-uids`` options can be used to
422
modify the user-id pool by adding/removing a list of user-ids or
423
user-id ranges.
424

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

    
434
To remove all reserved logical volumes, pass in an empty argument
435
to the option, as in ``--reserved-lvs=`` or ``--reserved-lvs ''``.
436

    
437
The ``-I`` is described in the **init** command. To clear the
438
default iallocator, just pass an empty string ('').
439

    
440
QUEUE
441
~~~~~
442

    
443
**queue** {drain | undrain | info}
444

    
445
Change job queue properties.
446

    
447
The ``drain`` option sets the drain flag on the job queue. No new
448
jobs will be accepted, but jobs already in the queue will be
449
processed.
450

    
451
The ``undrain`` will unset the drain flag on the job queue. New
452
jobs will be accepted.
453

    
454
The ``info`` option shows the properties of the job queue.
455

    
456
WATCHER
457
~~~~~~~
458

    
459
**watcher** {pause *duration* | continue | info}
460

    
461
Make the watcher pause or let it continue.
462

    
463
The ``pause`` option causes the watcher to pause for *duration*
464
seconds.
465

    
466
The ``continue`` option will let the watcher continue.
467

    
468
The ``info`` option shows whether the watcher is currently paused.
469

    
470
redist-conf
471
~~~~~~~~~~~
472

    
473
**redist-conf** [--submit]
474

    
475
This command forces a full push of configuration files from the
476
master node to the other nodes in the cluster. This is normally not
477
needed, but can be run if the **verify** complains about
478
configuration mismatches.
479

    
480
The ``--submit`` option is used to send the job to the master
481
daemon but not wait for its completion. The job ID will be shown so
482
that it can be examined via **gnt-job info**.
483

    
484
REMOVE-TAGS
485
~~~~~~~~~~~
486

    
487
**remove-tags** [--from *file*] {*tag*...}
488

    
489
Remove tags from the cluster. If any of the tags are not existing
490
on the cluster, the entire operation will abort.
491

    
492
If the ``--from`` option is given, the list of tags to be removed will
493
be extended with the contents of that file (each line becomes a tag).
494
In this case, there is not need to pass tags on the command line (if
495
you do, tags from both sources will be removed). A file name of - will
496
be interpreted as stdin.
497

    
498
RENAME
499
~~~~~~
500

    
501
**rename** [-f] {*name*}
502

    
503
Renames the cluster and in the process updates the master IP
504
address to the one the new name resolves to. At least one of either
505
the name or the IP address must be different, otherwise the
506
operation will be aborted.
507

    
508
Note that since this command can be dangerous (especially when run
509
over SSH), the command will require confirmation unless run with
510
the ``-f`` option.
511

    
512
RENEW-CRYPTO
513
~~~~~~~~~~~~
514

    
515
| **renew-crypto** [-f]
516
| [--new-cluster-certificate] [--new-confd-hmac-key]
517
| [--new-rapi-certificate] [--rapi-certificate *rapi-cert*]
518
| [--new-cluster-domain-secret] [--cluster-domain-secret *filename*]
519

    
520
This command will stop all Ganeti daemons in the cluster and start
521
them again once the new certificates and keys are replicated. The
522
options ``--new-cluster-certificate`` and ``--new-confd-hmac-key``
523
can be used to regenerate the cluster-internal SSL certificate
524
respective the HMAC key used by ganeti-confd(8).
525

    
526
To generate a new self-signed RAPI certificate (used by
527
ganeti-rapi(8)) specify ``--new-rapi-certificate``. If you want to
528
use your own certificate, e.g. one signed by a certificate
529
authority (CA), pass its filename to ``--rapi-certificate``.
530

    
531
``--new-cluster-domain-secret`` generates a new, random cluster
532
domain secret. ``--cluster-domain-secret`` reads the secret from a
533
file. The cluster domain secret is used to sign information
534
exchanged between separate clusters via a third party.
535

    
536
REPAIR-DISK-SIZES
537
~~~~~~~~~~~~~~~~~
538

    
539
**repair-disk-sizes** [instance...]
540

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

    
547
Note that only active disks can be checked by this command; in case
548
a disk cannot be activated it's advised to use
549
**gnt-instance activate-disks --ignore-size ...** to force
550
activation without regard to the current size.
551

    
552
When the all disk sizes are consistent, the command will return no
553
output. Otherwise it will log details about the inconsistencies in
554
the configuration.
555

    
556
SEARCH-TAGS
557
~~~~~~~~~~~
558

    
559
**search-tags** {*pattern*}
560

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

    
567
If no tags are matching the pattern, the exit code of the command
568
will be one. If there is at least one match, the exit code will be
569
zero. Each match is listed on one line, the object and the tag
570
separated by a space. The cluster will be listed as /cluster, a
571
node will be listed as /nodes/*name*, and an instance as
572
/instances/*name*. Example:
573

    
574
::
575

    
576
    # gnt-cluster search-tags time
577
    /cluster ctime:2007-09-01
578
    /nodes/node1.example.com mtime:2007-10-04
579

    
580
VERIFY
581
~~~~~~
582

    
583
**verify** [--no-nplus1-mem]
584

    
585
Verify correctness of cluster configuration. This is safe with
586
respect to running instances, and incurs no downtime of the
587
instances.
588

    
589
If the ``--no-nplus1-mem`` option is given, Ganeti won't check
590
whether if it loses a node it can restart all the instances on
591
their secondaries (and report an error otherwise).
592

    
593
VERIFY-DISKS
594
~~~~~~~~~~~~
595

    
596
**verify-disks**
597

    
598
The command checks which instances have degraded DRBD disks and
599
activates the disks of those instances.
600

    
601
This command is run from the **ganeti-watcher** tool, which also
602
has a different, complementary algorithm for doing this check.
603
Together, these two should ensure that DRBD disks are kept
604
consistent.
605

    
606
VERSION
607
~~~~~~~
608

    
609
**version**
610

    
611
Show the cluster version.