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