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