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