kvm: Use -display none rather than -nographic
[ganeti-local] / doc / admin.rst
1 Ganeti administrator's guide
2 ============================
3
4 Documents Ganeti version |version|
5
6 .. contents::
7
8 .. highlight:: shell-example
9
10 Introduction
11 ------------
12
13 Ganeti is a virtualization cluster management software. You are expected
14 to be a system administrator familiar with your Linux distribution and
15 the Xen or KVM virtualization environments before using it.
16
17 The various components of Ganeti all have man pages and interactive
18 help. This manual though will help you getting familiar with the system
19 by explaining the most common operations, grouped by related use.
20
21 After a terminology glossary and a section on the prerequisites needed
22 to use this manual, the rest of this document is divided in sections
23 for the different targets that a command affects: instance, nodes, etc.
24
25 .. _terminology-label:
26
27 Ganeti terminology
28 ++++++++++++++++++
29
30 This section provides a small introduction to Ganeti terminology, which
31 might be useful when reading the rest of the document.
32
33 Cluster
34 ~~~~~~~
35
36 A set of machines (nodes) that cooperate to offer a coherent, highly
37 available virtualization service under a single administration domain.
38
39 Node
40 ~~~~
41
42 A physical machine which is member of a cluster.  Nodes are the basic
43 cluster infrastructure, and they don't need to be fault tolerant in
44 order to achieve high availability for instances.
45
46 Node can be added and removed (if they host no instances) at will from
47 the cluster. In a HA cluster and only with HA instances, the loss of any
48 single node will not cause disk data loss for any instance; of course,
49 a node crash will cause the crash of its primary instances.
50
51 A node belonging to a cluster can be in one of the following roles at a
52 given time:
53
54 - *master* node, which is the node from which the cluster is controlled
55 - *master candidate* node, only nodes in this role have the full cluster
56   configuration and knowledge, and only master candidates can become the
57   master node
58 - *regular* node, which is the state in which most nodes will be on
59   bigger clusters (>20 nodes)
60 - *drained* node, nodes in this state are functioning normally but the
61   cannot receive new instances; the intention is that nodes in this role
62   have some issue and they are being evacuated for hardware repairs
63 - *offline* node, in which there is a record in the cluster
64   configuration about the node, but the daemons on the master node will
65   not talk to this node; any instances declared as having an offline
66   node as either primary or secondary will be flagged as an error in the
67   cluster verify operation
68
69 Depending on the role, each node will run a set of daemons:
70
71 - the :command:`ganeti-noded` daemon, which controls the manipulation of
72   this node's hardware resources; it runs on all nodes which are in a
73   cluster
74 - the :command:`ganeti-confd` daemon (Ganeti 2.1+) which runs on all
75   nodes, but is only functional on master candidate nodes; this daemon
76   can be disabled at configuration time if you don't need its
77   functionality
78 - the :command:`ganeti-rapi` daemon which runs on the master node and
79   offers an HTTP-based API for the cluster
80 - the :command:`ganeti-masterd` daemon which runs on the master node and
81   allows control of the cluster
82
83 Beside the node role, there are other node flags that influence its
84 behaviour:
85
86 - the *master_capable* flag denotes whether the node can ever become a
87   master candidate; setting this to 'no' means that auto-promotion will
88   never make this node a master candidate; this flag can be useful for a
89   remote node that only runs local instances, and having it become a
90   master is impractical due to networking or other constraints
91 - the *vm_capable* flag denotes whether the node can host instances or
92   not; for example, one might use a non-vm_capable node just as a master
93   candidate, for configuration backups; setting this flag to no
94   disallows placement of instances of this node, deactivates hypervisor
95   and related checks on it (e.g. bridge checks, LVM check, etc.), and
96   removes it from cluster capacity computations
97
98
99 Instance
100 ~~~~~~~~
101
102 A virtual machine which runs on a cluster. It can be a fault tolerant,
103 highly available entity.
104
105 An instance has various parameters, which are classified in three
106 categories: hypervisor related-parameters (called ``hvparams``), general
107 parameters (called ``beparams``) and per network-card parameters (called
108 ``nicparams``). All these parameters can be modified either at instance
109 level or via defaults at cluster level.
110
111 Disk template
112 ~~~~~~~~~~~~~
113
114 The are multiple options for the storage provided to an instance; while
115 the instance sees the same virtual drive in all cases, the node-level
116 configuration varies between them.
117
118 There are five disk templates you can choose from:
119
120 diskless
121   The instance has no disks. Only used for special purpose operating
122   systems or for testing.
123
124 file
125   The instance will use plain files as backend for its disks. No
126   redundancy is provided, and this is somewhat more difficult to
127   configure for high performance.
128
129 plain
130   The instance will use LVM devices as backend for its disks. No
131   redundancy is provided.
132
133 drbd
134   .. note:: This is only valid for multi-node clusters using DRBD 8.0+
135
136   A mirror is set between the local node and a remote one, which must be
137   specified with the second value of the --node option. Use this option
138   to obtain a highly available instance that can be failed over to a
139   remote node should the primary one fail.
140
141   .. note:: Ganeti does not support DRBD stacked devices:
142      DRBD stacked setup is not fully symmetric and as such it is
143      not working with live migration.
144
145 rbd
146   The instance will use Volumes inside a RADOS cluster as backend for its
147   disks. It will access them using the RADOS block device (RBD).
148
149 IAllocator
150 ~~~~~~~~~~
151
152 A framework for using external (user-provided) scripts to compute the
153 placement of instances on the cluster nodes. This eliminates the need to
154 manually specify nodes in instance add, instance moves, node evacuate,
155 etc.
156
157 In order for Ganeti to be able to use these scripts, they must be place
158 in the iallocator directory (usually ``lib/ganeti/iallocators`` under
159 the installation prefix, e.g. ``/usr/local``).
160
161 “Primary” and “secondary” concepts
162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163
164 An instance has a primary and depending on the disk configuration, might
165 also have a secondary node. The instance always runs on the primary node
166 and only uses its secondary node for disk replication.
167
168 Similarly, the term of primary and secondary instances when talking
169 about a node refers to the set of instances having the given node as
170 primary, respectively secondary.
171
172 Tags
173 ~~~~
174
175 Tags are short strings that can be attached to either to cluster itself,
176 or to nodes or instances. They are useful as a very simplistic
177 information store for helping with cluster administration, for example
178 by attaching owner information to each instance after it's created::
179
180   $ gnt-instance add … %instance1%
181   $ gnt-instance add-tags %instance1% %owner:user2%
182
183 And then by listing each instance and its tags, this information could
184 be used for contacting the users of each instance.
185
186 Jobs and OpCodes
187 ~~~~~~~~~~~~~~~~
188
189 While not directly visible by an end-user, it's useful to know that a
190 basic cluster operation (e.g. starting an instance) is represented
191 internally by Ganeti as an *OpCode* (abbreviation from operation
192 code). These OpCodes are executed as part of a *Job*. The OpCodes in a
193 single Job are processed serially by Ganeti, but different Jobs will be
194 processed (depending on resource availability) in parallel. They will
195 not be executed in the submission order, but depending on resource
196 availability, locks and (starting with Ganeti 2.3) priority. An earlier
197 job may have to wait for a lock while a newer job doesn't need any locks
198 and can be executed right away. Operations requiring a certain order
199 need to be submitted as a single job, or the client must submit one job
200 at a time and wait for it to finish before continuing.
201
202 For example, shutting down the entire cluster can be done by running the
203 command ``gnt-instance shutdown --all``, which will submit for each
204 instance a separate job containing the “shutdown instance” OpCode.
205
206
207 Prerequisites
208 +++++++++++++
209
210 You need to have your Ganeti cluster installed and configured before you
211 try any of the commands in this document. Please follow the
212 :doc:`install` for instructions on how to do that.
213
214 Instance management
215 -------------------
216
217 Adding an instance
218 ++++++++++++++++++
219
220 The add operation might seem complex due to the many parameters it
221 accepts, but once you have understood the (few) required parameters and
222 the customisation capabilities you will see it is an easy operation.
223
224 The add operation requires at minimum five parameters:
225
226 - the OS for the instance
227 - the disk template
228 - the disk count and size
229 - the node specification or alternatively the iallocator to use
230 - and finally the instance name
231
232 The OS for the instance must be visible in the output of the command
233 ``gnt-os list`` and specifies which guest OS to install on the instance.
234
235 The disk template specifies what kind of storage to use as backend for
236 the (virtual) disks presented to the instance; note that for instances
237 with multiple virtual disks, they all must be of the same type.
238
239 The node(s) on which the instance will run can be given either manually,
240 via the ``-n`` option, or computed automatically by Ganeti, if you have
241 installed any iallocator script.
242
243 With the above parameters in mind, the command is::
244
245   $ gnt-instance add \
246     -n %TARGET_NODE%:%SECONDARY_NODE% \
247     -o %OS_TYPE% \
248     -t %DISK_TEMPLATE% -s %DISK_SIZE% \
249     %INSTANCE_NAME%
250
251 The instance name must be resolvable (e.g. exist in DNS) and usually
252 points to an address in the same subnet as the cluster itself.
253
254 The above command has the minimum required options; other options you
255 can give include, among others:
256
257 - The maximum/minimum memory size (``-B maxmem``, ``-B minmem``)
258   (``-B memory`` can be used to specify only one size)
259
260 - The number of virtual CPUs (``-B vcpus``)
261
262 - Arguments for the NICs of the instance; by default, a single-NIC
263   instance is created. The IP and/or bridge of the NIC can be changed
264   via ``--nic 0:ip=IP,bridge=BRIDGE``
265
266 See the manpage for gnt-instance for the detailed option list.
267
268 For example if you want to create an highly available instance, with a
269 single disk of 50GB and the default memory size, having primary node
270 ``node1`` and secondary node ``node3``, use the following command::
271
272   $ gnt-instance add -n node1:node3 -o debootstrap -t drbd -s 50G \
273     instance1
274
275 There is a also a command for batch instance creation from a
276 specification file, see the ``batch-create`` operation in the
277 gnt-instance manual page.
278
279 Regular instance operations
280 +++++++++++++++++++++++++++
281
282 Removal
283 ~~~~~~~
284
285 Removing an instance is even easier than creating one. This operation is
286 irreversible and destroys all the contents of your instance. Use with
287 care::
288
289   $ gnt-instance remove %INSTANCE_NAME%
290
291 .. _instance-startup-label:
292
293 Startup/shutdown
294 ~~~~~~~~~~~~~~~~
295
296 Instances are automatically started at instance creation time. To
297 manually start one which is currently stopped you can run::
298
299   $ gnt-instance startup %INSTANCE_NAME%
300
301 Ganeti will start an instance with up to its maximum instance memory. If
302 not enough memory is available Ganeti will use all the available memory
303 down to the instance minimum memory. If not even that amount of memory
304 is free Ganeti will refuse to start the instance.
305
306 Note, that this will not work when an instance is in a permanently
307 stopped state ``offline``. In this case, you will first have to
308 put it back to online mode by running::
309
310   $ gnt-instance modify --online %INSTANCE_NAME%
311
312 The command to stop the running instance is::
313
314   $ gnt-instance shutdown %INSTANCE_NAME%
315
316 If you want to shut the instance down more permanently, so that it
317 does not require dynamically allocated resources (memory and vcpus),
318 after shutting down an instance, execute the following::
319
320   $ gnt-instance modify --offline %INSTANCE_NAME%
321
322 .. warning:: Do not use the Xen or KVM commands directly to stop
323    instances. If you run for example ``xm shutdown`` or ``xm destroy``
324    on an instance Ganeti will automatically restart it (via
325    the :command:`ganeti-watcher(8)` command which is launched via cron).
326
327 Querying instances
328 ~~~~~~~~~~~~~~~~~~
329
330 There are two ways to get information about instances: listing
331 instances, which does a tabular output containing a given set of fields
332 about each instance, and querying detailed information about a set of
333 instances.
334
335 The command to see all the instances configured and their status is::
336
337   $ gnt-instance list
338
339 The command can return a custom set of information when using the ``-o``
340 option (as always, check the manpage for a detailed specification). Each
341 instance will be represented on a line, thus making it easy to parse
342 this output via the usual shell utilities (grep, sed, etc.).
343
344 To get more detailed information about an instance, you can run::
345
346   $ gnt-instance info %INSTANCE%
347
348 which will give a multi-line block of information about the instance,
349 it's hardware resources (especially its disks and their redundancy
350 status), etc. This is harder to parse and is more expensive than the
351 list operation, but returns much more detailed information.
352
353 Changing an instance's runtime memory
354 +++++++++++++++++++++++++++++++++++++
355
356 Ganeti will always make sure an instance has a value between its maximum
357 and its minimum memory available as runtime memory. As of version 2.6
358 Ganeti will only choose a size different than the maximum size when
359 starting up, failing over, or migrating an instance on a node with less
360 than the maximum memory available. It won't resize other instances in
361 order to free up space for an instance.
362
363 If you find that you need more memory on a node any instance can be
364 manually resized without downtime, with the command::
365
366   $ gnt-instance modify -m %SIZE% %INSTANCE_NAME%
367
368 The same command can also be used to increase the memory available on an
369 instance, provided that enough free memory is available on its node, and
370 the specified size is not larger than the maximum memory size the
371 instance had when it was first booted (an instance will be unable to see
372 new memory above the maximum that was specified to the hypervisor at its
373 boot time, if it needs to grow further a reboot becomes necessary).
374
375 Export/Import
376 +++++++++++++
377
378 You can create a snapshot of an instance disk and its Ganeti
379 configuration, which then you can backup, or import into another
380 cluster. The way to export an instance is::
381
382   $ gnt-backup export -n %TARGET_NODE% %INSTANCE_NAME%
383
384
385 The target node can be any node in the cluster with enough space under
386 ``/srv/ganeti`` to hold the instance image. Use the ``--noshutdown``
387 option to snapshot an instance without rebooting it. Note that Ganeti
388 only keeps one snapshot for an instance - any previous snapshot of the
389 same instance existing cluster-wide under ``/srv/ganeti`` will be
390 removed by this operation: if you want to keep them, you need to move
391 them out of the Ganeti exports directory.
392
393 Importing an instance is similar to creating a new one, but additionally
394 one must specify the location of the snapshot. The command is::
395
396   $ gnt-backup import -n %TARGET_NODE% \
397     --src-node=%NODE% --src-dir=%DIR% %INSTANCE_NAME%
398
399 By default, parameters will be read from the export information, but you
400 can of course pass them in via the command line - most of the options
401 available for the command :command:`gnt-instance add` are supported here
402 too.
403
404 Import of foreign instances
405 +++++++++++++++++++++++++++
406
407 There is a possibility to import a foreign instance whose disk data is
408 already stored as LVM volumes without going through copying it: the disk
409 adoption mode.
410
411 For this, ensure that the original, non-managed instance is stopped,
412 then create a Ganeti instance in the usual way, except that instead of
413 passing the disk information you specify the current volumes::
414
415   $ gnt-instance add -t plain -n %HOME_NODE% ... \
416     --disk 0:adopt=%lv_name%[,vg=%vg_name%] %INSTANCE_NAME%
417
418 This will take over the given logical volumes, rename them to the Ganeti
419 standard (UUID-based), and without installing the OS on them start
420 directly the instance. If you configure the hypervisor similar to the
421 non-managed configuration that the instance had, the transition should
422 be seamless for the instance. For more than one disk, just pass another
423 disk parameter (e.g. ``--disk 1:adopt=...``).
424
425 Instance kernel selection
426 +++++++++++++++++++++++++
427
428 The kernel that instances uses to bootup can come either from the node,
429 or from instances themselves, depending on the setup.
430
431 Xen-PVM
432 ~~~~~~~
433
434 With Xen PVM, there are three options.
435
436 First, you can use a kernel from the node, by setting the hypervisor
437 parameters as such:
438
439 - ``kernel_path`` to a valid file on the node (and appropriately
440   ``initrd_path``)
441 - ``kernel_args`` optionally set to a valid Linux setting (e.g. ``ro``)
442 - ``root_path`` to a valid setting (e.g. ``/dev/xvda1``)
443 - ``bootloader_path`` and ``bootloader_args`` to empty
444
445 Alternatively, you can delegate the kernel management to instances, and
446 use either ``pvgrub`` or the deprecated ``pygrub``. For this, you must
447 install the kernels and initrds in the instance and create a valid GRUB
448 v1 configuration file.
449
450 For ``pvgrub`` (new in version 2.4.2), you need to set:
451
452 - ``kernel_path`` to point to the ``pvgrub`` loader present on the node
453   (e.g. ``/usr/lib/xen/boot/pv-grub-x86_32.gz``)
454 - ``kernel_args`` to the path to the GRUB config file, relative to the
455   instance (e.g. ``(hd0,0)/grub/menu.lst``)
456 - ``root_path`` **must** be empty
457 - ``bootloader_path`` and ``bootloader_args`` to empty
458
459 While ``pygrub`` is deprecated, here is how you can configure it:
460
461 - ``bootloader_path`` to the pygrub binary (e.g. ``/usr/bin/pygrub``)
462 - the other settings are not important
463
464 More information can be found in the Xen wiki pages for `pvgrub
465 <http://wiki.xensource.com/xenwiki/PvGrub>`_ and `pygrub
466 <http://wiki.xensource.com/xenwiki/PyGrub>`_.
467
468 KVM
469 ~~~
470
471 For KVM also the kernel can be loaded either way.
472
473 For loading the kernels from the node, you need to set:
474
475 - ``kernel_path`` to a valid value
476 - ``initrd_path`` optionally set if you use an initrd
477 - ``kernel_args`` optionally set to a valid value (e.g. ``ro``)
478
479 If you want instead to have the instance boot from its disk (and execute
480 its bootloader), simply set the ``kernel_path`` parameter to an empty
481 string, and all the others will be ignored.
482
483 Instance HA features
484 --------------------
485
486 .. note:: This section only applies to multi-node clusters
487
488 .. _instance-change-primary-label:
489
490 Changing the primary node
491 +++++++++++++++++++++++++
492
493 There are three ways to exchange an instance's primary and secondary
494 nodes; the right one to choose depends on how the instance has been
495 created and the status of its current primary node. See
496 :ref:`rest-redundancy-label` for information on changing the secondary
497 node. Note that it's only possible to change the primary node to the
498 secondary and vice-versa; a direct change of the primary node with a
499 third node, while keeping the current secondary is not possible in a
500 single step, only via multiple operations as detailed in
501 :ref:`instance-relocation-label`.
502
503 Failing over an instance
504 ~~~~~~~~~~~~~~~~~~~~~~~~
505
506 If an instance is built in highly available mode you can at any time
507 fail it over to its secondary node, even if the primary has somehow
508 failed and it's not up anymore. Doing it is really easy, on the master
509 node you can just run::
510
511   $ gnt-instance failover %INSTANCE_NAME%
512
513 That's it. After the command completes the secondary node is now the
514 primary, and vice-versa.
515
516 The instance will be started with an amount of memory between its
517 ``maxmem`` and its ``minmem`` value, depending on the free memory on its
518 target node, or the operation will fail if that's not possible. See
519 :ref:`instance-startup-label` for details.
520
521 If the instance's disk template is of type rbd, then you can specify
522 the target node (which can be any node) explicitly, or specify an
523 iallocator plugin. If you omit both, the default iallocator will be
524 used to determine the target node::
525
526   $ gnt-instance failover -n %TARGET_NODE% %INSTANCE_NAME%
527
528 Live migrating an instance
529 ~~~~~~~~~~~~~~~~~~~~~~~~~~
530
531 If an instance is built in highly available mode, it currently runs and
532 both its nodes are running fine, you can migrate it over to its
533 secondary node, without downtime. On the master node you need to run::
534
535   $ gnt-instance migrate %INSTANCE_NAME%
536
537 The current load on the instance and its memory size will influence how
538 long the migration will take. In any case, for both KVM and Xen
539 hypervisors, the migration will be transparent to the instance.
540
541 If the destination node has less memory than the instance's current
542 runtime memory, but at least the instance's minimum memory available
543 Ganeti will automatically reduce the instance runtime memory before
544 migrating it, unless the ``--no-runtime-changes`` option is passed, in
545 which case the target node should have at least the instance's current
546 runtime memory free.
547
548 If the instance's disk template is of type rbd, then you can specify
549 the target node (which can be any node) explicitly, or specify an
550 iallocator plugin. If you omit both, the default iallocator will be
551 used to determine the target node::
552
553    $ gnt-instance migrate -n %TARGET_NODE% %INSTANCE_NAME%
554
555 Moving an instance (offline)
556 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
557
558 If an instance has not been create as mirrored, then the only way to
559 change its primary node is to execute the move command::
560
561   $ gnt-instance move -n %NEW_NODE% %INSTANCE%
562
563 This has a few prerequisites:
564
565 - the instance must be stopped
566 - its current primary node must be on-line and healthy
567 - the disks of the instance must not have any errors
568
569 Since this operation actually copies the data from the old node to the
570 new node, expect it to take proportional to the size of the instance's
571 disks and the speed of both the nodes' I/O system and their networking.
572
573 Disk operations
574 +++++++++++++++
575
576 Disk failures are a common cause of errors in any server
577 deployment. Ganeti offers protection from single-node failure if your
578 instances were created in HA mode, and it also offers ways to restore
579 redundancy after a failure.
580
581 Preparing for disk operations
582 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
583
584 It is important to note that for Ganeti to be able to do any disk
585 operation, the Linux machines on top of which Ganeti runs must be
586 consistent; for LVM, this means that the LVM commands must not return
587 failures; it is common that after a complete disk failure, any LVM
588 command aborts with an error similar to::
589
590   $ vgs
591   /dev/sdb1: read failed after 0 of 4096 at 0: Input/output error
592   /dev/sdb1: read failed after 0 of 4096 at 750153695232: Input/output error
593   /dev/sdb1: read failed after 0 of 4096 at 0: Input/output error
594   Couldn't find device with uuid 't30jmN-4Rcf-Fr5e-CURS-pawt-z0jU-m1TgeJ'.
595   Couldn't find all physical volumes for volume group xenvg.
596
597 Before restoring an instance's disks to healthy status, it's needed to
598 fix the volume group used by Ganeti so that we can actually create and
599 manage the logical volumes. This is usually done in a multi-step
600 process:
601
602 #. first, if the disk is completely gone and LVM commands exit with
603    “Couldn't find device with uuid…” then you need to run the command::
604
605     $ vgreduce --removemissing %VOLUME_GROUP%
606
607 #. after the above command, the LVM commands should be executing
608    normally (warnings are normal, but the commands will not fail
609    completely).
610
611 #. if the failed disk is still visible in the output of the ``pvs``
612    command, you need to deactivate it from allocations by running::
613
614     $ pvs -x n /dev/%DISK%
615
616 At this point, the volume group should be consistent and any bad
617 physical volumes should not longer be available for allocation.
618
619 Note that since version 2.1 Ganeti provides some commands to automate
620 these two operations, see :ref:`storage-units-label`.
621
622 .. _rest-redundancy-label:
623
624 Restoring redundancy for DRBD-based instances
625 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
626
627 A DRBD instance has two nodes, and the storage on one of them has
628 failed. Depending on which node (primary or secondary) has failed, you
629 have three options at hand:
630
631 - if the storage on the primary node has failed, you need to re-create
632   the disks on it
633 - if the storage on the secondary node has failed, you can either
634   re-create the disks on it or change the secondary and recreate
635   redundancy on the new secondary node
636
637 Of course, at any point it's possible to force re-creation of disks even
638 though everything is already fine.
639
640 For all three cases, the ``replace-disks`` operation can be used::
641
642   # re-create disks on the primary node
643   $ gnt-instance replace-disks -p %INSTANCE_NAME%
644   # re-create disks on the current secondary
645   $ gnt-instance replace-disks -s %INSTANCE_NAME%
646   # change the secondary node, via manual specification
647   $ gnt-instance replace-disks -n %NODE% %INSTANCE_NAME%
648   # change the secondary node, via an iallocator script
649   $ gnt-instance replace-disks -I %SCRIPT% %INSTANCE_NAME%
650   # since Ganeti 2.1: automatically fix the primary or secondary node
651   $ gnt-instance replace-disks -a %INSTANCE_NAME%
652
653 Since the process involves copying all data from the working node to the
654 target node, it will take a while, depending on the instance's disk
655 size, node I/O system and network speed. But it is (barring any network
656 interruption) completely transparent for the instance.
657
658 Re-creating disks for non-redundant instances
659 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
660
661 .. versionadded:: 2.1
662
663 For non-redundant instances, there isn't a copy (except backups) to
664 re-create the disks. But it's possible to at-least re-create empty
665 disks, after which a reinstall can be run, via the ``recreate-disks``
666 command::
667
668   $ gnt-instance recreate-disks %INSTANCE%
669
670 Note that this will fail if the disks already exists. The instance can
671 be assigned to new nodes automatically by specifying an iallocator
672 through the ``--iallocator`` option.
673
674 Conversion of an instance's disk type
675 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
676
677 It is possible to convert between a non-redundant instance of type
678 ``plain`` (LVM storage) and redundant ``drbd`` via the ``gnt-instance
679 modify`` command::
680
681   # start with a non-redundant instance
682   $ gnt-instance add -t plain ... %INSTANCE%
683
684   # later convert it to redundant
685   $ gnt-instance stop %INSTANCE%
686   $ gnt-instance modify -t drbd -n %NEW_SECONDARY% %INSTANCE%
687   $ gnt-instance start %INSTANCE%
688
689   # and convert it back
690   $ gnt-instance stop %INSTANCE%
691   $ gnt-instance modify -t plain %INSTANCE%
692   $ gnt-instance start %INSTANCE%
693
694 The conversion must be done while the instance is stopped, and
695 converting from plain to drbd template presents a small risk, especially
696 if the instance has multiple disks and/or if one node fails during the
697 conversion procedure). As such, it's recommended (as always) to make
698 sure that downtime for manual recovery is acceptable and that the
699 instance has up-to-date backups.
700
701 Debugging instances
702 +++++++++++++++++++
703
704 Accessing an instance's disks
705 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
706
707 From an instance's primary node you can have access to its disks. Never
708 ever mount the underlying logical volume manually on a fault tolerant
709 instance, or will break replication and your data will be
710 inconsistent. The correct way to access an instance's disks is to run
711 (on the master node, as usual) the command::
712
713   $ gnt-instance activate-disks %INSTANCE%
714
715 And then, *on the primary node of the instance*, access the device that
716 gets created. For example, you could mount the given disks, then edit
717 files on the filesystem, etc.
718
719 Note that with partitioned disks (as opposed to whole-disk filesystems),
720 you will need to use a tool like :manpage:`kpartx(8)`::
721
722   # on node1
723   $ gnt-instance activate-disks %instance1%
724   node3:disk/0:…
725   $ ssh node3
726   # on node 3
727   $ kpartx -l /dev/…
728   $ kpartx -a /dev/…
729   $ mount /dev/mapper/… /mnt/
730   # edit files under mnt as desired
731   $ umount /mnt/
732   $ kpartx -d /dev/…
733   $ exit
734   # back to node 1
735
736 After you've finished you can deactivate them with the deactivate-disks
737 command, which works in the same way::
738
739   $ gnt-instance deactivate-disks %INSTANCE%
740
741 Note that if any process started by you is still using the disks, the
742 above command will error out, and you **must** cleanup and ensure that
743 the above command runs successfully before you start the instance,
744 otherwise the instance will suffer corruption.
745
746 Accessing an instance's console
747 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
748
749 The command to access a running instance's console is::
750
751   $ gnt-instance console %INSTANCE_NAME%
752
753 Use the console normally and then type ``^]`` when done, to exit.
754
755 Other instance operations
756 +++++++++++++++++++++++++
757
758 Reboot
759 ~~~~~~
760
761 There is a wrapper command for rebooting instances::
762
763   $ gnt-instance reboot %instance2%
764
765 By default, this does the equivalent of shutting down and then starting
766 the instance, but it accepts parameters to perform a soft-reboot (via
767 the hypervisor), a hard reboot (hypervisor shutdown and then startup) or
768 a full one (the default, which also de-configures and then configures
769 again the disks of the instance).
770
771 Instance OS definitions debugging
772 +++++++++++++++++++++++++++++++++
773
774 Should you have any problems with instance operating systems the command
775 to see a complete status for all your nodes is::
776
777    $ gnt-os diagnose
778
779 .. _instance-relocation-label:
780
781 Instance relocation
782 ~~~~~~~~~~~~~~~~~~~
783
784 While it is not possible to move an instance from nodes ``(A, B)`` to
785 nodes ``(C, D)`` in a single move, it is possible to do so in a few
786 steps::
787
788   # instance is located on A, B
789   $ gnt-instance replace -n %nodeC% %instance1%
790   # instance has moved from (A, B) to (A, C)
791   # we now flip the primary/secondary nodes
792   $ gnt-instance migrate %instance1%
793   # instance lives on (C, A)
794   # we can then change A to D via:
795   $ gnt-instance replace -n %nodeD% %instance1%
796
797 Which brings it into the final configuration of ``(C, D)``. Note that we
798 needed to do two replace-disks operation (two copies of the instance
799 disks), because we needed to get rid of both the original nodes (A and
800 B).
801
802 Node operations
803 ---------------
804
805 There are much fewer node operations available than for instances, but
806 they are equivalently important for maintaining a healthy cluster.
807
808 Add/readd
809 +++++++++
810
811 It is at any time possible to extend the cluster with one more node, by
812 using the node add operation::
813
814   $ gnt-node add %NEW_NODE%
815
816 If the cluster has a replication network defined, then you need to pass
817 the ``-s REPLICATION_IP`` parameter to this option.
818
819 A variation of this command can be used to re-configure a node if its
820 Ganeti configuration is broken, for example if it has been reinstalled
821 by mistake::
822
823   $ gnt-node add --readd %EXISTING_NODE%
824
825 This will reinitialise the node as if it's been newly added, but while
826 keeping its existing configuration in the cluster (primary/secondary IP,
827 etc.), in other words you won't need to use ``-s`` here.
828
829 Changing the node role
830 ++++++++++++++++++++++
831
832 A node can be in different roles, as explained in the
833 :ref:`terminology-label` section. Promoting a node to the master role is
834 special, while the other roles are handled all via a single command.
835
836 Failing over the master node
837 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
838
839 If you want to promote a different node to the master role (for whatever
840 reason), run on any other master-candidate node the command::
841
842   $ gnt-cluster master-failover
843
844 and the node you ran it on is now the new master. In case you try to run
845 this on a non master-candidate node, you will get an error telling you
846 which nodes are valid.
847
848 Changing between the other roles
849 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
850
851 The ``gnt-node modify`` command can be used to select a new role::
852
853   # change to master candidate
854   $ gnt-node modify -C yes %NODE%
855   # change to drained status
856   $ gnt-node modify -D yes %NODE%
857   # change to offline status
858   $ gnt-node modify -O yes %NODE%
859   # change to regular mode (reset all flags)
860   $ gnt-node modify -O no -D no -C no %NODE%
861
862 Note that the cluster requires that at any point in time, a certain
863 number of nodes are master candidates, so changing from master candidate
864 to other roles might fail. It is recommended to either force the
865 operation (via the ``--force`` option) or first change the number of
866 master candidates in the cluster - see :ref:`cluster-config-label`.
867
868 Evacuating nodes
869 ++++++++++++++++
870
871 There are two steps of moving instances off a node:
872
873 - moving the primary instances (actually converting them into secondary
874   instances)
875 - moving the secondary instances (including any instances converted in
876   the step above)
877
878 Primary instance conversion
879 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
880
881 For this step, you can use either individual instance move
882 commands (as seen in :ref:`instance-change-primary-label`) or the bulk
883 per-node versions; these are::
884
885   $ gnt-node migrate %NODE%
886   $ gnt-node evacuate -s %NODE%
887
888 Note that the instance “move” command doesn't currently have a node
889 equivalent.
890
891 Both these commands, or the equivalent per-instance command, will make
892 this node the secondary node for the respective instances, whereas their
893 current secondary node will become primary. Note that it is not possible
894 to change in one step the primary node to another node as primary, while
895 keeping the same secondary node.
896
897 Secondary instance evacuation
898 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
899
900 For the evacuation of secondary instances, a command called
901 :command:`gnt-node evacuate` is provided and its syntax is::
902
903   $ gnt-node evacuate -I %IALLOCATOR_SCRIPT% %NODE%
904   $ gnt-node evacuate -n %DESTINATION_NODE% %NODE%
905
906 The first version will compute the new secondary for each instance in
907 turn using the given iallocator script, whereas the second one will
908 simply move all instances to DESTINATION_NODE.
909
910 Removal
911 +++++++
912
913 Once a node no longer has any instances (neither primary nor secondary),
914 it's easy to remove it from the cluster::
915
916   $ gnt-node remove %NODE_NAME%
917
918 This will deconfigure the node, stop the ganeti daemons on it and leave
919 it hopefully like before it joined to the cluster.
920
921 Replication network changes
922 +++++++++++++++++++++++++++
923
924 The :command:`gnt-node modify -s` command can be used to change the
925 secondary IP of a node. This operation can only be performed if:
926
927 - No instance is active on the target node
928 - The new target IP is reachable from the master's secondary IP
929
930 Also this operation will not allow to change a node from single-homed
931 (same primary and secondary ip) to multi-homed (separate replication
932 network) or vice versa, unless:
933
934 - The target node is the master node and `--force` is passed.
935 - The target cluster is single-homed and the new primary ip is a change
936   to single homed for a particular node.
937 - The target cluster is multi-homed and the new primary ip is a change
938   to multi homed for a particular node.
939
940 For example to do a single-homed to multi-homed conversion::
941
942   $ gnt-node modify --force -s %SECONDARY_IP% %MASTER_NAME%
943   $ gnt-node modify -s %SECONDARY_IP% %NODE1_NAME%
944   $ gnt-node modify -s %SECONDARY_IP% %NODE2_NAME%
945   $ gnt-node modify -s %SECONDARY_IP% %NODE3_NAME%
946   ...
947
948 The same commands can be used for multi-homed to single-homed except the
949 secondary IPs should be the same as the primaries for each node, for
950 that case.
951
952 Storage handling
953 ++++++++++++++++
954
955 When using LVM (either standalone or with DRBD), it can become tedious
956 to debug and fix it in case of errors. Furthermore, even file-based
957 storage can become complicated to handle manually on many hosts. Ganeti
958 provides a couple of commands to help with automation.
959
960 Logical volumes
961 ~~~~~~~~~~~~~~~
962
963 This is a command specific to LVM handling. It allows listing the
964 logical volumes on a given node or on all nodes and their association to
965 instances via the ``volumes`` command::
966
967   $ gnt-node volumes
968   Node  PhysDev   VG    Name             Size Instance
969   node1 /dev/sdb1 xenvg e61fbc97-….disk0 512M instance17
970   node1 /dev/sdb1 xenvg ebd1a7d1-….disk0 512M instance19
971   node2 /dev/sdb1 xenvg 0af08a3d-….disk0 512M instance20
972   node2 /dev/sdb1 xenvg cc012285-….disk0 512M instance16
973   node2 /dev/sdb1 xenvg f0fac192-….disk0 512M instance18
974
975 The above command maps each logical volume to a volume group and
976 underlying physical volume and (possibly) to an instance.
977
978 .. _storage-units-label:
979
980 Generalized storage handling
981 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
982
983 .. versionadded:: 2.1
984
985 Starting with Ganeti 2.1, a new storage framework has been implemented
986 that tries to abstract the handling of the storage type the cluster
987 uses.
988
989 First is listing the backend storage and their space situation::
990
991   $ gnt-node list-storage
992   Node  Name        Size Used   Free
993   node1 /dev/sda7 673.8G   0M 673.8G
994   node1 /dev/sdb1 698.6G 1.5G 697.1G
995   node2 /dev/sda7 673.8G   0M 673.8G
996   node2 /dev/sdb1 698.6G 1.0G 697.6G
997
998 The default is to list LVM physical volumes. It's also possible to list
999 the LVM volume groups::
1000
1001   $ gnt-node list-storage -t lvm-vg
1002   Node  Name  Size
1003   node1 xenvg 1.3T
1004   node2 xenvg 1.3T
1005
1006 Next is repairing storage units, which is currently only implemented for
1007 volume groups and does the equivalent of ``vgreduce --removemissing``::
1008
1009   $ gnt-node repair-storage %node2% lvm-vg xenvg
1010   Sun Oct 25 22:21:45 2009 Repairing storage unit 'xenvg' on node2 ...
1011
1012 Last is the modification of volume properties, which is (again) only
1013 implemented for LVM physical volumes and allows toggling the
1014 ``allocatable`` value::
1015
1016   $ gnt-node modify-storage --allocatable=no %node2% lvm-pv /dev/%sdb1%
1017
1018 Use of the storage commands
1019 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1020
1021 All these commands are needed when recovering a node from a disk
1022 failure:
1023
1024 - first, we need to recover from complete LVM failure (due to missing
1025   disk), by running the ``repair-storage`` command
1026 - second, we need to change allocation on any partially-broken disk
1027   (i.e. LVM still sees it, but it has bad blocks) by running
1028   ``modify-storage``
1029 - then we can evacuate the instances as needed
1030
1031
1032 Cluster operations
1033 ------------------
1034
1035 Beside the cluster initialisation command (which is detailed in the
1036 :doc:`install` document) and the master failover command which is
1037 explained under node handling, there are a couple of other cluster
1038 operations available.
1039
1040 .. _cluster-config-label:
1041
1042 Standard operations
1043 +++++++++++++++++++
1044
1045 One of the few commands that can be run on any node (not only the
1046 master) is the ``getmaster`` command::
1047
1048   # on node2
1049   $ gnt-cluster getmaster
1050   node1.example.com
1051
1052 It is possible to query and change global cluster parameters via the
1053 ``info`` and ``modify`` commands::
1054
1055   $ gnt-cluster info
1056   Cluster name: cluster.example.com
1057   Cluster UUID: 07805e6f-f0af-4310-95f1-572862ee939c
1058   Creation time: 2009-09-25 05:04:15
1059   Modification time: 2009-10-18 22:11:47
1060   Master node: node1.example.com
1061   Architecture (this node): 64bit (x86_64)
1062   …
1063   Tags: foo
1064   Default hypervisor: xen-pvm
1065   Enabled hypervisors: xen-pvm
1066   Hypervisor parameters:
1067     - xen-pvm:
1068         root_path: /dev/sda1
1069         …
1070   Cluster parameters:
1071     - candidate pool size: 10
1072       …
1073   Default instance parameters:
1074     - default:
1075         memory: 128
1076         …
1077   Default nic parameters:
1078     - default:
1079         link: xen-br0
1080         …
1081
1082 There various parameters above can be changed via the ``modify``
1083 commands as follows:
1084
1085 - the hypervisor parameters can be changed via ``modify -H
1086   xen-pvm:root_path=…``, and so on for other hypervisors/key/values
1087 - the "default instance parameters" are changeable via ``modify -B
1088   parameter=value…`` syntax
1089 - the cluster parameters are changeable via separate options to the
1090   modify command (e.g. ``--candidate-pool-size``, etc.)
1091
1092 For detailed option list see the :manpage:`gnt-cluster(8)` man page.
1093
1094 The cluster version can be obtained via the ``version`` command::
1095   $ gnt-cluster version
1096   Software version: 2.1.0
1097   Internode protocol: 20
1098   Configuration format: 2010000
1099   OS api version: 15
1100   Export interface: 0
1101
1102 This is not very useful except when debugging Ganeti.
1103
1104 Global node commands
1105 ++++++++++++++++++++
1106
1107 There are two commands provided for replicating files to all nodes of a
1108 cluster and for running commands on all the nodes::
1109
1110   $ gnt-cluster copyfile %/path/to/file%
1111   $ gnt-cluster command %ls -l /path/to/file%
1112
1113 These are simple wrappers over scp/ssh and more advanced usage can be
1114 obtained using :manpage:`dsh(1)` and similar commands. But they are
1115 useful to update an OS script from the master node, for example.
1116
1117 Cluster verification
1118 ++++++++++++++++++++
1119
1120 There are three commands that relate to global cluster checks. The first
1121 one is ``verify`` which gives an overview on the cluster state,
1122 highlighting any issues. In normal operation, this command should return
1123 no ``ERROR`` messages::
1124
1125   $ gnt-cluster verify
1126   Sun Oct 25 23:08:58 2009 * Verifying global settings
1127   Sun Oct 25 23:08:58 2009 * Gathering data (2 nodes)
1128   Sun Oct 25 23:09:00 2009 * Verifying node status
1129   Sun Oct 25 23:09:00 2009 * Verifying instance status
1130   Sun Oct 25 23:09:00 2009 * Verifying orphan volumes
1131   Sun Oct 25 23:09:00 2009 * Verifying remaining instances
1132   Sun Oct 25 23:09:00 2009 * Verifying N+1 Memory redundancy
1133   Sun Oct 25 23:09:00 2009 * Other Notes
1134   Sun Oct 25 23:09:00 2009   - NOTICE: 5 non-redundant instance(s) found.
1135   Sun Oct 25 23:09:00 2009 * Hooks Results
1136
1137 The second command is ``verify-disks``, which checks that the instance's
1138 disks have the correct status based on the desired instance state
1139 (up/down)::
1140
1141   $ gnt-cluster verify-disks
1142
1143 Note that this command will show no output when disks are healthy.
1144
1145 The last command is used to repair any discrepancies in Ganeti's
1146 recorded disk size and the actual disk size (disk size information is
1147 needed for proper activation and growth of DRBD-based disks)::
1148
1149   $ gnt-cluster repair-disk-sizes
1150   Sun Oct 25 23:13:16 2009  - INFO: Disk 0 of instance instance1 has mismatched size, correcting: recorded 512, actual 2048
1151   Sun Oct 25 23:13:17 2009  - WARNING: Invalid result from node node4, ignoring node results
1152
1153 The above shows one instance having wrong disk size, and a node which
1154 returned invalid data, and thus we ignored all primary instances of that
1155 node.
1156
1157 Configuration redistribution
1158 ++++++++++++++++++++++++++++
1159
1160 If the verify command complains about file mismatches between the master
1161 and other nodes, due to some node problems or if you manually modified
1162 configuration files, you can force an push of the master configuration
1163 to all other nodes via the ``redist-conf`` command::
1164
1165   $ gnt-cluster redist-conf
1166
1167 This command will be silent unless there are problems sending updates to
1168 the other nodes.
1169
1170
1171 Cluster renaming
1172 ++++++++++++++++
1173
1174 It is possible to rename a cluster, or to change its IP address, via the
1175 ``rename`` command. If only the IP has changed, you need to pass the
1176 current name and Ganeti will realise its IP has changed::
1177
1178   $ gnt-cluster rename %cluster.example.com%
1179   This will rename the cluster to 'cluster.example.com'. If
1180   you are connected over the network to the cluster name, the operation
1181   is very dangerous as the IP address will be removed from the node and
1182   the change may not go through. Continue?
1183   y/[n]/?: %y%
1184   Failure: prerequisites not met for this operation:
1185   Neither the name nor the IP address of the cluster has changed
1186
1187 In the above output, neither value has changed since the cluster
1188 initialisation so the operation is not completed.
1189
1190 Queue operations
1191 ++++++++++++++++
1192
1193 The job queue execution in Ganeti 2.0 and higher can be inspected,
1194 suspended and resumed via the ``queue`` command::
1195
1196   $ gnt-cluster queue info
1197   The drain flag is unset
1198   $ gnt-cluster queue drain
1199   $ gnt-instance stop %instance1%
1200   Failed to submit job for instance1: Job queue is drained, refusing job
1201   $ gnt-cluster queue info
1202   The drain flag is set
1203   $ gnt-cluster queue undrain
1204
1205 This is most useful if you have an active cluster and you need to
1206 upgrade the Ganeti software, or simply restart the software on any node:
1207
1208 #. suspend the queue via ``queue drain``
1209 #. wait until there are no more running jobs via ``gnt-job list``
1210 #. restart the master or another node, or upgrade the software
1211 #. resume the queue via ``queue undrain``
1212
1213 .. note:: this command only stores a local flag file, and if you
1214    failover the master, it will not have effect on the new master.
1215
1216
1217 Watcher control
1218 +++++++++++++++
1219
1220 The :manpage:`ganeti-watcher(8)` is a program, usually scheduled via
1221 ``cron``, that takes care of cluster maintenance operations (restarting
1222 downed instances, activating down DRBD disks, etc.). However, during
1223 maintenance and troubleshooting, this can get in your way; disabling it
1224 via commenting out the cron job is not so good as this can be
1225 forgotten. Thus there are some commands for automated control of the
1226 watcher: ``pause``, ``info`` and ``continue``::
1227
1228   $ gnt-cluster watcher info
1229   The watcher is not paused.
1230   $ gnt-cluster watcher pause %1h%
1231   The watcher is paused until Mon Oct 26 00:30:37 2009.
1232   $ gnt-cluster watcher info
1233   The watcher is paused until Mon Oct 26 00:30:37 2009.
1234   $ ganeti-watcher -d
1235   2009-10-25 23:30:47,984:  pid=28867 ganeti-watcher:486 DEBUG Pause has been set, exiting
1236   $ gnt-cluster watcher continue
1237   The watcher is no longer paused.
1238   $ ganeti-watcher -d
1239   2009-10-25 23:31:04,789:  pid=28976 ganeti-watcher:345 DEBUG Archived 0 jobs, left 0
1240   2009-10-25 23:31:05,884:  pid=28976 ganeti-watcher:280 DEBUG Got data from cluster, writing instance status file
1241   2009-10-25 23:31:06,061:  pid=28976 ganeti-watcher:150 DEBUG Data didn't change, just touching status file
1242   $ gnt-cluster watcher info
1243   The watcher is not paused.
1244
1245 The exact details of the argument to the ``pause`` command are available
1246 in the manpage.
1247
1248 .. note:: this command only stores a local flag file, and if you
1249    failover the master, it will not have effect on the new master.
1250
1251 Node auto-maintenance
1252 +++++++++++++++++++++
1253
1254 If the cluster parameter ``maintain_node_health`` is enabled (see the
1255 manpage for :command:`gnt-cluster`, the init and modify subcommands),
1256 then the following will happen automatically:
1257
1258 - the watcher will shutdown any instances running on offline nodes
1259 - the watcher will deactivate any DRBD devices on offline nodes
1260
1261 In the future, more actions are planned, so only enable this parameter
1262 if the nodes are completely dedicated to Ganeti; otherwise it might be
1263 possible to lose data due to auto-maintenance actions.
1264
1265 Removing a cluster entirely
1266 +++++++++++++++++++++++++++
1267
1268 The usual method to cleanup a cluster is to run ``gnt-cluster destroy``
1269 however if the Ganeti installation is broken in any way then this will
1270 not run.
1271
1272 It is possible in such a case to cleanup manually most if not all traces
1273 of a cluster installation by following these steps on all of the nodes:
1274
1275 1. Shutdown all instances. This depends on the virtualisation method
1276    used (Xen, KVM, etc.):
1277
1278   - Xen: run ``xm list`` and ``xm destroy`` on all the non-Domain-0
1279     instances
1280   - KVM: kill all the KVM processes
1281   - chroot: kill all processes under the chroot mountpoints
1282
1283 2. If using DRBD, shutdown all DRBD minors (which should by at this time
1284    no-longer in use by instances); on each node, run ``drbdsetup
1285    /dev/drbdN down`` for each active DRBD minor.
1286
1287 3. If using LVM, cleanup the Ganeti volume group; if only Ganeti created
1288    logical volumes (and you are not sharing the volume group with the
1289    OS, for example), then simply running ``lvremove -f xenvg`` (replace
1290    'xenvg' with your volume group name) should do the required cleanup.
1291
1292 4. If using file-based storage, remove recursively all files and
1293    directories under your file-storage directory: ``rm -rf
1294    /srv/ganeti/file-storage/*`` replacing the path with the correct path
1295    for your cluster.
1296
1297 5. Stop the ganeti daemons (``/etc/init.d/ganeti stop``) and kill any
1298    that remain alive (``pgrep ganeti`` and ``pkill ganeti``).
1299
1300 6. Remove the ganeti state directory (``rm -rf /var/lib/ganeti/*``),
1301    replacing the path with the correct path for your installation.
1302
1303 7. If using RBD, run ``rbd unmap /dev/rbdN`` to unmap the RBD disks.
1304    Then remove the RBD disk images used by Ganeti, identified by their
1305    UUIDs (``rbd rm uuid.rbd.diskN``).
1306
1307 On the master node, remove the cluster from the master-netdev (usually
1308 ``xen-br0`` for bridged mode, otherwise ``eth0`` or similar), by running
1309 ``ip a del $clusterip/32 dev xen-br0`` (use the correct cluster ip and
1310 network device name).
1311
1312 At this point, the machines are ready for a cluster creation; in case
1313 you want to remove Ganeti completely, you need to also undo some of the
1314 SSH changes and log directories:
1315
1316 - ``rm -rf /var/log/ganeti /srv/ganeti`` (replace with the correct
1317   paths)
1318 - remove from ``/root/.ssh`` the keys that Ganeti added (check the
1319   ``authorized_keys`` and ``id_dsa`` files)
1320 - regenerate the host's SSH keys (check the OpenSSH startup scripts)
1321 - uninstall Ganeti
1322
1323 Otherwise, if you plan to re-create the cluster, you can just go ahead
1324 and rerun ``gnt-cluster init``.
1325
1326 Tags handling
1327 -------------
1328
1329 The tags handling (addition, removal, listing) is similar for all the
1330 objects that support it (instances, nodes, and the cluster).
1331
1332 Limitations
1333 +++++++++++
1334
1335 Note that the set of characters present in a tag and the maximum tag
1336 length are restricted. Currently the maximum length is 128 characters,
1337 there can be at most 4096 tags per object, and the set of characters is
1338 comprised by alphanumeric characters and additionally ``.+*/:@-``.
1339
1340 Operations
1341 ++++++++++
1342
1343 Tags can be added via ``add-tags``::
1344
1345   $ gnt-instance add-tags %INSTANCE% %a% %b% %c%
1346   $ gnt-node add-tags %INSTANCE% %a% %b% %c%
1347   $ gnt-cluster add-tags %a% %b% %c%
1348
1349
1350 The above commands add three tags to an instance, to a node and to the
1351 cluster. Note that the cluster command only takes tags as arguments,
1352 whereas the node and instance commands first required the node and
1353 instance name.
1354
1355 Tags can also be added from a file, via the ``--from=FILENAME``
1356 argument. The file is expected to contain one tag per line.
1357
1358 Tags can also be remove via a syntax very similar to the add one::
1359
1360   $ gnt-instance remove-tags %INSTANCE% %a% %b% %c%
1361
1362 And listed via::
1363
1364   $ gnt-instance list-tags
1365   $ gnt-node list-tags
1366   $ gnt-cluster list-tags
1367
1368 Global tag search
1369 +++++++++++++++++
1370
1371 It is also possible to execute a global search on the all tags defined
1372 in the cluster configuration, via a cluster command::
1373
1374   $ gnt-cluster search-tags %REGEXP%
1375
1376 The parameter expected is a regular expression (see
1377 :manpage:`regex(7)`). This will return all tags that match the search,
1378 together with the object they are defined in (the names being show in a
1379 hierarchical kind of way)::
1380
1381   $ gnt-cluster search-tags %o%
1382   /cluster foo
1383   /instances/instance1 owner:bar
1384
1385
1386 Job operations
1387 --------------
1388
1389 The various jobs submitted by the instance/node/cluster commands can be
1390 examined, canceled and archived by various invocations of the
1391 ``gnt-job`` command.
1392
1393 First is the job list command::
1394
1395   $ gnt-job list
1396   17771 success INSTANCE_QUERY_DATA
1397   17773 success CLUSTER_VERIFY_DISKS
1398   17775 success CLUSTER_REPAIR_DISK_SIZES
1399   17776 error   CLUSTER_RENAME(cluster.example.com)
1400   17780 success CLUSTER_REDIST_CONF
1401   17792 success INSTANCE_REBOOT(instance1.example.com)
1402
1403 More detailed information about a job can be found via the ``info``
1404 command::
1405
1406   $ gnt-job info %17776%
1407   Job ID: 17776
1408     Status: error
1409     Received:         2009-10-25 23:18:02.180569
1410     Processing start: 2009-10-25 23:18:02.200335 (delta 0.019766s)
1411     Processing end:   2009-10-25 23:18:02.279743 (delta 0.079408s)
1412     Total processing time: 0.099174 seconds
1413     Opcodes:
1414       OP_CLUSTER_RENAME
1415         Status: error
1416         Processing start: 2009-10-25 23:18:02.200335
1417         Processing end:   2009-10-25 23:18:02.252282
1418         Input fields:
1419           name: cluster.example.com
1420         Result:
1421           OpPrereqError
1422           [Neither the name nor the IP address of the cluster has changed]
1423         Execution log:
1424
1425 During the execution of a job, it's possible to follow the output of a
1426 job, similar to the log that one get from the ``gnt-`` commands, via the
1427 watch command::
1428
1429   $ gnt-instance add --submit … %instance1%
1430   JobID: 17818
1431   $ gnt-job watch %17818%
1432   Output from job 17818 follows
1433   -----------------------------
1434   Mon Oct 26 00:22:48 2009  - INFO: Selected nodes for instance instance1 via iallocator dumb: node1, node2
1435   Mon Oct 26 00:22:49 2009 * creating instance disks...
1436   Mon Oct 26 00:22:52 2009 adding instance instance1 to cluster config
1437   Mon Oct 26 00:22:52 2009  - INFO: Waiting for instance instance1 to sync disks.
1438   …
1439   Mon Oct 26 00:23:03 2009 creating os for instance instance1 on node node1
1440   Mon Oct 26 00:23:03 2009 * running the instance OS create scripts...
1441   Mon Oct 26 00:23:13 2009 * starting instance...
1442   $
1443
1444 This is useful if you need to follow a job's progress from multiple
1445 terminals.
1446
1447 A job that has not yet started to run can be canceled::
1448
1449   $ gnt-job cancel %17810%
1450
1451 But not one that has already started execution::
1452
1453   $ gnt-job cancel %17805%
1454   Job 17805 is no longer waiting in the queue
1455
1456 There are two queues for jobs: the *current* and the *archive*
1457 queue. Jobs are initially submitted to the current queue, and they stay
1458 in that queue until they have finished execution (either successfully or
1459 not). At that point, they can be moved into the archive queue using e.g.
1460 ``gnt-job autoarchive all``. The ``ganeti-watcher`` script will do this
1461 automatically 6 hours after a job is finished. The ``ganeti-cleaner``
1462 script will then remove archived the jobs from the archive directory
1463 after three weeks.
1464
1465 Note that ``gnt-job list`` only shows jobs in the current queue.
1466 Archived jobs can be viewed using ``gnt-job info <id>``.
1467
1468 Special Ganeti deployments
1469 --------------------------
1470
1471 Since Ganeti 2.4, it is possible to extend the Ganeti deployment with
1472 two custom scenarios: Ganeti inside Ganeti and multi-site model.
1473
1474 Running Ganeti under Ganeti
1475 +++++++++++++++++++++++++++
1476
1477 It is sometimes useful to be able to use a Ganeti instance as a Ganeti
1478 node (part of another cluster, usually). One example scenario is two
1479 small clusters, where we want to have an additional master candidate
1480 that holds the cluster configuration and can be used for helping with
1481 the master voting process.
1482
1483 However, these Ganeti instance should not host instances themselves, and
1484 should not be considered in the normal capacity planning, evacuation
1485 strategies, etc. In order to accomplish this, mark these nodes as
1486 non-``vm_capable``::
1487
1488   $ gnt-node modify --vm-capable=no %node3%
1489
1490 The vm_capable status can be listed as usual via ``gnt-node list``::
1491
1492   $ gnt-node list -oname,vm_capable
1493   Node  VMCapable
1494   node1 Y
1495   node2 Y
1496   node3 N
1497
1498 When this flag is set, the cluster will not do any operations that
1499 relate to instances on such nodes, e.g. hypervisor operations,
1500 disk-related operations, etc. Basically they will just keep the ssconf
1501 files, and if master candidates the full configuration.
1502
1503 Multi-site model
1504 ++++++++++++++++
1505
1506 If Ganeti is deployed in multi-site model, with each site being a node
1507 group (so that instances are not relocated across the WAN by mistake),
1508 it is conceivable that either the WAN latency is high or that some sites
1509 have a lower reliability than others. In this case, it doesn't make
1510 sense to replicate the job information across all sites (or even outside
1511 of a “central” node group), so it should be possible to restrict which
1512 nodes can become master candidates via the auto-promotion algorithm.
1513
1514 Ganeti 2.4 introduces for this purpose a new ``master_capable`` flag,
1515 which (when unset) prevents nodes from being marked as master
1516 candidates, either manually or automatically.
1517
1518 As usual, the node modify operation can change this flag::
1519
1520   $ gnt-node modify --auto-promote --master-capable=no %node3%
1521   Fri Jan  7 06:23:07 2011  - INFO: Demoting from master candidate
1522   Fri Jan  7 06:23:08 2011  - INFO: Promoted nodes to master candidate role: node4
1523   Modified node node3
1524    - master_capable -> False
1525    - master_candidate -> False
1526
1527 And the node list operation will list this flag::
1528
1529   $ gnt-node list -oname,master_capable %node1% %node2% %node3%
1530   Node  MasterCapable
1531   node1 Y
1532   node2 Y
1533   node3 N
1534
1535 Note that marking a node both not ``vm_capable`` and not
1536 ``master_capable`` makes the node practically unusable from Ganeti's
1537 point of view. Hence these two flags should be used probably in
1538 contrast: some nodes will be only master candidates (master_capable but
1539 not vm_capable), and other nodes will only hold instances (vm_capable
1540 but not master_capable).
1541
1542
1543 Ganeti tools
1544 ------------
1545
1546 Beside the usual ``gnt-`` and ``ganeti-`` commands which are provided
1547 and installed in ``$prefix/sbin`` at install time, there are a couple of
1548 other tools installed which are used seldom but can be helpful in some
1549 cases.
1550
1551 lvmstrap
1552 ++++++++
1553
1554 The ``lvmstrap`` tool, introduced in :ref:`configure-lvm-label` section,
1555 has two modes of operation:
1556
1557 - ``diskinfo`` shows the discovered disks on the system and their status
1558 - ``create`` takes all not-in-use disks and creates a volume group out
1559   of them
1560
1561 .. warning:: The ``create`` argument to this command causes data-loss!
1562
1563 cfgupgrade
1564 ++++++++++
1565
1566 The ``cfgupgrade`` tools is used to upgrade between major (and minor)
1567 Ganeti versions. Point-releases are usually transparent for the admin.
1568
1569 More information about the upgrade procedure is listed on the wiki at
1570 http://code.google.com/p/ganeti/wiki/UpgradeNotes.
1571
1572 There is also a script designed to upgrade from Ganeti 1.2 to 2.0,
1573 called ``cfgupgrade12``.
1574
1575 cfgshell
1576 ++++++++
1577
1578 .. note:: This command is not actively maintained; make sure you backup
1579    your configuration before using it
1580
1581 This can be used as an alternative to direct editing of the
1582 main configuration file if Ganeti has a bug and prevents you, for
1583 example, from removing an instance or a node from the configuration
1584 file.
1585
1586 .. _burnin-label:
1587
1588 burnin
1589 ++++++
1590
1591 .. warning:: This command will erase existing instances if given as
1592    arguments!
1593
1594 This tool is used to exercise either the hardware of machines or
1595 alternatively the Ganeti software. It is safe to run on an existing
1596 cluster **as long as you don't pass it existing instance names**.
1597
1598 The command will, by default, execute a comprehensive set of operations
1599 against a list of instances, these being:
1600
1601 - creation
1602 - disk replacement (for redundant instances)
1603 - failover and migration (for redundant instances)
1604 - move (for non-redundant instances)
1605 - disk growth
1606 - add disks, remove disk
1607 - add NICs, remove NICs
1608 - export and then import
1609 - rename
1610 - reboot
1611 - shutdown/startup
1612 - and finally removal of the test instances
1613
1614 Executing all these operations will test that the hardware performs
1615 well: the creation, disk replace, disk add and disk growth will exercise
1616 the storage and network; the migrate command will test the memory of the
1617 systems. Depending on the passed options, it can also test that the
1618 instance OS definitions are executing properly the rename, import and
1619 export operations.
1620
1621 sanitize-config
1622 +++++++++++++++
1623
1624 This tool takes the Ganeti configuration and outputs a "sanitized"
1625 version, by randomizing or clearing:
1626
1627 - DRBD secrets and cluster public key (always)
1628 - host names (optional)
1629 - IPs (optional)
1630 - OS names (optional)
1631 - LV names (optional, only useful for very old clusters which still have
1632   instances whose LVs are based on the instance name)
1633
1634 By default, all optional items are activated except the LV name
1635 randomization. When passing ``--no-randomization``, which disables the
1636 optional items (i.e. just the DRBD secrets and cluster public keys are
1637 randomized), the resulting file can be used as a safety copy of the
1638 cluster config - while not trivial, the layout of the cluster can be
1639 recreated from it and if the instance disks have not been lost it
1640 permits recovery from the loss of all master candidates.
1641
1642 move-instance
1643 +++++++++++++
1644
1645 See :doc:`separate documentation for move-instance <move-instance>`.
1646
1647 .. TODO: document cluster-merge tool
1648
1649
1650 Other Ganeti projects
1651 ---------------------
1652
1653 Below is a list (which might not be up-to-date) of additional projects
1654 that can be useful in a Ganeti deployment. They can be downloaded from
1655 the project site (http://code.google.com/p/ganeti/) and the repositories
1656 are also on the project git site (http://git.ganeti.org).
1657
1658 NBMA tools
1659 ++++++++++
1660
1661 The ``ganeti-nbma`` software is designed to allow instances to live on a
1662 separate, virtual network from the nodes, and in an environment where
1663 nodes are not guaranteed to be able to reach each other via multicasting
1664 or broadcasting. For more information see the README in the source
1665 archive.
1666
1667 ganeti-htools
1668 +++++++++++++
1669
1670 Before Ganeti version 2.5, this was a standalone project; since that
1671 version it is integrated into the Ganeti codebase (see
1672 :doc:`install-quick` for instructions on how to enable it). If you run
1673 an older Ganeti version, you will have to download and build it
1674 separately.
1675
1676 For more information and installation instructions, see the README file
1677 in the source archive.
1678
1679 .. vim: set textwidth=72 :
1680 .. Local Variables:
1681 .. mode: rst
1682 .. fill-column: 72
1683 .. End: