Add ``--no-ssh-key-check`` to manpage of renew-crypto
[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-masterd** on the new
649 master to solve this problem, and run **gnt-cluster redist-conf**
650 to make sure the cluster is consistent again.
651
652 The option ``--yes-do-it`` is used together with ``--no-voting``, for
653 skipping the interactive checks. This is even more dangerous, and should
654 only be used in conjunction with other means (e.g. a HA suite) to
655 confirm that the operation is indeed safe.
656
657 MASTER-PING
658 ~~~~~~~~~~~
659
660 **master-ping**
661
662 Checks if the master daemon is alive.
663
664 If the master daemon is alive and can respond to a basic query (the
665 equivalent of **gnt-cluster info**), then the exit code of the
666 command will be 0. If the master daemon is not alive (either due to
667 a crash or because this is not the master node), the exit code will
668 be 1.
669
670 MODIFY
671 ~~~~~~
672
673 | **modify** [\--submit] [\--print-job-id]
674 | [\--force]
675 | [\--vg-name *vg-name*]
676 | [\--enabled-hypervisors *hypervisors*]
677 | [{-H|\--hypervisor-parameters} *hypervisor*:*hv-param*=*value*[,*hv-param*=*value*...]]
678 | [{-B|\--backend-parameters} *be-param*=*value*[,*be-param*=*value*...]]
679 | [{-N|\--nic-parameters} *nic-param*=*value*[,*nic-param*=*value*...]]
680 | [{-D|\--disk-parameters} *disk-template*:*disk-param*=*value*[,*disk-param*=*value*...]]
681 | [\--uid-pool *user-id pool definition*]
682 | [\--add-uids *user-id pool definition*]
683 | [\--remove-uids *user-id pool definition*]
684 | [{-C|\--candidate-pool-size} *candidate\_pool\_size*]
685 | [--max-running-jobs *count* ]
686 | [--max-tracked-jobs *count* ]
687 | [\--maintain-node-health {yes \| no}]
688 | [\--prealloc-wipe-disks {yes \| no}]
689 | [{-I|\--default-iallocator} *default instance allocator*]
690 | [\--default-iallocator-params *ial-param*=*value*,*ial-param*=*value*]
691 | [\--reserved-lvs=*NAMES*]
692 | [\--node-parameters *ndparams*]
693 | [{-m|\--mac-prefix} *mac-prefix*]
694 | [\--master-netdev *interface-name*]
695 | [\--master-netmask *netmask*]
696 | [\--use-external-mip-script {yes \| no}]
697 | [\--hypervisor-state *hvstate*]
698 | [\--disk-state *diskstate*]
699 | [\--ipolicy-std-specs *spec*=*value* [,*spec*=*value*...]]
700 | [\--ipolicy-bounds-specs *bounds_ispecs*]
701 | [\--ipolicy-disk-templates *template* [,*template*...]]
702 | [\--ipolicy-spindle-ratio *ratio*]
703 | [\--ipolicy-vcpu-ratio *ratio*]
704 | [\--enabled-disk-templates *template* [,*template*...]]
705 | [\--drbd-usermode-helper *helper*]
706 | [\--file-storage-dir *dir*]
707 | [\--shared-file-storage-dir *dir*]
708 | [\--compression-tools [*tool*, [*tool*]]]
709 | [\--instance-communication-network *network*]
710 | [\--install-image *image*]
711 | [\--zeroing-image *image*]
712 | [\--user-shutdown {yes \| no}]
713 | [\--enabled-data-collectors *collectors*]
714 | [\--data-collector-interval *intervals*]
715
716
717 Modify the options for the cluster.
718
719 The ``--vg-name``, ``--enabled-hypervisors``, ``-H (--hypervisor-parameters)``,
720 ``-B (--backend-parameters)``, ``-D (--disk-parameters)``, ``--nic-parameters``,
721 ``-C (--candidate-pool-size)``, ``--maintain-node-health``,
722 ``--prealloc-wipe-disks``, ``--uid-pool``, ``--node-parameters``,
723 ``--mac-prefix``, ``--master-netdev``, ``--master-netmask``,
724 ``--use-external-mip-script``, ``--drbd-usermode-helper``,
725 ``--file-storage-dir``, ``--shared-file-storage-dir``,
726 ``--compression-tools``, and ``--enabled-disk-templates`` options are described in the **init** command.
727 ``--master-netdev``, ``--master-netmask``, ``--use-external-mip-script``,
728 ``--drbd-usermode-helper``, ``--file-storage-dir``,
729 ``--shared-file-storage-dir``, ``--enabled-disk-templates``, and
730 ``--user-shutdown`` options are
731 described in the **init** command.
732
733 The ``--hypervisor-state`` and ``--disk-state`` options are described in
734 detail in **ganeti**\(7).
735
736 The ``--max-running-jobs`` options allows to set limit on the
737 number of jobs in non-finished jobs that are not queued, i.e.,
738 the number of jobs that are in waiting or running state.
739 The ``--max-tracked-jobs`` options allows to set the limit on
740 the tracked jobs. Normally, Ganeti will watch waiting and running
741 jobs by tracking their job file with inotify. If this limit is
742 exceeded, however, Ganeti will back off and only periodically
743 pull for updates.
744
745 The ``--add-uids`` and ``--remove-uids`` options can be used to
746 modify the user-id pool by adding/removing a list of user-ids or
747 user-id ranges.
748
749 The option ``--reserved-lvs`` specifies a list (comma-separated) of
750 logical volume group names (regular expressions) that will be
751 ignored by the cluster verify operation. This is useful if the
752 volume group used for Ganeti is shared with the system for other
753 uses. Note that it's not recommended to create and mark as ignored
754 logical volume names which match Ganeti's own name format (starting
755 with UUID and then .diskN), as this option only skips the
756 verification, but not the actual use of the names given.
757
758 To remove all reserved logical volumes, pass in an empty argument
759 to the option, as in ``--reserved-lvs=`` or ``--reserved-lvs ''``.
760
761 The ``-I (--default-iallocator)`` is described in the **init**
762 command. To clear the default iallocator, just pass an empty string
763 ('').
764
765 The option ``--default-iallocator-params`` is described in the **init**
766 command. To clear the default iallocator parameters, just pass an empty
767 string ('').
768
769 The ``--ipolicy-...`` options are described in the **init** command.
770
771 The ``--instance-communication-network`` enables instance communication
772 by specifying the name of the Ganeti network that should be used for
773 instance communication.  If the supplied network does not exist, Ganeti
774 will create a new network with the supplied name with the default
775 parameters for instance communication.  If the supplied network exists,
776 Ganeti will check its parameters and warn about unusual configurations,
777 but it will still use that network for instance communication.
778
779 The ``--enabled-data-collectors`` and ``--data-collector-interval``
780 options are to control the behavior of the **ganeti-mond**\(8). The
781 first expects a list name=bool pairs to activate or decative the mentioned
782 data collector. The second option expects similar pairs of collector name
783 and number of seconds specifying the interval at which the collector
784 shall be collected.
785
786 See **gnt-cluster init** for a description of ``--install-image`` and
787 ``--zeroing-image``.
788
789 See **ganeti**\(7) for a description of ``--submit`` and other common
790 options.
791
792 QUEUE
793 ~~~~~
794
795 **queue** {drain | undrain | info}
796
797 Change job queue properties.
798
799 The ``drain`` option sets the drain flag on the job queue. No new
800 jobs will be accepted, but jobs already in the queue will be
801 processed.
802
803 The ``undrain`` will unset the drain flag on the job queue. New
804 jobs will be accepted.
805
806 The ``info`` option shows the properties of the job queue.
807
808 WATCHER
809 ~~~~~~~
810
811 **watcher** {pause *duration* | continue | info}
812
813 Make the watcher pause or let it continue.
814
815 The ``pause`` option causes the watcher to pause for *duration*
816 seconds.
817
818 The ``continue`` option will let the watcher continue.
819
820 The ``info`` option shows whether the watcher is currently paused.
821
822 REDIST-CONF
823 ~~~~~~~~~~~
824
825 **redist-conf** [\--submit] [\--print-job-id]
826
827 This command forces a full push of configuration files from the
828 master node to the other nodes in the cluster. This is normally not
829 needed, but can be run if the **verify** complains about
830 configuration mismatches.
831
832 See **ganeti**\(7) for a description of ``--submit`` and other common
833 options.
834
835 RENAME
836 ~~~~~~
837
838 **rename** [-f] {*name*}
839
840 Renames the cluster and in the process updates the master IP
841 address to the one the new name resolves to. At least one of either
842 the name or the IP address must be different, otherwise the
843 operation will be aborted.
844
845 Note that since this command can be dangerous (especially when run
846 over SSH), the command will require confirmation unless run with
847 the ``-f`` option.
848
849 RENEW-CRYPTO
850 ~~~~~~~~~~~~
851
852 | **renew-crypto** [-f]
853 | [\--new-cluster-certificate] | [\--new-node-certificates]
854 | [\--new-confd-hmac-key]
855 | [\--new-rapi-certificate] [\--rapi-certificate *rapi-cert*]
856 | [\--new-spice-certificate | \--spice-certificate *spice-cert*
857 | \--spice-ca-certificate *spice-ca-cert*]
858 | [\--new-ssh-keys] [\--no-ssh-key-check]
859 | [\--new-cluster-domain-secret] [\--cluster-domain-secret *filename*]
860
861 This command will stop all Ganeti daemons in the cluster and start
862 them again once the new certificates and keys are replicated. The
863 option ``--new-confd-hmac-key`` can be used to regenerate
864 the HMAC key used by **ganeti-confd**\(8).
865
866 The option ``--new-cluster-certificate`` will regenerate the
867 cluster-internal server SSL certificate. The option
868 ``--new-node-certificates`` will generate new node SSL
869 certificates for all nodes. Note that for the regeneration of
870 of the server SSL certficate will invoke a regeneration of the
871 node certificates as well, because node certificates are signed
872 by the server certificate and thus have to be recreated and
873 signed by the new server certificate. Nodes which are offline
874 during a renewal of the server or the node certificates are not
875 accessible anymore once they are marked as online again. To
876 fix this, please readd the node instead.
877
878 To generate a new self-signed RAPI certificate (used by
879 **ganeti-rapi**\(8)) specify ``--new-rapi-certificate``. If you want to
880 use your own certificate, e.g. one signed by a certificate
881 authority (CA), pass its filename to ``--rapi-certificate``.
882
883 To generate a new self-signed SPICE certificate, used for SPICE
884 connections to the KVM hypervisor, specify the
885 ``--new-spice-certificate`` option. If you want to provide a
886 certificate, pass its filename to ``--spice-certificate`` and pass the
887 signing CA certificate to ``--spice-ca-certificate``.
888
889 The option ``--new-ssh-keys`` renews all SSH keys of all nodes
890 and updates the ``authorized_keys`` files of all nodes to contain
891 only the (new) public keys of all master candidates. To avoid having
892 to confirm the fingerprint of each node use the
893 ``--no-ssh-key-check`` option. Be aware of that this includes a
894 security risk as you omit verifying the machines' identities.
895
896 Finally ``--new-cluster-domain-secret`` generates a new, random
897 cluster domain secret, and ``--cluster-domain-secret`` reads the
898 secret from a file. The cluster domain secret is used to sign
899 information exchanged between separate clusters via a third party.
900
901 REPAIR-DISK-SIZES
902 ~~~~~~~~~~~~~~~~~
903
904 **repair-disk-sizes** [instance...]
905
906 This command checks that the recorded size of the given instance's
907 disks matches the actual size and updates any mismatches found.
908 This is needed if the Ganeti configuration is no longer consistent
909 with reality, as it will impact some disk operations. If no
910 arguments are given, all instances will be checked. When exclusive
911 storage is active, also spindles are updated.
912
913 Note that only active disks can be checked by this command; in case
914 a disk cannot be activated it's advised to use
915 **gnt-instance activate-disks \--ignore-size ...** to force
916 activation without regard to the current size.
917
918 When all the disk sizes are consistent, the command will return no
919 output. Otherwise it will log details about the inconsistencies in
920 the configuration.
921
922 UPGRADE
923 ~~~~~~~
924
925 **upgrade** {--to *version* | --resume}
926
927 This command safely switches all nodes of the cluster to a new Ganeti
928 version. It is a prerequisite that the new version is already installed,
929 albeit not activated, on all nodes; this requisite is checked before any
930 actions are done.
931
932 If called with the ``--resume`` option, any pending upgrade is
933 continued, that was interrupted by a power failure or similar on
934 master. It will do nothing, if not run on the master node, or if no
935 upgrade was in progress.
936
937
938 VERIFY
939 ~~~~~~
940
941 | **verify** [\--no-nplus1-mem] [\--node-group *nodegroup*]
942 | [\--error-codes] [{-I|\--ignore-errors} *errorcode*]
943 | [{-I|\--ignore-errors} *errorcode*...]
944 | [--verify-ssh-clutter]
945
946 Verify correctness of cluster configuration. This is safe with
947 respect to running instances, and incurs no downtime of the
948 instances.
949
950 If the ``--no-nplus1-mem`` option is given, Ganeti won't check
951 whether if it loses a node it can restart all the instances on
952 their secondaries (and report an error otherwise).
953
954 With ``--node-group``, restrict the verification to those nodes and
955 instances that live in the named group. This will not verify global
956 settings, but will allow to perform verification of a group while other
957 operations are ongoing in other groups.
958
959 The ``--error-codes`` option outputs each error in the following
960 parseable format: *ftype*:*ecode*:*edomain*:*name*:*msg*.
961 These fields have the following meaning:
962
963 ftype
964     Failure type. Can be *WARNING* or *ERROR*.
965
966 ecode
967     Error code of the failure. See below for a list of error codes.
968
969 edomain
970     Can be *cluster*, *node* or *instance*.
971
972 name
973     Contains the name of the item that is affected from the failure.
974
975 msg
976     Contains a descriptive error message about the error
977
978 ``gnt-cluster verify`` will have a non-zero exit code if at least one of
979 the failures that are found are of type *ERROR*.
980
981 The ``--ignore-errors`` option can be used to change this behaviour,
982 because it demotes the error represented by the error code received as a
983 parameter to a warning. The option must be repeated for each error that
984 should be ignored (e.g.: ``-I ENODEVERSION -I ENODEORPHANLV``). The
985 ``--error-codes`` option can be used to determine the error code of a
986 given error.
987
988 Note that the verification of the configuration file consistency across
989 master candidates can fail if there are other concurrently running
990 operations that modify the configuration.
991
992 The ``--verify-ssh-clutter`` option checks if more than one SSH key for the
993 same 'user@hostname' pair exists in the 'authorizied_keys' file. This is only
994 checked for hostnames of nodes which belong to the cluster. This check is
995 optional, because there might be other systems manipulating the
996 'authorized_keys' files, which would cause too many false positives
997 otherwise.
998
999 List of error codes:
1000
1001 @CONSTANTS_ECODES@
1002
1003 VERIFY-DISKS
1004 ~~~~~~~~~~~~
1005
1006 **verify-disks**
1007
1008 The command checks which instances have degraded DRBD disks and
1009 activates the disks of those instances.
1010
1011 This command is run from the **ganeti-watcher** tool, which also
1012 has a different, complementary algorithm for doing this check.
1013 Together, these two should ensure that DRBD disks are kept
1014 consistent.
1015
1016 VERSION
1017 ~~~~~~~
1018
1019 **version**
1020
1021 Show the cluster version.
1022
1023 Tags
1024 ~~~~
1025
1026 ADD-TAGS
1027 ^^^^^^^^
1028
1029 **add-tags** [\--from *file*] {*tag*...}
1030
1031 Add tags to the cluster. If any of the tags contains invalid
1032 characters, the entire operation will abort.
1033
1034 If the ``--from`` option is given, the list of tags will be
1035 extended with the contents of that file (each line becomes a tag).
1036 In this case, there is not need to pass tags on the command line
1037 (if you do, both sources will be used). A file name of - will be
1038 interpreted as stdin.
1039
1040 LIST-TAGS
1041 ^^^^^^^^^
1042
1043 **list-tags**
1044
1045 List the tags of the cluster.
1046
1047 REMOVE-TAGS
1048 ^^^^^^^^^^^
1049
1050 **remove-tags** [\--from *file*] {*tag*...}
1051
1052 Remove tags from the cluster. If any of the tags are not existing
1053 on the cluster, the entire operation will abort.
1054
1055 If the ``--from`` option is given, the list of tags to be removed will
1056 be extended with the contents of that file (each line becomes a tag).
1057 In this case, there is not need to pass tags on the command line (if
1058 you do, tags from both sources will be removed). A file name of - will
1059 be interpreted as stdin.
1060
1061 SEARCH-TAGS
1062 ^^^^^^^^^^^
1063
1064 **search-tags** {*pattern*}
1065
1066 Searches the tags on all objects in the cluster (the cluster
1067 itself, the nodes and the instances) for a given pattern. The
1068 pattern is interpreted as a regular expression and a search will be
1069 done on it (i.e. the given pattern is not anchored to the beggining
1070 of the string; if you want that, prefix the pattern with ^).
1071
1072 If no tags are matching the pattern, the exit code of the command
1073 will be one. If there is at least one match, the exit code will be
1074 zero. Each match is listed on one line, the object and the tag
1075 separated by a space. The cluster will be listed as /cluster, a
1076 node will be listed as /nodes/*name*, and an instance as
1077 /instances/*name*. Example:
1078
1079 ::
1080
1081     # gnt-cluster search-tags time
1082     /cluster ctime:2007-09-01
1083     /nodes/node1.example.com mtime:2007-10-04
1084
1085 .. vim: set textwidth=72 :
1086 .. Local Variables:
1087 .. mode: rst
1088 .. fill-column: 72
1089 .. End: