Statistics
| Branch: | Tag: | Revision:

root / man / gnt-cluster.rst @ 6204ee71

History | View | Annotate | Download (19.9 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
GETMASTER
97
~~~~~~~~~
98

    
99
**getmaster**
100

    
101
Displays the current master node.
102

    
103
INFO
104
~~~~
105

    
106
**info** [--roman]
107

    
108
Shows runtime cluster information: cluster name, architecture (32
109
or 64 bit), master node, node list and instance list.
110

    
111
Passing the ``--roman`` option gnt-cluster info will try to print
112
its integer fields in a latin friendly way. This allows further
113
diffusion of Ganeti among ancient cultures.
114

    
115
INIT
116
~~~~
117

    
118
| **init**
119
| [-s *secondary\_ip*]
120
| [--vg-name *vg-name*]
121
| [--master-netdev *interface-name*]
122
| [-m *mac-prefix*]
123
| [--no-lvm-storage]
124
| [--no-etc-hosts]
125
| [--no-ssh-init]
126
| [--file-storage-dir *dir*]
127
| [--enabled-hypervisors *hypervisors*]
128
| [-t *hypervisor name*]
129
| [--hypervisor-parameters *hypervisor*:*hv-param*=*value*[,*hv-param*=*value*...]]
130
| [--backend-parameters *be-param*=*value* [,*be-param*=*value*...]]
131
| [--nic-parameters *nic-param*=*value* [,*nic-param*=*value*...]]
132
| [--maintain-node-health {yes \| no}]
133
| [--uid-pool *user-id pool definition*]
134
| [-I *default instance allocator*]
135
| [--primary-ip-version *version*]
136
| [--prealloc-wipe-disks {yes \| no}]
137
| [--node-parameters *ndparams*]
138
| {*clustername*}
139

    
140
This commands is only run once initially on the first node of the
141
cluster. It will initialize the cluster configuration, setup the
142
ssh-keys, start the daemons on the master node, etc. in order to have
143
a working one-node cluster.
144

    
145
Note that the *clustername* is not any random name. It has to be
146
resolvable to an IP address using DNS, and it is best if you give the
147
fully-qualified domain name. This hostname must resolve to an IP
148
address reserved exclusively for this purpose, i.e. not already in
149
use.
150

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

    
160
Note that for Ganeti it doesn't matter if the secondary network is
161
actually a separate physical network, or is done using tunneling,
162
etc. For performance reasons, it's recommended to use a separate
163
network, of course.
164

    
165
The ``--vg-name`` option will let you specify a volume group
166
different than "xenvg" for Ganeti to use when creating instance
167
disks. This volume group must have the same name on all nodes. Once
168
the cluster is initialized this can be altered by using the
169
**modify** command. If you don't want to use lvm storage at all use
170
the ``--no-lvm-storage`` option. Once the cluster is initialized
171
you can change this setup with the **modify** command.
172

    
173
The ``--master-netdev`` option is useful for specifying a different
174
interface on which the master will activate its IP address. It's
175
important that all nodes have this interface because you'll need it
176
for a master failover.
177

    
178
The ``-m`` option will let you specify a three byte prefix under
179
which the virtual MAC addresses of your instances will be
180
generated. The prefix must be specified in the format XX:XX:XX and
181
the default is aa:00:00.
182

    
183
The ``--no-lvm-storage`` option allows you to initialize the
184
cluster without lvm support. This means that only instances using
185
files as storage backend will be possible to create. Once the
186
cluster is initialized you can change this setup with the
187
**modify** command.
188

    
189
The ``--no-etc-hosts`` option allows you to initialize the cluster
190
without modifying the /etc/hosts file.
191

    
192
The ``--no-ssh-init`` option allows you to initialize the cluster
193
without creating or distributing SSH key pairs.
194

    
195
The ``--file-storage-dir`` option allows you set the directory to
196
use for storing the instance disk files when using file storage as
197
backend for instance disks.
198

    
199
The ``--enabled-hypervisors`` option allows you to set the list of
200
hypervisors that will be enabled for this cluster. Instance
201
hypervisors can only be chosen from the list of enabled
202
hypervisors, and the first entry of this list will be used by
203
default. Currently, the following hypervisors are available:
204

    
205
The ``--prealloc-wipe-disks`` sets a cluster wide configuration
206
value for wiping disks prior to allocation. This increases security
207
on instance level as the instance can't access untouched data from
208
it's underlying storage.
209

    
210

    
211

    
212

    
213

    
214
xen-pvm
215
    Xen PVM hypervisor
216

    
217
xen-hvm
218
    Xen HVM hypervisor
219

    
220
kvm
221
    Linux KVM hypervisor
222

    
223
chroot
224
    a simple chroot manager that starts chroot based on a script at the
225
    root of the filesystem holding the chroot
226

    
227
fake
228
    fake hypervisor for development/testing
229

    
230

    
231
Either a single hypervisor name or a comma-separated list of
232
hypervisor names can be specified. If this option is not specified,
233
only the xen-pvm hypervisor is enabled by default.
234

    
235
The ``--hypervisor-parameters`` option allows you to set default
236
hypervisor specific parameters for the cluster. The format of this
237
option is the name of the hypervisor, followed by a colon and a
238
comma-separated list of key=value pairs. The keys available for
239
each hypervisors are detailed in the gnt-instance(8) man page, in
240
the **add** command plus the following parameters which are only
241
configurable globally (at cluster level):
242

    
243
migration\_port
244
    Valid for the Xen PVM and KVM hypervisors.
245

    
246
    This options specifies the TCP port to use for live-migration. For
247
    Xen, the same port should be configured on all nodes in the
248
    ``/etc/xen/xend-config.sxp`` file, under the key
249
    "xend-relocation-port".
250

    
251
migration\_bandwidth
252
    Valid for the KVM hypervisor.
253

    
254
    This option specifies the maximum bandwidth that KVM will use for
255
    instance live migrations. The value is in MiB/s.
256

    
257
    This option is only effective with kvm versions >= 78 and qemu-kvm
258
    versions >= 0.10.0.
259

    
260

    
261
The ``--backend-parameters`` option allows you to set the default
262
backend parameters for the cluster. The parameter format is a
263
comma-separated list of key=value pairs with the following
264
supported keys:
265

    
266
vcpus
267
    Number of VCPUs to set for an instance by default, must be an
268
    integer, will be set to 1 if no specified.
269

    
270
memory
271
    Amount of memory to allocate for an instance by default, can be
272
    either an integer or an integer followed by a unit (M for mebibytes
273
    and G for gibibytes are supported), will be set to 128M if not
274
    specified.
275

    
276
auto\_balance
277
    Value of the auto\_balance flag for instances to use by default,
278
    will be set to true if not specified.
279

    
280

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

    
286
mode
287
    The default nic mode, 'routed' or 'bridged'.
288

    
289
link
290
    In bridged mode the default NIC bridge. In routed mode it
291
    represents an hypervisor-vif-script dependent value to allow
292
    different instance groups. For example under the KVM default
293
    network script it is interpreted as a routing table number or
294
    name.
295

    
296

    
297
The option ``--maintain-node-health`` allows to enable/disable
298
automatic maintenance actions on nodes. Currently these include
299
automatic shutdown of instances and deactivation of DRBD devices on
300
offline nodes; in the future it might be extended to automatic
301
removal of unknown LVM volumes, etc.
302

    
303
The ``--uid-pool`` option initializes the user-id pool. The
304
*user-id pool definition* can contain a list of user-ids and/or a
305
list of user-id ranges. The parameter format is a comma-separated
306
list of numeric user-ids or user-id ranges. The ranges are defined
307
by a lower and higher boundary, separated by a dash. The boundaries
308
are inclusive. If the ``--uid-pool`` option is not supplied, the
309
user-id pool is initialized to an empty list. An empty list means
310
that the user-id pool feature is disabled.
311

    
312
The ``-I (--default-iallocator)`` option specifies the default
313
instance allocator. The instance allocator will be used for
314
operations like instance creation, instance and node migration,
315
etc. when no manual override is specified. If this option is not
316
specified, the default instance allocator will be blank, which
317
means that relevant operations will require the administrator to
318
manually specify either an instance allocator, or a set of nodes.
319
The default iallocator can be changed later using the **modify**
320
command.
321

    
322
The ``--primary-ip-version`` option specifies the IP version used
323
for the primary address. Possible values are 4 and 6 for IPv4 and
324
IPv6, respectively. This option is used when resolving node names
325
and the cluster name.
326

    
327
The ``--node-parameters`` option allows you to set default node
328
parameters for the cluster. Please see **ganeti**(7) for more
329
information about supported key=value pairs.
330

    
331
LIST-TAGS
332
~~~~~~~~~
333

    
334
**list-tags**
335

    
336
List the tags of the cluster.
337

    
338
MASTER-FAILOVER
339
~~~~~~~~~~~~~~~
340

    
341
**master-failover** [--no-voting]
342

    
343
Failover the master role to the current node.
344

    
345
The ``--no-voting`` option skips the remote node agreement checks.
346
This is dangerous, but necessary in some cases (for example failing
347
over the master role in a 2 node cluster with the original master
348
down). If the original master then comes up, it won't be able to
349
start its master daemon because it won't have enough votes, but so
350
won't the new master, if the master daemon ever needs a restart.
351
You can pass ``--no-voting`` to **ganeti-masterd** on the new
352
master to solve this problem, and run **gnt-cluster redist-conf**
353
to make sure the cluster is consistent again.
354

    
355
MASTER-PING
356
~~~~~~~~~~~
357

    
358
**master-ping**
359

    
360
Checks if the master daemon is alive.
361

    
362
If the master daemon is alive and can respond to a basic query (the
363
equivalent of **gnt-cluster info**), then the exit code of the
364
command will be 0. If the master daemon is not alive (either due to
365
a crash or because this is not the master node), the exit code will
366
be 1.
367

    
368
MODIFY
369
~~~~~~
370

    
371
| **modify**
372
| [--vg-name *vg-name*]
373
| [--no-lvm-storage]
374
| [--enabled-hypervisors *hypervisors*]
375
| [--hypervisor-parameters *hypervisor*:*hv-param*=*value*[,*hv-param*=*value*...]]
376
| [--backend-parameters *be-param*=*value* [,*be-param*=*value*...]]
377
| [--nic-parameters *nic-param*=*value* [,*nic-param*=*value*...]]
378
| [--uid-pool *user-id pool definition*]
379
| [--add-uids *user-id pool definition*]
380
| [--remove-uids *user-id pool definition*]
381
| [-C *candidate\_pool\_size*]
382
| [--maintain-node-health {yes \| no}]
383
| [--prealloc-wipe-disks {yes \| no}]
384
| [-I *default instance allocator*]
385
| [--reserved-lvs=*NAMES*]
386
| [--node-parameters *ndparams*]
387

    
388
Modify the options for the cluster.
389

    
390
The ``--vg-name``, ``--no-lvm-storarge``, ``--enabled-hypervisors``,
391
``--hypervisor-parameters``, ``--backend-parameters``,
392
``--nic-parameters``, ``--maintain-node-health``,
393
``--prealloc-wipe-disks``, ``--uid-pool``, ``--node-parameters`` options
394
are described in the **init** command.
395

    
396
The ``-C`` option specifies the ``candidate_pool_size`` cluster
397
parameter. This is the number of nodes that the master will try to
398
keep as master\_candidates. For more details about this role and
399
other node roles, see the ganeti(7). If you increase the size, the
400
master will automatically promote as many nodes as required and
401
possible to reach the intended number.
402

    
403
The ``--add-uids`` and ``--remove-uids`` options can be used to
404
modify the user-id pool by adding/removing a list of user-ids or
405
user-id ranges.
406

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

    
416
To remove all reserved logical volumes, pass in an empty argument
417
to the option, as in ``--reserved-lvs=`` or ``--reserved-lvs ''``.
418

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

    
422
QUEUE
423
~~~~~
424

    
425
**queue** {drain | undrain | info}
426

    
427
Change job queue properties.
428

    
429
The ``drain`` option sets the drain flag on the job queue. No new
430
jobs will be accepted, but jobs already in the queue will be
431
processed.
432

    
433
The ``undrain`` will unset the drain flag on the job queue. New
434
jobs will be accepted.
435

    
436
The ``info`` option shows the properties of the job queue.
437

    
438
WATCHER
439
~~~~~~~
440

    
441
**watcher** {pause *duration* | continue | info}
442

    
443
Make the watcher pause or let it continue.
444

    
445
The ``pause`` option causes the watcher to pause for *duration*
446
seconds.
447

    
448
The ``continue`` option will let the watcher continue.
449

    
450
The ``info`` option shows whether the watcher is currently paused.
451

    
452
redist-conf
453
~~~~~~~~~~~
454

    
455
**redist-conf** [--submit]
456

    
457
This command forces a full push of configuration files from the
458
master node to the other nodes in the cluster. This is normally not
459
needed, but can be run if the **verify** complains about
460
configuration mismatches.
461

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

    
466
REMOVE-TAGS
467
~~~~~~~~~~~
468

    
469
**remove-tags** [--from *file*] {*tag*...}
470

    
471
Remove tags from the cluster. If any of the tags are not existing
472
on the cluster, the entire operation will abort.
473

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

    
480
RENAME
481
~~~~~~
482

    
483
**rename** [-f] {*name*}
484

    
485
Renames the cluster and in the process updates the master IP
486
address to the one the new name resolves to. At least one of either
487
the name or the IP address must be different, otherwise the
488
operation will be aborted.
489

    
490
Note that since this command can be dangerous (especially when run
491
over SSH), the command will require confirmation unless run with
492
the ``-f`` option.
493

    
494
RENEW-CRYPTO
495
~~~~~~~~~~~~
496

    
497
| **renew-crypto** [-f]
498
| [--new-cluster-certificate] [--new-confd-hmac-key]
499
| [--new-rapi-certificate] [--rapi-certificate *rapi-cert*]
500
| [--new-cluster-domain-secret] [--cluster-domain-secret *filename*]
501

    
502
This command will stop all Ganeti daemons in the cluster and start
503
them again once the new certificates and keys are replicated. The
504
options ``--new-cluster-certificate`` and ``--new-confd-hmac-key``
505
can be used to regenerate the cluster-internal SSL certificate
506
respective the HMAC key used by ganeti-confd(8).
507

    
508
To generate a new self-signed RAPI certificate (used by
509
ganeti-rapi(8)) specify ``--new-rapi-certificate``. If you want to
510
use your own certificate, e.g. one signed by a certificate
511
authority (CA), pass its filename to ``--rapi-certificate``.
512

    
513
``--new-cluster-domain-secret`` generates a new, random cluster
514
domain secret. ``--cluster-domain-secret`` reads the secret from a
515
file. The cluster domain secret is used to sign information
516
exchanged between separate clusters via a third party.
517

    
518
REPAIR-DISK-SIZES
519
~~~~~~~~~~~~~~~~~
520

    
521
**repair-disk-sizes** [instance...]
522

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

    
529
Note that only active disks can be checked by this command; in case
530
a disk cannot be activated it's advised to use
531
**gnt-instance activate-disks --ignore-size ...** to force
532
activation without regard to the current size.
533

    
534
When the all disk sizes are consistent, the command will return no
535
output. Otherwise it will log details about the inconsistencies in
536
the configuration.
537

    
538
SEARCH-TAGS
539
~~~~~~~~~~~
540

    
541
**search-tags** {*pattern*}
542

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

    
549
If no tags are matching the pattern, the exit code of the command
550
will be one. If there is at least one match, the exit code will be
551
zero. Each match is listed on one line, the object and the tag
552
separated by a space. The cluster will be listed as /cluster, a
553
node will be listed as /nodes/*name*, and an instance as
554
/instances/*name*. Example:
555

    
556
::
557

    
558
    # gnt-cluster search-tags time
559
    /cluster ctime:2007-09-01
560
    /nodes/node1.example.com mtime:2007-10-04
561

    
562
VERIFY
563
~~~~~~
564

    
565
**verify** [--no-nplus1-mem]
566

    
567
Verify correctness of cluster configuration. This is safe with
568
respect to running instances, and incurs no downtime of the
569
instances.
570

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

    
575
VERIFY-DISKS
576
~~~~~~~~~~~~
577

    
578
**verify-disks**
579

    
580
The command checks which instances have degraded DRBD disks and
581
activates the disks of those instances.
582

    
583
This command is run from the **ganeti-watcher** tool, which also
584
has a different, complementary algorithm for doing this check.
585
Together, these two should ensure that DRBD disks are kept
586
consistent.
587

    
588
VERSION
589
~~~~~~~
590

    
591
**version**
592

    
593
Show the cluster version.