e77bb9bff7c7001b4af28a041b4c6a3049f18120
[ganeti-github.git] / man / gnt-cluster.rst
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 ACTIVATE-MASTER-IP
24 ~~~~~~~~~~~~~~~~~~
25
26 **activate-master-ip**
27
28 Activates the master IP on the master node.
29
30 COMMAND
31 ~~~~~~~
32
33 **command** [-n *node*] [-g *group*] [-M] {*command*}
34
35 Executes a command on all nodes. This command is designed for simple
36 usage. For more complex use cases the commands **dsh**\(1) or **cssh**\(1)
37 should be used instead.
38
39 If the option ``-n`` is not given, the command will be executed on all
40 nodes, otherwise it will be executed only on the node(s) specified. Use
41 the option multiple times for running it on multiple nodes, like::
42
43     # gnt-cluster command -n node1.example.com -n node2.example.com date
44
45 The ``-g`` option can be used to run a command only on a specific node
46 group, e.g.::
47
48     # gnt-cluster command -g default date
49
50 The ``-M`` option can be used to prepend the node name to all output
51 lines. The ``--failure-only`` option hides successful commands, making
52 it easier to see failures.
53
54 The command is executed serially on the selected nodes. If the
55 master node is present in the list, the command will be executed
56 last on the master. Regarding the other nodes, the execution order
57 is somewhat alphabetic, so that node2.example.com will be earlier
58 than node10.example.com but after node1.example.com.
59
60 So given the node names node1, node2, node3, node10, node11, with
61 node3 being the master, the order will be: node1, node2, node10,
62 node11, node3.
63
64 The command is constructed by concatenating all other command line
65 arguments. For example, to list the contents of the /etc directory
66 on all nodes, run::
67
68     # gnt-cluster command ls -l /etc
69
70 and the command which will be executed will be ``ls -l /etc``.
71
72 COPYFILE
73 ~~~~~~~~
74
75 | **copyfile** [\--use-replication-network] [-n *node*] [-g *group*]
76 | {*file*}
77
78 Copies a file to all or to some nodes. The argument specifies the
79 source file (on the current system), the ``-n`` argument specifies
80 the target node, or nodes if the option is given multiple times. If
81 ``-n`` is not given at all, the file will be copied to all nodes. The
82 ``-g`` option can be used to only select nodes in a specific node group.
83 Passing the ``--use-replication-network`` option will cause the
84 copy to be done over the replication network (only matters if the
85 primary/secondary IPs are different). Example::
86
87     # gnt-cluster copyfile -n node1.example.com -n node2.example.com /tmp/test
88
89 This will copy the file /tmp/test from the current node to the two
90 named nodes.
91
92 DEACTIVATE-MASTER-IP
93 ~~~~~~~~~~~~~~~~~~~~
94
95 **deactivate-master-ip** [\--yes]
96
97 Deactivates the master IP on the master node.
98
99 This should be run only locally or on a connection to the node ip
100 directly, as a connection to the master ip will be broken by this
101 operation. Because of this risk it will require user confirmation
102 unless the ``--yes`` option is passed.
103
104 DESTROY
105 ~~~~~~~
106
107 **destroy** {\--yes-do-it}
108
109 Remove all configuration files related to the cluster, so that a
110 **gnt-cluster init** can be done again afterwards.
111
112 Since this is a dangerous command, you are required to pass the
113 argument *\--yes-do-it.*
114
115 EPO
116 ~~~
117
118 **epo** [\--on] [\--groups|\--all] [\--power-delay] *arguments*
119
120 Performs an emergency power-off on nodes given as arguments. If
121 ``--groups`` is given, arguments are node groups. If ``--all`` is
122 provided, the whole cluster will be shut down.
123
124 The ``--on`` flag recovers the cluster after an emergency power-off.
125 When powering on the cluster you can use ``--power-delay`` to define the
126 time in seconds (fractions allowed) waited between powering on
127 individual nodes.
128
129 Please note that the master node will not be turned down or up
130 automatically.  It will just be left in a state, where you can manully
131 perform the shutdown of that one node. If the master is in the list of
132 affected nodes and this is not a complete cluster emergency power-off
133 (e.g. using ``--all``), you're required to do a master failover to
134 another node not affected.
135
136 GETMASTER
137 ~~~~~~~~~
138
139 **getmaster**
140
141 Displays the current master node.
142
143 INFO
144 ~~~~
145
146 **info** [\--roman]
147
148 Shows runtime cluster information: cluster name, architecture (32
149 or 64 bit), master node, node list and instance list.
150
151 Passing the ``--roman`` option gnt-cluster info will try to print
152 its integer fields in a latin friendly way. This allows further
153 diffusion of Ganeti among ancient cultures.
154
155 SHOW-ISPECS-CMD
156 ~~~~~~~~~~~~~~~
157
158 **show-ispecs-cmd**
159
160 Shows the command line that can be used to recreate the cluster with the
161 same options relative to specs in the instance policies.
162
163 INIT
164 ~~~~
165
166 | **init**
167 | [{-s|\--secondary-ip} *secondary\_ip*]
168 | [\--vg-name *vg-name*]
169 | [\--master-netdev *interface-name*]
170 | [\--master-netmask *netmask*]
171 | [\--use-external-mip-script {yes \| no}]
172 | [{-m|\--mac-prefix} *mac-prefix*]
173 | [\--no-etc-hosts]
174 | [\--no-ssh-init]
175 | [\--file-storage-dir *dir*]
176 | [\--shared-file-storage-dir *dir*]
177 | [\--gluster-storage-dir *dir*]
178 | [\--enabled-hypervisors *hypervisors*]
179 | [{-H|\--hypervisor-parameters} *hypervisor*:*hv-param*=*value*[,*hv-param*=*value*...]]
180 | [{-B|\--backend-parameters} *be-param*=*value*[,*be-param*=*value*...]]
181 | [{-N|\--nic-parameters} *nic-param*=*value*[,*nic-param*=*value*...]]
182 | [{-D|\--disk-parameters} *disk-template*:*disk-param*=*value*[,*disk-param*=*value*...]]
183 | [\--maintain-node-health {yes \| no}]
184 | [\--uid-pool *user-id pool definition*]
185 | [{-I|\--default-iallocator} *default instance allocator*]
186 | [\--default-iallocator-params *ial-param*=*value*,*ial-param*=*value*]
187 | [\--primary-ip-version *version*]
188 | [\--prealloc-wipe-disks {yes \| no}]
189 | [\--node-parameters *ndparams*]
190 | [{-C|\--candidate-pool-size} *candidate\_pool\_size*]
191 | [\--specs-cpu-count *spec-param*=*value* [,*spec-param*=*value*...]]
192 | [\--specs-disk-count *spec-param*=*value* [,*spec-param*=*value*...]]
193 | [\--specs-disk-size *spec-param*=*value* [,*spec-param*=*value*...]]
194 | [\--specs-mem-size *spec-param*=*value* [,*spec-param*=*value*...]]
195 | [\--specs-nic-count *spec-param*=*value* [,*spec-param*=*value*...]]
196 | [\--ipolicy-std-specs *spec*=*value* [,*spec*=*value*...]]
197 | [\--ipolicy-bounds-specs *bounds_ispecs*]
198 | [\--ipolicy-disk-templates *template* [,*template*...]]
199 | [\--ipolicy-spindle-ratio *ratio*]
200 | [\--ipolicy-vcpu-ratio *ratio*]
201 | [\--disk-state *diskstate*]
202 | [\--hypervisor-state *hvstate*]
203 | [\--drbd-usermode-helper *helper*]
204 | [\--enabled-disk-templates *template* [,*template*...]]
205 | [\--install-image *image*]
206 | [\--zeroing-image *image*]
207 | [\--compression-tools [*tool*, [*tool*]]]
208 | [\--user-shutdown {yes \| no}]
209 | {*clustername*}
210
211 This commands is only run once initially on the first node of the
212 cluster. It will initialize the cluster configuration, setup the
213 ssh-keys, start the daemons on the master node, etc. in order to have
214 a working one-node cluster.
215
216 Note that the *clustername* is not any random name. It has to be
217 resolvable to an IP address using DNS, and it is best if you give the
218 fully-qualified domain name. This hostname must resolve to an IP
219 address reserved exclusively for this purpose, i.e. not already in
220 use.
221
222 The cluster can run in two modes: single-home or dual-homed. In the
223 first case, all traffic (both public traffic, inter-node traffic and
224 data replication traffic) goes over the same interface. In the
225 dual-homed case, the data replication traffic goes over the second
226 network. The ``-s (--secondary-ip)`` option here marks the cluster as
227 dual-homed and its parameter represents this node's address on the
228 second network.  If you initialise the cluster with ``-s``, all nodes
229 added must have a secondary IP as well.
230
231 Note that for Ganeti it doesn't matter if the secondary network is
232 actually a separate physical network, or is done using tunneling,
233 etc. For performance reasons, it's recommended to use a separate
234 network, of course.
235
236 The ``--vg-name`` option will let you specify a volume group
237 different than "xenvg" for Ganeti to use when creating instance
238 disks. This volume group must have the same name on all nodes. Once
239 the cluster is initialized this can be altered by using the
240 **modify** command. Note that if the volume group name is modified after
241 the cluster creation and DRBD support is enabled you might have to
242 manually modify the metavg as well.
243
244 If you don't want to use lvm storage at all use
245 the ``--enabled-disk-templates`` option to restrict the set of enabled
246 disk templates. Once the cluster is initialized
247 you can change this setup with the **modify** command.
248
249 The ``--master-netdev`` option is useful for specifying a different
250 interface on which the master will activate its IP address. It's
251 important that all nodes have this interface because you'll need it
252 for a master failover.
253
254 The ``--master-netmask`` option allows to specify a netmask for the
255 master IP. The netmask must be specified as an integer, and will be
256 interpreted as a CIDR netmask. The default value is 32 for an IPv4
257 address and 128 for an IPv6 address.
258
259 The ``--use-external-mip-script`` option allows to specify whether to
260 use an user-supplied master IP address setup script, whose location is
261 ``@SYSCONFDIR@/ganeti/scripts/master-ip-setup``. If the option value is
262 set to False, the default script (located at
263 ``@PKGLIBDIR@/tools/master-ip-setup``) will be executed.
264
265 The ``-m (--mac-prefix)`` option will let you specify a three byte
266 prefix under which the virtual MAC addresses of your instances will be
267 generated. The prefix must be specified in the format ``XX:XX:XX`` and
268 the default is ``aa:00:00``.
269
270 The ``--no-etc-hosts`` option allows you to initialize the cluster
271 without modifying the /etc/hosts file.
272
273 The ``--no-ssh-init`` option allows you to initialize the cluster
274 without creating or distributing SSH key pairs.
275
276 The ``--file-storage-dir``, ``--shared-file-storage-dir`` and
277 ``--gluster-storage-dir`` options allow you set the directory to use for
278 storing the instance disk files when using respectively the file storage
279 backend, the shared file storage backend and the gluster storage
280 backend. Note that these directories must be an allowed directory for
281 file storage. Those directories are specified in the
282 ``@SYSCONFDIR@/ganeti/file-storage-paths`` file.
283 The file storage directory can also be a subdirectory of an allowed one.
284 The file storage directory should be present on all nodes.
285
286 The ``--prealloc-wipe-disks`` sets a cluster wide configuration value
287 for wiping disks prior to allocation and size changes (``gnt-instance
288 grow-disk``). This increases security on instance level as the instance
289 can't access untouched data from its underlying storage.
290
291 The ``--enabled-hypervisors`` option allows you to set the list of
292 hypervisors that will be enabled for this cluster. Instance
293 hypervisors can only be chosen from the list of enabled
294 hypervisors, and the first entry of this list will be used by
295 default. Currently, the following hypervisors are available:
296
297 xen-pvm
298     Xen PVM hypervisor
299
300 xen-hvm
301     Xen HVM hypervisor
302
303 kvm
304     Linux KVM hypervisor
305
306 chroot
307     a simple chroot manager that starts chroot based on a script at the
308     root of the filesystem holding the chroot
309
310 fake
311     fake hypervisor for development/testing
312
313 Either a single hypervisor name or a comma-separated list of
314 hypervisor names can be specified. If this option is not specified,
315 only the xen-pvm hypervisor is enabled by default.
316
317 The ``--user-shutdown`` option enables or disables user shutdown
318 detection at the cluster level.  User shutdown detection allows users to
319 initiate instance poweroff from inside the instance, and Ganeti will
320 report the instance status as 'USER_down' (as opposed, to 'ERROR_down')
321 and the watcher will not restart these instances, thus preserving their
322 instance status.  This option is disabled by default.  For KVM,
323 the hypervisor parameter ``user_shutdown`` must also be set, either at
324 the cluster level or on a per-instance basis (see **gnt-instance**\(8)).
325
326 The ``-H (--hypervisor-parameters)`` option allows you to set default
327 hypervisor specific parameters for the cluster. The format of this
328 option is the name of the hypervisor, followed by a colon and a
329 comma-separated list of key=value pairs. The keys available for each
330 hypervisors are detailed in the **gnt-instance**\(8) man page, in the
331 **add** command plus the following parameters which are only
332 configurable globally (at cluster level):
333
334 migration\_port
335     Valid for the Xen PVM and KVM hypervisors.
336
337     This options specifies the TCP port to use for live-migration when
338     using the xm toolstack. The same port should be configured on all
339     nodes in the ``@XEN_CONFIG_DIR@/xend-config.sxp`` file, under the
340     key "xend-relocation-port".
341
342 migration\_bandwidth
343     Valid for the KVM hypervisor.
344
345     This option specifies the maximum bandwidth that KVM will use for
346     instance live migrations. The value is in MiB/s.
347
348     This option is only effective with kvm versions >= 78 and qemu-kvm
349     versions >= 0.10.0.
350
351 The ``-B (--backend-parameters)`` option allows you to set the default
352 backend parameters for the cluster. The parameter format is a
353 comma-separated list of key=value pairs with the following supported
354 keys:
355
356 vcpus
357     Number of VCPUs to set for an instance by default, must be an
358     integer, will be set to 1 if no specified.
359
360 maxmem
361     Maximum amount of memory to allocate for an instance by default, can
362     be either an integer or an integer followed by a unit (M for
363     mebibytes and G for gibibytes are supported), will be set to 128M if
364     not specified.
365
366 minmem
367     Minimum amount of memory to allocate for an instance by default, can
368     be either an integer or an integer followed by a unit (M for
369     mebibytes and G for gibibytes are supported), will be set to 128M if
370     not specified.
371
372 auto\_balance
373     Value of the auto\_balance flag for instances to use by default,
374     will be set to true if not specified.
375
376 always\_failover
377     Default value for the ``always_failover`` flag for instances; if
378     not set, ``False`` is used.
379
380
381 The ``-N (--nic-parameters)`` option allows you to set the default
382 network interface parameters for the cluster. The parameter format is a
383 comma-separated list of key=value pairs with the following supported
384 keys:
385
386 mode
387     The default NIC mode, one of ``routed``, ``bridged`` or
388     ``openvswitch``.
389
390 link
391     In ``bridged`` or ``openvswitch`` mode the default interface where
392     to attach NICs. In ``routed`` mode it represents an
393     hypervisor-vif-script dependent value to allow different instance
394     groups. For example under the KVM default network script it is
395     interpreted as a routing table number or name. Openvswitch support
396     is also hypervisor dependent and currently works for the default KVM
397     network script. Under Xen a custom network script must be provided.
398
399 The ``-D (--disk-parameters)`` option allows you to set the default disk
400 template parameters at cluster level. The format used for this option is
401 similar to the one use by the  ``-H`` option: the disk template name
402 must be specified first, followed by a colon and by a comma-separated
403 list of key-value pairs. These parameters can only be specified at
404 cluster and node group level; the cluster-level parameter are inherited
405 by the node group at the moment of its creation, and can be further
406 modified at node group level using the **gnt-group**\(8) command.
407
408 The following is the list of disk parameters available for the **drbd**
409 template, with measurement units specified in square brackets at the end
410 of the description (when applicable):
411
412 resync-rate
413     Static re-synchronization rate. [KiB/s]
414
415 data-stripes
416     Number of stripes to use for data LVs.
417
418 meta-stripes
419     Number of stripes to use for meta LVs.
420
421 disk-barriers
422     What kind of barriers to **disable** for disks. It can either assume
423     the value "n", meaning no barrier disabled, or a non-empty string
424     containing a subset of the characters "bfd". "b" means disable disk
425     barriers, "f" means disable disk flushes, "d" disables disk drains.
426
427 meta-barriers
428     Boolean value indicating whether the meta barriers should be
429     disabled (True) or not (False).
430
431 metavg
432     String containing the name of the default LVM volume group for DRBD
433     metadata. By default, it is set to ``xenvg``. It can be overridden
434     during the instance creation process by using the ``metavg`` key of
435     the ``--disk`` parameter.
436
437 disk-custom
438     String containing additional parameters to be appended to the
439     arguments list of ``drbdsetup disk``.
440
441 net-custom
442     String containing additional parameters to be appended to the
443     arguments list of ``drbdsetup net``.
444
445 protocol
446     Replication protocol for the DRBD device. Has to be either "A", "B"
447     or "C". Refer to the DRBD documentation for further information
448     about the differences between the protocols.
449
450 dynamic-resync
451     Boolean indicating whether to use the dynamic resync speed
452     controller or not. If enabled, c-plan-ahead must be non-zero and all
453     the c-* parameters will be used by DRBD. Otherwise, the value of
454     resync-rate will be used as a static resync speed.
455
456 c-plan-ahead
457     Agility factor of the dynamic resync speed controller. (the higher,
458     the slower the algorithm will adapt the resync speed). A value of 0
459     (that is the default) disables the controller. [ds]
460
461 c-fill-target
462     Maximum amount of in-flight resync data for the dynamic resync speed
463     controller. [sectors]
464
465 c-delay-target
466     Maximum estimated peer response latency for the dynamic resync speed
467     controller. [ds]
468
469 c-min-rate
470     Minimum resync speed for the dynamic resync speed controller. [KiB/s]
471
472 c-max-rate
473     Upper bound on resync speed for the dynamic resync speed controller.
474     [KiB/s]
475
476 List of parameters available for the **plain** template:
477
478 stripes
479     Number of stripes to use for new LVs.
480
481 List of parameters available for the **rbd** template:
482
483 pool
484     The RADOS cluster pool, inside which all rbd volumes will reside.
485     When a new RADOS cluster is deployed, the default pool to put rbd
486     volumes (Images in RADOS terminology) is 'rbd'.
487
488 access
489     If 'userspace', instances will access their disks directly without
490     going through a block device, avoiding expensive context switches
491     with kernel space and the potential for deadlocks_ in low memory
492     scenarios.
493
494     The default value is 'kernelspace' and it disables this behaviour.
495     This setting may only be changed to 'userspace' if all instance
496     disks in the affected group or cluster can be accessed in userspace.
497
498     Attempts to use this feature without rbd support compiled in KVM
499     result in a "no such file or directory" error messages.
500
501 .. _deadlocks: http://tracker.ceph.com/issues/3076
502
503 The option ``--maintain-node-health`` allows one to enable/disable
504 automatic maintenance actions on nodes. Currently these include
505 automatic shutdown of instances and deactivation of DRBD devices on
506 offline nodes; in the future it might be extended to automatic
507 removal of unknown LVM volumes, etc. Note that this option is only
508 useful if the use of ``ganeti-confd`` was enabled at compilation.
509
510 The ``--uid-pool`` option initializes the user-id pool. The
511 *user-id pool definition* can contain a list of user-ids and/or a
512 list of user-id ranges. The parameter format is a comma-separated
513 list of numeric user-ids or user-id ranges. The ranges are defined
514 by a lower and higher boundary, separated by a dash. The boundaries
515 are inclusive. If the ``--uid-pool`` option is not supplied, the
516 user-id pool is initialized to an empty list. An empty list means
517 that the user-id pool feature is disabled.
518
519 The ``-I (--default-iallocator)`` option specifies the default
520 instance allocator. The instance allocator will be used for operations
521 like instance creation, instance and node migration, etc. when no
522 manual override is specified. If this option is not specified and
523 htools was not enabled at build time, the default instance allocator
524 will be blank, which means that relevant operations will require the
525 administrator to manually specify either an instance allocator, or a
526 set of nodes. If the option is not specified but htools was enabled,
527 the default iallocator will be **hail**\(1) (assuming it can be found
528 on disk). The default iallocator can be changed later using the
529 **modify** command.
530
531 The option ``--default-iallocator-params`` sets the cluster-wide
532 iallocator parameters used by the default iallocator only on instance
533 allocations.
534
535 The ``--primary-ip-version`` option specifies the IP version used
536 for the primary address. Possible values are 4 and 6 for IPv4 and
537 IPv6, respectively. This option is used when resolving node names
538 and the cluster name.
539
540 The ``--node-parameters`` option allows you to set default node
541 parameters for the cluster. Please see **ganeti**\(7) for more
542 information about supported key=value pairs.
543
544 The ``-C (--candidate-pool-size)`` option specifies the
545 ``candidate_pool_size`` cluster parameter. This is the number of nodes
546 that the master will try to keep as master\_candidates. For more
547 details about this role and other node roles, see the **ganeti**\(7).
548
549 The ``--specs-...`` and ``--ipolicy-...`` options specify the instance
550 policy on the cluster. The ``--ipolicy-bounds-specs`` option sets the
551 minimum and maximum specifications for instances. The format is:
552 min:*param*=*value*,.../max:*param*=*value*,... and further
553 specifications pairs can be added by using ``//`` as a separator. The
554 ``--ipolicy-std-specs`` option takes a list of parameter/value pairs.
555 For both options, *param* can be:
556
557 - ``cpu-count``: number of VCPUs for an instance
558 - ``disk-count``: number of disk for an instance
559 - ``disk-size``: size of each disk
560 - ``memory-size``: instance memory
561 - ``nic-count``: number of network interface
562 - ``spindle-use``: spindle usage for an instance
563
564 For the ``--specs-...`` options, each option can have three values:
565 ``min``, ``max`` and ``std``, which can also be modified on group level
566 (except for ``std``, which is defined once for the entire cluster).
567 Please note, that ``std`` values are not the same as defaults set by
568 ``--beparams``, but they are used for the capacity calculations.
569
570 - ``--specs-cpu-count`` limits the number of VCPUs that can be used by an
571   instance.
572 - ``--specs-disk-count`` limits the number of disks
573 - ``--specs-disk-size`` limits the disk size for every disk used
574 - ``--specs-mem-size`` limits the amount of memory available
575 - ``--specs-nic-count`` sets limits on the number of NICs used
576
577 The ``--ipolicy-spindle-ratio`` option takes a decimal number. The
578 ``--ipolicy-disk-templates`` option takes a comma-separated list of disk
579 templates. This list of disk templates must be a subset of the list
580 of cluster-wide enabled disk templates (which can be set with
581 ``--enabled-disk-templates``).
582
583 - ``--ipolicy-spindle-ratio`` limits the instances-spindles ratio
584 - ``--ipolicy-vcpu-ratio`` limits the vcpu-cpu ratio
585
586 All the instance policy elements can be overridden at group level. Group
587 level overrides can be removed by specifying ``default`` as the value of
588 an item.
589
590 The ``--drbd-usermode-helper`` option can be used to specify a usermode
591 helper. Check that this string is the one used by the DRBD kernel.
592
593 For details about how to use ``--hypervisor-state`` and ``--disk-state``
594 have a look at **ganeti**\(7).
595
596 The ``--enabled-disk-templates`` option specifies a list of disk templates
597 that can be used by instances of the cluster. For the possible values in
598 this list, see **gnt-instance**\(8). Note that in contrast to the list of
599 disk templates in the ipolicy, this list is a hard restriction. It is not
600 possible to create instances with disk templates that are not enabled in
601 the cluster. It is also not possible to disable a disk template when there
602 are still instances using it. The first disk template in the list of
603 enabled disk template is the default disk template. It will be used for
604 instance creation, if no disk template is requested explicitely.
605
606 The ``--install-image`` option specifies the location of the OS image to
607 use to run the OS scripts inside a virtualized environment. This can be
608 a file path or a URL. In the case that a file path is used, nodes are
609 expected to have the install image located at the given path, although
610 that is enforced during a instance create with unsafe OS scripts
611 operation only.
612
613 The ``--zeroing-image`` option specifies the location of the OS image to
614 use to zero out the free space of an instance. This can be a file path
615 or a URL. In the case that a file path is used, nodes are expected to
616 have the zeroing image located at the given path, although that is
617 enforced during a zeroing operation only.
618
619 The ``--compression-tools`` option specifies the tools that can be used
620 to compress the disk data of instances in transfer. The default tools
621 are: 'gzip', 'gzip-slow', and 'gzip-fast'. For compatibility reasons,
622 the 'gzip' tool cannot be excluded from the list of compression tools.
623 Ganeti knows how to use certain tools, but does not provide them as a
624 default as they are not commonly present: currently only 'lzop'. The
625 user should indicate their presence by specifying them through this
626 option.
627 Any other custom tool specified must have a simple executable name
628 ('[-_a-zA-Z0-9]+'), accept input on stdin, and produce output on
629 stdout. The '-d' flag specifies that decompression rather than
630 compression is taking place. The '-h' flag must be supported as a means
631 of testing whether the executable exists. These requirements are
632 compatible with the gzip command line options, allowing many tools to
633 be easily wrapped and used.
634
635 MASTER-FAILOVER
636 ~~~~~~~~~~~~~~~
637
638 **master-failover** [\--no-voting] [\--yes-do-it]
639
640 Failover the master role to the current node.
641
642 The ``--no-voting`` option skips the remote node agreement checks.
643 This is dangerous, but necessary in some cases (for example failing
644 over the master role in a 2 node cluster with the original master
645 down). If the original master then comes up, it won't be able to
646 start its master daemon because it won't have enough votes, but so
647 won't the new master, if the master daemon ever needs a restart.
648 You can pass ``--no-voting`` to **ganeti-luxid** and **ganeti-wconfd**
649 on the new master to solve this problem, and run
650 **gnt-cluster redist-conf** to make sure the cluster is consistent
651 again.
652
653 The option ``--yes-do-it`` is used together with ``--no-voting``, for
654 skipping the interactive checks. This is even more dangerous, and should
655 only be used in conjunction with other means (e.g. a HA suite) to
656 confirm that the operation is indeed safe.
657
658 MASTER-PING
659 ~~~~~~~~~~~
660
661 **master-ping**
662
663 Checks if the master daemon is alive.
664
665 If the master daemon is alive and can respond to a basic query (the
666 equivalent of **gnt-cluster info**), then the exit code of the
667 command will be 0. If the master daemon is not alive (either due to
668 a crash or because this is not the master node), the exit code will
669 be 1.
670
671 MODIFY
672 ~~~~~~
673
674 | **modify** [\--submit] [\--print-job-id]
675 | [\--force]
676 | [\--vg-name *vg-name*]
677 | [\--enabled-hypervisors *hypervisors*]
678 | [{-H|\--hypervisor-parameters} *hypervisor*:*hv-param*=*value*[,*hv-param*=*value*...]]
679 | [{-B|\--backend-parameters} *be-param*=*value*[,*be-param*=*value*...]]
680 | [{-N|\--nic-parameters} *nic-param*=*value*[,*nic-param*=*value*...]]
681 | [{-D|\--disk-parameters} *disk-template*:*disk-param*=*value*[,*disk-param*=*value*...]]
682 | [\--uid-pool *user-id pool definition*]
683 | [\--add-uids *user-id pool definition*]
684 | [\--remove-uids *user-id pool definition*]
685 | [{-C|\--candidate-pool-size} *candidate\_pool\_size*]
686 | [--max-running-jobs *count* ]
687 | [--max-tracked-jobs *count* ]
688 | [\--maintain-node-health {yes \| no}]
689 | [\--prealloc-wipe-disks {yes \| no}]
690 | [{-I|\--default-iallocator} *default instance allocator*]
691 | [\--default-iallocator-params *ial-param*=*value*,*ial-param*=*value*]
692 | [\--reserved-lvs=*NAMES*]
693 | [\--node-parameters *ndparams*]
694 | [{-m|\--mac-prefix} *mac-prefix*]
695 | [\--master-netdev *interface-name*]
696 | [\--master-netmask *netmask*]
697 | [\--use-external-mip-script {yes \| no}]
698 | [\--hypervisor-state *hvstate*]
699 | [\--disk-state *diskstate*]
700 | [\--ipolicy-std-specs *spec*=*value* [,*spec*=*value*...]]
701 | [\--ipolicy-bounds-specs *bounds_ispecs*]
702 | [\--ipolicy-disk-templates *template* [,*template*...]]
703 | [\--ipolicy-spindle-ratio *ratio*]
704 | [\--ipolicy-vcpu-ratio *ratio*]
705 | [\--enabled-disk-templates *template* [,*template*...]]
706 | [\--drbd-usermode-helper *helper*]
707 | [\--file-storage-dir *dir*]
708 | [\--shared-file-storage-dir *dir*]
709 | [\--compression-tools [*tool*, [*tool*]]]
710 | [\--instance-communication-network *network*]
711 | [\--install-image *image*]
712 | [\--zeroing-image *image*]
713 | [\--user-shutdown {yes \| no}]
714
715
716 Modify the options for the cluster.
717
718 The ``--vg-name``, ``--enabled-hypervisors``, ``-H (--hypervisor-parameters)``,
719 ``-B (--backend-parameters)``, ``-D (--disk-parameters)``, ``--nic-parameters``,
720 ``-C (--candidate-pool-size)``, ``--maintain-node-health``,
721 ``--prealloc-wipe-disks``, ``--uid-pool``, ``--node-parameters``,
722 ``--mac-prefix``, ``--master-netdev``, ``--master-netmask``,
723 ``--use-external-mip-script``, ``--drbd-usermode-helper``,
724 ``--file-storage-dir``, ``--shared-file-storage-dir``,
725 ``--compression-tools``, and ``--enabled-disk-templates`` options are described in the **init** command.
726 ``--master-netdev``, ``--master-netmask``, ``--use-external-mip-script``,
727 ``--drbd-usermode-helper``, ``--file-storage-dir``,
728 ``--shared-file-storage-dir``, ``--enabled-disk-templates``, and
729 ``--user-shutdown`` options are
730 described in the **init** command.
731
732 The ``--hypervisor-state`` and ``--disk-state`` options are described in
733 detail in **ganeti**\(7).
734
735 The ``--max-running-jobs`` options allows to set limit on the
736 number of jobs in non-finished jobs that are not queued, i.e.,
737 the number of jobs that are in waiting or running state.
738 The ``--max-tracked-jobs`` options allows to set the limit on
739 the tracked jobs. Normally, Ganeti will watch waiting and running
740 jobs by tracking their job file with inotify. If this limit is
741 exceeded, however, Ganeti will back off and only periodically
742 pull for updates.
743
744 The ``--add-uids`` and ``--remove-uids`` options can be used to
745 modify the user-id pool by adding/removing a list of user-ids or
746 user-id ranges.
747
748 The option ``--reserved-lvs`` specifies a list (comma-separated) of
749 logical volume group names (regular expressions) that will be
750 ignored by the cluster verify operation. This is useful if the
751 volume group used for Ganeti is shared with the system for other
752 uses. Note that it's not recommended to create and mark as ignored
753 logical volume names which match Ganeti's own name format (starting
754 with UUID and then .diskN), as this option only skips the
755 verification, but not the actual use of the names given.
756
757 To remove all reserved logical volumes, pass in an empty argument
758 to the option, as in ``--reserved-lvs=`` or ``--reserved-lvs ''``.
759
760 The ``-I (--default-iallocator)`` is described in the **init**
761 command. To clear the default iallocator, just pass an empty string
762 ('').
763
764 The option ``--default-iallocator-params`` is described in the **init**
765 command. To clear the default iallocator parameters, just pass an empty
766 string ('').
767
768 The ``--ipolicy-...`` options are described in the **init** command.
769
770 The ``--instance-communication-network`` enables instance communication
771 by specifying the name of the Ganeti network that should be used for
772 instance communication.  If the supplied network does not exist, Ganeti
773 will create a new network with the supplied name with the default
774 parameters for instance communication.  If the supplied network exists,
775 Ganeti will check its parameters and warn about unusual configurations,
776 but it will still use that network for instance communication.
777
778 See **gnt-cluster init** for a description of ``--install-image`` and
779 ``--zeroing-image``.
780
781 See **ganeti**\(7) for a description of ``--submit`` and other common
782 options.
783
784 QUEUE
785 ~~~~~
786
787 **queue** {drain | undrain | info}
788
789 Change job queue properties.
790
791 The ``drain`` option sets the drain flag on the job queue. No new
792 jobs will be accepted, but jobs already in the queue will be
793 processed.
794
795 The ``undrain`` will unset the drain flag on the job queue. New
796 jobs will be accepted.
797
798 The ``info`` option shows the properties of the job queue.
799
800 WATCHER
801 ~~~~~~~
802
803 **watcher** {pause *duration* | continue | info}
804
805 Make the watcher pause or let it continue.
806
807 The ``pause`` option causes the watcher to pause for *duration*
808 seconds.
809
810 The ``continue`` option will let the watcher continue.
811
812 The ``info`` option shows whether the watcher is currently paused.
813
814 REDIST-CONF
815 ~~~~~~~~~~~
816
817 **redist-conf** [\--submit] [\--print-job-id]
818
819 This command forces a full push of configuration files from the
820 master node to the other nodes in the cluster. This is normally not
821 needed, but can be run if the **verify** complains about
822 configuration mismatches.
823
824 See **ganeti**\(7) for a description of ``--submit`` and other common
825 options.
826
827 RENAME
828 ~~~~~~
829
830 **rename** [-f] {*name*}
831
832 Renames the cluster and in the process updates the master IP
833 address to the one the new name resolves to. At least one of either
834 the name or the IP address must be different, otherwise the
835 operation will be aborted.
836
837 Note that since this command can be dangerous (especially when run
838 over SSH), the command will require confirmation unless run with
839 the ``-f`` option.
840
841 RENEW-CRYPTO
842 ~~~~~~~~~~~~
843
844 | **renew-crypto** [-f]
845 | [\--new-cluster-certificate] | [\--new-node-certificates]
846 | [\--new-confd-hmac-key]
847 | [\--new-rapi-certificate] [\--rapi-certificate *rapi-cert*]
848 | [\--new-spice-certificate | \--spice-certificate *spice-cert*
849 | \--spice-ca-certificate *spice-ca-cert*]
850 | [\--new-cluster-domain-secret] [\--cluster-domain-secret *filename*]
851
852 This command will stop all Ganeti daemons in the cluster and start
853 them again once the new certificates and keys are replicated. The
854 option ``--new-confd-hmac-key`` can be used to regenerate
855 the HMAC key used by **ganeti-confd**\(8).
856
857 The option ``--new-cluster-certificate`` will regenerate the
858 cluster-internal server SSL certificate. The option
859 ``--new-node-certificates`` will generate new node SSL
860 certificates for all nodes. Note that for the regeneration of
861 of the server SSL certficate will invoke a regeneration of the
862 node certificates as well, because node certificates are signed
863 by the server certificate and thus have to be recreated and
864 signed by the new server certificate. Nodes which are offline
865 during a renewal of the server or the node certificates are not
866 accessible anymore once they are marked as online again. To
867 fix this, please readd the node instead.
868
869 To generate a new self-signed RAPI certificate (used by
870 **ganeti-rapi**\(8)) specify ``--new-rapi-certificate``. If you want to
871 use your own certificate, e.g. one signed by a certificate
872 authority (CA), pass its filename to ``--rapi-certificate``.
873
874 To generate a new self-signed SPICE certificate, used for SPICE
875 connections to the KVM hypervisor, specify the
876 ``--new-spice-certificate`` option. If you want to provide a
877 certificate, pass its filename to ``--spice-certificate`` and pass the
878 signing CA certificate to ``--spice-ca-certificate``.
879
880 Finally ``--new-cluster-domain-secret`` generates a new, random
881 cluster domain secret, and ``--cluster-domain-secret`` reads the
882 secret from a file. The cluster domain secret is used to sign
883 information exchanged between separate clusters via a third party.
884
885 REPAIR-DISK-SIZES
886 ~~~~~~~~~~~~~~~~~
887
888 **repair-disk-sizes** [instance...]
889
890 This command checks that the recorded size of the given instance's
891 disks matches the actual size and updates any mismatches found.
892 This is needed if the Ganeti configuration is no longer consistent
893 with reality, as it will impact some disk operations. If no
894 arguments are given, all instances will be checked. When exclusive
895 storage is active, also spindles are updated.
896
897 Note that only active disks can be checked by this command; in case
898 a disk cannot be activated it's advised to use
899 **gnt-instance activate-disks \--ignore-size ...** to force
900 activation without regard to the current size.
901
902 When all the disk sizes are consistent, the command will return no
903 output. Otherwise it will log details about the inconsistencies in
904 the configuration.
905
906 UPGRADE
907 ~~~~~~~
908
909 **upgrade** {--to *version* | --resume}
910
911 This command safely switches all nodes of the cluster to a new Ganeti
912 version. It is a prerequisite that the new version is already installed,
913 albeit not activated, on all nodes; this requisite is checked before any
914 actions are done.
915
916 If called with the ``--resume`` option, any pending upgrade is
917 continued, that was interrupted by a power failure or similar on
918 master. It will do nothing, if not run on the master node, or if no
919 upgrade was in progress.
920
921
922 VERIFY
923 ~~~~~~
924
925 | **verify** [\--no-nplus1-mem] [\--node-group *nodegroup*]
926 | [\--error-codes] [{-I|\--ignore-errors} *errorcode*]
927 | [{-I|\--ignore-errors} *errorcode*...]
928
929 Verify correctness of cluster configuration. This is safe with
930 respect to running instances, and incurs no downtime of the
931 instances.
932
933 If the ``--no-nplus1-mem`` option is given, Ganeti won't check
934 whether if it loses a node it can restart all the instances on
935 their secondaries (and report an error otherwise).
936
937 With ``--node-group``, restrict the verification to those nodes and
938 instances that live in the named group. This will not verify global
939 settings, but will allow to perform verification of a group while other
940 operations are ongoing in other groups.
941
942 The ``--error-codes`` option outputs each error in the following
943 parseable format: *ftype*:*ecode*:*edomain*:*name*:*msg*.
944 These fields have the following meaning:
945
946 ftype
947     Failure type. Can be *WARNING* or *ERROR*.
948
949 ecode
950     Error code of the failure. See below for a list of error codes.
951
952 edomain
953     Can be *cluster*, *node* or *instance*.
954
955 name
956     Contains the name of the item that is affected from the failure.
957
958 msg
959     Contains a descriptive error message about the error
960
961 ``gnt-cluster verify`` will have a non-zero exit code if at least one of
962 the failures that are found are of type *ERROR*.
963
964 The ``--ignore-errors`` option can be used to change this behaviour,
965 because it demotes the error represented by the error code received as a
966 parameter to a warning. The option must be repeated for each error that
967 should be ignored (e.g.: ``-I ENODEVERSION -I ENODEORPHANLV``). The
968 ``--error-codes`` option can be used to determine the error code of a
969 given error.
970
971 Note that the verification of the configuration file consistency across
972 master candidates can fail if there are other concurrently running
973 operations that modify the configuration.
974
975 List of error codes:
976
977 @CONSTANTS_ECODES@
978
979 VERIFY-DISKS
980 ~~~~~~~~~~~~
981
982 **verify-disks**
983
984 The command checks which instances have degraded DRBD disks and
985 activates the disks of those instances.
986
987 This command is run from the **ganeti-watcher** tool, which also
988 has a different, complementary algorithm for doing this check.
989 Together, these two should ensure that DRBD disks are kept
990 consistent.
991
992 VERSION
993 ~~~~~~~
994
995 **version**
996
997 Show the cluster version.
998
999 Tags
1000 ~~~~
1001
1002 ADD-TAGS
1003 ^^^^^^^^
1004
1005 **add-tags** [\--from *file*] {*tag*...}
1006
1007 Add tags to the cluster. If any of the tags contains invalid
1008 characters, the entire operation will abort.
1009
1010 If the ``--from`` option is given, the list of tags will be
1011 extended with the contents of that file (each line becomes a tag).
1012 In this case, there is not need to pass tags on the command line
1013 (if you do, both sources will be used). A file name of - will be
1014 interpreted as stdin.
1015
1016 LIST-TAGS
1017 ^^^^^^^^^
1018
1019 **list-tags**
1020
1021 List the tags of the cluster.
1022
1023 REMOVE-TAGS
1024 ^^^^^^^^^^^
1025
1026 **remove-tags** [\--from *file*] {*tag*...}
1027
1028 Remove tags from the cluster. If any of the tags are not existing
1029 on the cluster, the entire operation will abort.
1030
1031 If the ``--from`` option is given, the list of tags to be removed will
1032 be extended with the contents of that file (each line becomes a tag).
1033 In this case, there is not need to pass tags on the command line (if
1034 you do, tags from both sources will be removed). A file name of - will
1035 be interpreted as stdin.
1036
1037 SEARCH-TAGS
1038 ^^^^^^^^^^^
1039
1040 **search-tags** {*pattern*}
1041
1042 Searches the tags on all objects in the cluster (the cluster
1043 itself, the nodes and the instances) for a given pattern. The
1044 pattern is interpreted as a regular expression and a search will be
1045 done on it (i.e. the given pattern is not anchored to the beggining
1046 of the string; if you want that, prefix the pattern with ^).
1047
1048 If no tags are matching the pattern, the exit code of the command
1049 will be one. If there is at least one match, the exit code will be
1050 zero. Each match is listed on one line, the object and the tag
1051 separated by a space. The cluster will be listed as /cluster, a
1052 node will be listed as /nodes/*name*, and an instance as
1053 /instances/*name*. Example:
1054
1055 ::
1056
1057     # gnt-cluster search-tags time
1058     /cluster ctime:2007-09-01
1059     /nodes/node1.example.com mtime:2007-10-04
1060
1061 .. vim: set textwidth=72 :
1062 .. Local Variables:
1063 .. mode: rst
1064 .. fill-column: 72
1065 .. End: