1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
3 <!-- Fill in your name for FIRSTNAME and SURNAME. -->
4 <!-- Please adjust the date whenever revising the manpage. -->
5 <!ENTITY dhdate "<date>May 16, 2007</date>">
6 <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
7 allowed: see man(7), man(1). -->
8 <!ENTITY dhsection "<manvolnum>8</manvolnum>">
9 <!ENTITY dhucpackage "<refentrytitle>gnt-instance</refentrytitle>">
10 <!ENTITY dhpackage "gnt-instance">
12 <!ENTITY debian "<productname>Debian</productname>">
13 <!ENTITY gnu "<acronym>GNU</acronym>">
14 <!ENTITY gpl "&gnu; <acronym>GPL</acronym>">
15 <!ENTITY footer SYSTEM "footer.sgml">
23 <holder>Google Inc.</holder>
31 <refmiscinfo>ganeti 1.2</refmiscinfo>
34 <refname>&dhpackage;</refname>
36 <refpurpose>ganeti instance administration</refpurpose>
40 <command>&dhpackage; </command>
42 <arg choice="req">command</arg>
43 <arg>arguments...</arg>
47 <title>DESCRIPTION</title>
50 The <command>&dhpackage;</command> is used for instance
51 administration in the ganeti system.
56 <title>COMMANDS</title>
59 <title>Creation/removal/querying</title>
64 <command>add</command>
65 <arg>-s <replaceable>disksize</replaceable></arg>
66 <arg>--swap-size <replaceable>disksize</replaceable></arg>
67 <arg>-m <replaceable>memsize</replaceable></arg>
69 <arg>-o <replaceable>os-type</replaceable></arg>
70 <arg>-b <replaceable>bridge</replaceable></arg>
71 <arg>--mac <replaceable>MAC-address</replaceable></arg>
72 <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
74 <arg>--kernel <group choice="req">
76 <arg><replaceable>kernel_path</replaceable></arg>
79 <arg>--initrd <group choice="req">
82 <arg><replaceable>initrd_path</replaceable></arg>
85 <arg choice="req">-t<group>
88 <arg>local_raid1</arg>
89 <arg>remote_raid1</arg>
94 <arg choice="req">-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
95 <arg choice="req"><replaceable>instance</replaceable></arg>
99 Creates a new instance on the specified
100 host. <replaceable>instance</replaceable> must be in DNS and
101 resolve to a IP in the same network as the nodes in the
106 The <option>-s</option> option specifies the disk size for
107 the instance, in mebibytes (defaults to
108 <constant>20480MiB</constant> =
109 <constant>20GiB</constant>). You can also use one of the
110 suffixes <literal>m</literal>, <literal>g</literal> or
111 <literal>t</literal> to specificy the exact the units used;
112 these suffixes map to mebibytes, gibibytes and tebibytes.
116 The <option>--swap-size</option> option specifies the swap
117 disk size (in mebibytes) for the instance (the one presented
118 as <filename class="devicefile">/dev/sdb</filename>). The
119 default is <constant>4096MiB</constant>. As for the disk
120 size, you can specify other suffixes.
124 The <option>-m</option> option specifies the memory size for
125 the instance, in mebibytes (defaults to 128 MiB). Again, you
126 can use other suffixes (e.g. <userinput>2g</userinput>).
130 The <option>-o</option> options specifies the operating
131 system to be installed. The available operating systems can
132 be listed with <command>gnt-os list</command>.
136 The <option>-b</option> option specifies the bridge to which the
137 instance will be connected. (defaults to the cluster-wide default
138 bridge specified at cluster initialization time).
142 The <option>--mac</option> option specifies the MAC address
143 of the ethernet interface for the instance. If this option
144 is not specified, a new MAC address is generated randomly with
145 the configured MAC prefix. The randomly generated MAC
146 address is guaranteed to be unique among the instances of
151 The <option>--hvm-boot-order</option> option specifies the
152 boot device order for Xen HVM instances. The boot order is a
153 string of letters listing the boot devices, with valid
154 device letters being:
195 The option is only relevant for Xen HVM instances and
196 ignored by all other instances types.
200 The <option>--kernel</option> options allows the instance to
201 use a custom kernel (if a filename is passed) or to use the
202 default kernel (<filename>@CUSTOM_XEN_KERNEL@</filename>), if the
203 string <constant>default</constant> is passed.
207 The <option>--initrd</option> option is similar: it allows
208 the instance to use a custom initrd (if a filename is
209 passed) or to use the default initrd
210 (<filename>@CUSTOM_XEN_INITRD@</filename>), if the string
211 <constant>default</constant> is passed, or to disable the
212 use of an initrd, if the string <constant>none</constant> is
213 passed. Note that in the case the instance is set to use the
214 default initrd and it doesn't exist, it will be silently
215 ignored; if the instance is set to use a custom initrd and
216 it doesn't exist, this will be treated as an error and will
217 prevent the startup of the instance.
221 The <option>-t</option> options specifies the disk layout type for
222 the instance. The available choices are:
225 <term>diskless</term>
228 This creates an instance with no disks. Its useful for
229 testing only (or other special cases).
236 <para>Disk devices will be logical volumes.</para>
240 <term>local_raid1</term>
243 Disk devices will be md raid1 arrays over two local
249 <term>remote_raid1</term>
252 Disk devices will be md raid1 arrays with one
253 component (so it's not actually raid1): a drbd
254 (0.7.x) device between the instance's primary node
255 and the node given by the second value of the
256 <option>--node</option> option.
264 Disk devices will be drbd (version 8.x) on top of
265 lvm volumes. They are equivalent in functionality to
266 <replaceable>remote_raid1</replaceable>, but are
267 recommended for new instances (if you have drbd 8.x
276 The optional second value of the <option>--node</option> is used for
277 the remote raid template type and specifies the remote node.
281 If you do not want gnt-instance to wait for the disk mirror
282 to be synced, use the <option>--no-wait-for-sync</option>
289 # gnt-instance add -t plain -s 30g -m 512 -o debian-etch \
290 -n node1.example.com instance1.example.com
291 # gnt-instance add -t remote_raid1 -s 30g -m 512 -o debian-etch \
292 -n node1.example.com:node2.example.com instance2.example.com
298 <title>REMOVE</title>
301 <command>remove</command>
302 <arg>--ignore-failures</arg>
303 <arg choice="req"><replaceable>instance</replaceable></arg>
307 Remove an instance. This will remove all data from the
308 instance and there is <emphasis>no way back</emphasis>. If
309 you are not sure if you use an instance again, use
310 <command>shutdown</command> first and leave it in the
311 shutdown state for a while.
316 The <option>--ignore-failures</option> option will cause the
317 removal to proceed even in the presence of errors during the
318 removal of the instance (e.g. during the shutdown or the
319 disk removal). If this option is not given, the command will
320 stop at the first error.
326 # gnt-instance remove instance1.example.com
335 <command>list</command>
336 <arg>--no-headers</arg>
337 <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
338 <arg>-o <replaceable>FIELD,...</replaceable></arg>
342 Shows the currently configured instances with memory usage,
343 disk usage, the node they are running on, and the CPU time,
344 counted in seconds, used by each instance since its latest
349 The <option>--no-headers</option> option will skip the
350 initial header line. The <option>--separator</option> option
351 takes an argument which denotes what will be used between
352 the output fields. Both these options are to help scripting.
356 The <option>-o</option> option takes a comma-separated list
357 of output fields. The available fields and their meaning
363 <simpara>the instance name</simpara>
369 <simpara>the OS of the instance</simpara>
375 <simpara>the primary node of the instance</simpara>
381 <simpara>comma-separated list of secondary nodes for the
382 instance; usually this will be just one node</simpara>
386 <term>admin_state</term>
388 <simpara>the desired state of the instance (either "yes"
389 or "no" denoting the instance should run or
394 <term>admin_ram</term>
396 <simpara>the desired memory for the instance</simpara>
400 <term>disk_template</term>
402 <simpara>the disk template of the instance</simpara>
406 <term>oper_state</term>
408 <simpara>the actual state of the instance; can be
409 one of the values "running", "stopped", "(node
416 <simpara>combined form of admin_state and oper_stat;
418 <computeroutput>ERROR_nodedown</computeroutput> if the
419 node of the instance is down,
420 <computeroutput>ERROR_down</computeroutput> if the
421 instance should run but is down,
422 <computeroutput>ERROR_up</computeroutput> if the
423 instance should be stopped but is actually running,
424 <computeroutput>ADMIN_down</computeroutput> if the
425 instance has been stopped (and is stopped) and
426 <computeroutput>running</computeroutput> if the
427 instance is set to be running (and is
432 <term>oper_ram</term>
434 <simpara>the actual memory usage of the instance as seen
435 by the hypervisor</simpara>
441 <simpara>the ip address ganeti recognizes as associated with
442 the instance interface</simpara>
448 <simpara>the instance interface MAC address</simpara>
454 <simpara>bridge the instance is connected to
459 <term>sda_size</term>
461 <simpara>the size of the instance's first disk</simpara>
465 <term>sdb_size</term>
467 <simpara>the size of the instance's second disk</simpara>
473 <simpara>the number of VCPUs allocated to the
481 There is a subtle grouping about the available output
482 fields: all fields except for <option>oper_state</option>
483 and <option>oper_ram</option> are configuration value and
484 not run-time values. So if you don't select any of the
485 <option>oper_*</option> fields, the query will be satisfied
486 instantly from the cluster configuration, without having to
487 ask the remote nodes for the data. This can be helpful for
488 big clusters when you only want some data and it makes sense
489 to specify a reduced set of output fields.
492 <para>The default output field list is:
493 <simplelist type="inline">
494 <member>name</member>
496 <member>pnode</member>
497 <member>admin_state</member>
498 <member>oper_state</member>
499 <member>oper_ram</member>
508 <command>info</command>
509 <arg rep="repeat"><replaceable>instance</replaceable></arg>
513 Show detailed information about the (given) instances. This
514 is different from <command>list</command> as it shows
515 detailed data about the instance's disks (especially useful
516 for remote raid templates).
521 <title>MODIFY</title>
524 <command>modify</command>
525 <arg choice="opt">-m <replaceable>memsize</replaceable></arg>
526 <arg choice="opt">-p <replaceable>vcpus</replaceable></arg>
527 <arg choice="opt">-i <replaceable>ip</replaceable></arg>
528 <arg choice="opt">-b <replaceable>bridge</replaceable></arg>
529 <arg choice="opt">--mac <replaceable>MAC-address</replaceable></arg>
530 <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
532 <arg>--kernel <group choice="req">
534 <arg><replaceable>kernel_path</replaceable></arg>
537 <arg>--initrd <group choice="req">
540 <arg><replaceable>initrd_path</replaceable></arg>
543 <arg choice="req"><replaceable>instance</replaceable></arg>
547 Modify the memory size, number of vcpus, ip address, MAC
548 address and/or bridge for an instance.
552 The memory size is given in MiB. Note that you need to give
553 at least one of the arguments, otherwise the command
558 The <option>--kernel</option>, <option>--initrd</option>
559 and <option>--hvm-boot-order</option>
560 options are described in the <command>add</command> command.
564 Additionally, the HVM boot order can be reset to the default
565 values by using <option>--hvm-boot-order=default</option>.
569 All the changes take effect at the next restart. If the
570 instance is running, there is no effect on the instance.
575 <title>REINSTALL</title>
578 <command>reinstall</command>
579 <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
580 <arg choice="opt">-f <replaceable>force</replaceable></arg>
581 <arg choice="req"><replaceable>instance</replaceable></arg>
585 Reinstalls the operating system on the given instance. The instance
586 must be stopped when running this command. If the
587 <option>--os-type</option> is specified, the operating system is
593 <title>RENAME</title>
596 <command>rename</command>
597 <arg>--no-ip-check</arg>
598 <arg choice="req"><replaceable>instance</replaceable></arg>
599 <arg choice="req"><replaceable>new_name</replaceable></arg>
603 Renames the given instance. The instance must be stopped
604 when running this command. The requirements for the new name
605 are the same as for adding an instance: the new name must be
606 resolvable and the IP it resolves to must not be reachable
607 (in order to prevent duplicate IPs the next time the
608 instance is started). The IP test can be skipped if the
609 <option>--no-ip-check</option> option is passed.
616 <title>Starting/stopping/connecting to console</title>
619 <title>STARTUP</title>
622 <command>startup</command>
623 <arg>--extra=<replaceable>PARAMS</replaceable></arg>
627 <arg>--instance</arg>
630 <arg>--secondary</arg>
635 rep="repeat"><replaceable>name</replaceable></arg>
639 Starts one or more instances, depending on the following
640 options. The four available modes are:
643 <term><option>--instance</option></term>
645 <simpara>will start the instances given as arguments
646 (at least one argument required); this is the default
653 <simpara>will start the instances who have the given
654 node as either primary or secondary</simpara>
658 <term><option>--primary</option></term>
660 <simpara>will start all instances whose primary node
661 is in the list of nodes passed as arguments (at least
662 one node required)</simpara>
666 <term><option>--secondary</option></term>
668 <simpara>will start all instances whose secondary node
669 is in the list of nodes passed as arguments (at least
670 one node required)</simpara>
676 <simpara>will start all instances in the cluster (no
677 arguments accepted)</simpara>
684 Note that although you can pass more than one selection
685 option, the last one wins, so in order to guarantee the
686 desired result, don't pass more than one such option.
690 The <option>--extra</option> option is used to pass
691 additional argument to the instance's kernel for this start
692 only. Currently there is no way to specify a persistent set
693 of arguments (beside the one hardcoded). Note that this may
694 not apply to all virtualization types.
698 Use <option>--force</option> to start even if secondary disks are
705 # gnt-instance start instance1.example.com
706 # gnt-instance start --extra single test1.example.com
707 # gnt-instance start --node node1.example.com node2.example.com
708 # gnt-instance start --all
714 <title>SHUTDOWN</title>
717 <command>shutdown</command>
720 <arg>--instance</arg>
723 <arg>--secondary</arg>
729 rep="repeat"><replaceable>name</replaceable></arg>
733 Stops one or more instances. If the instance cannot be
734 cleanly stopped during a hardcoded interval (currently 2
735 minutes), it will forcibly stop the instance (equivalent to
736 switching off the power on a physical machine).
740 The <option>--instance</option>, <option>--node</option>,
741 <option>--primary</option>, <option>--secondary</option> and
742 <option>--all</option> options are similar as for the
743 <command>startup</command> command and they influence the
744 actual instances being shutdown.
750 # gnt-instance shutdown instance1.example.com
751 # gnt-instance shutdown --all
757 <title>REBOOT</title>
760 <command>reboot</command>
762 <arg>--extra=<replaceable>PARAMS</replaceable></arg>
764 <arg>--type=<replaceable>REBOOT-TYPE</replaceable></arg>
766 <arg>--ignore-secondaries</arg>
768 <arg>--force-multiple</arg>
771 <arg>--instance</arg>
774 <arg>--secondary</arg>
780 rep="repeat"><replaceable>name</replaceable></arg>
784 Reboots one or more instances. The type of reboot depends on
785 the value of <option>--type</option>. A soft reboot does a
786 hypervisor reboot, a hard reboot does a instance stop,
787 recreates the hypervisor config for the instance and
788 starts the instance. A full reboot does the equivalent
789 of <command>gnt-instance shutdown && gnt-instance
790 startup</command>. The default is soft reboot.
794 For the hard reboot the option
795 <option>--ignore-secondaries</option> ignores errors for the
796 secondary node while re-assembling the instance disks.
800 The <option>--instance</option>, <option>--node</option>,
801 <option>--primary</option>, <option>--secondary</option> and
802 <option>--all</option> options are similar as for the
803 <command>startup</command> command and they influence the
804 actual instances being rebooted.
808 Use the <option>--force-multiple</option> option to keep
809 gnt-instance from asking for confirmation when more than one
810 instance is affected.
816 # gnt-instance reboot instance1.example.com
817 # gnt-instance reboot --type=full instance1.example.com
823 <title>CONSOLE</title>
825 <command>console</command>
826 <arg choice="req"><replaceable>instance</replaceable></arg>
830 Connects to the console of the given instance. If the instance
831 is not up, an error is returned.
837 # gnt-instance console instance1.example.com
845 <title>Disk management</title>
848 <title>REPLACE-DISKS</title>
851 <command>replace-disks</command>
852 <arg choice="opt">--new-secondary <replaceable>NODE</replaceable></arg>
853 <arg choice="req"><replaceable>instance</replaceable></arg>
857 <command>replace-disks</command>
858 <arg choice="req">-s</arg>
859 <arg choice="req">--new-secondary <replaceable>NODE</replaceable></arg>
860 <arg choice="req"><replaceable>instance</replaceable></arg>
864 <command>replace-disks</command>
866 <arg choice="req">-s</arg>
867 <arg choice="req">-p</arg>
869 <arg choice="req"><replaceable>instance</replaceable></arg>
873 This command is a generalized form for adding and replacing
878 The first form is usable with the
879 <literal>remote_raid1</literal> disk template. This will
880 replace the disks on both the primary and secondary node,
881 and optionally will change the secondary node to a new one
882 if you pass the <option>--new-secondary</option> option.
886 The second and third forms are usable with the
887 <literal>drbd</literal> disk template. The second form will
888 do a secondary replacement, but as opposed to the
889 <literal>remote_raid1</literal> will not replace the disks
890 on the primary, therefore it will execute faster. The third
891 form will replace the disks on either the primary
892 (<option>-p</option>) or the secondary (<option>-s</option>)
893 node of the instance only, without changing the node.
899 <title>ADD-MIRROR</title>
901 <command>add-mirror</command>
902 <arg choice="req">-b <replaceable>sdX</replaceable></arg>
903 <arg choice="req">-n <replaceable>node</replaceable></arg>
904 <arg choice="req"><replaceable>instance</replaceable></arg>
907 Adds a new mirror to the disk layout of the instance, if the
908 instance has a remote raid disk layout.
910 The new mirror member will be between the instance's primary
911 node and the node given with the <option>-n</option> option.
916 <title>REMOVE-MIRROR</title>
919 <command>removemirror</command>
920 <arg choice="req">-b <replaceable>sdX</replaceable></arg>
921 <arg choice="req">-p <replaceable>id</replaceable></arg>
922 <arg choice="req"><replaceable>instance</replaceable></arg>
925 Removes a mirror componenent from the disk layout of the
926 instance, if the instance has a remote raid disk layout.
930 You need to specifiy on which disk to act on using the
931 <option>-b</option> option (either <filename>sda</filename>
932 or <filename>sdb</filename>) and the mirror component, which
933 is identified by the <option>-p</option> option. You can
934 find the list of valid identifiers with the
935 <command>info</command> command.
939 <title>ACTIVATE-DISKS</title>
942 <command>activate-disks</command>
943 <arg choice="req"><replaceable>instance</replaceable></arg>
946 Activates the block devices of the given instance. If
947 successful, the command will show the location and name of
950 node1.example.com:sda:/dev/md0
951 node1.example.com:sdb:/dev/md1
954 In this example, <emphasis>node1.example.com</emphasis> is
955 the name of the node on which the devices have been
956 activated. The <emphasis>sda</emphasis> and
957 <emphasis>sdb</emphasis> are the names of the block devices
958 inside the instance. <emphasis>/dev/md0</emphasis> and
959 <emphasis>/dev/md1</emphasis> are the names of the block
960 devices as visible on the node.
964 Note that it is safe to run this command while the instance
970 <title>DEACTIVATE-DISKS</title>
973 <command>deactivate-disks</command>
974 <arg choice="req"><replaceable>instance</replaceable></arg>
977 De-activates the block devices of the given instance. Note
978 that if you run this command for a remote raid instance
979 type, while it is running, it will not be able to shutdown
980 the block devices on the primary node, but it will shutdown
981 the block devices on the secondary nodes, thus breaking the
990 <title>Recovery</title>
993 <title>FAILOVER</title>
996 <command>failover</command>
998 <arg>--ignore-consistency</arg>
999 <arg choice="req"><replaceable>instance</replaceable></arg>
1003 Failover will fail the instance over its secondary
1004 node. This works only for instances having a remote raid
1009 Normally the failover will check the consistency of the
1010 disks before failing over the instance. If you are trying to
1011 migrate instances off a dead node, this will fail. Use the
1012 <option>--ignore-consistency</option> option for this
1013 purpose. Note that this option can be dangerous as errors in
1014 shutting down the instance will be ignored, resulting in
1015 possibly having the instance running on two machines in
1016 parallel (on disconnected DRBD drives).
1022 # gnt-instance failover instance1.example.com
1033 <title>ADD-TAGS</title>
1036 <command>add-tags</command>
1037 <arg choice="opt">--from <replaceable>file</replaceable></arg>
1038 <arg choice="req"><replaceable>instancename</replaceable></arg>
1040 rep="repeat"><replaceable>tag</replaceable></arg>
1044 Add tags to the given instance. If any of the tags contains
1045 invalid characters, the entire operation will abort.
1048 If the <option>--from</option> option is given, the list of
1049 tags will be extended with the contents of that file (each
1050 line becomes a tag). In this case, there is not need to pass
1051 tags on the command line (if you do, both sources will be
1052 used). A file name of - will be interpreted as stdin.
1057 <title>LIST-TAGS</title>
1060 <command>list-tags</command>
1061 <arg choice="req"><replaceable>instancename</replaceable></arg>
1064 <para>List the tags of the given instance.</para>
1068 <title>REMOVE-TAGS</title>
1070 <command>remove-tags</command>
1071 <arg choice="opt">--from <replaceable>file</replaceable></arg>
1072 <arg choice="req"><replaceable>instancename</replaceable></arg>
1074 rep="repeat"><replaceable>tag</replaceable></arg>
1078 Remove tags from the given instance. If any of the tags are
1079 not existing on the node, the entire operation will abort.
1083 If the <option>--from</option> option is given, the list of
1084 tags will be extended with the contents of that file (each
1085 line becomes a tag). In this case, there is not need to pass
1086 tags on the command line (if you do, both sources will be
1087 used). A file name of - will be interpreted as stdin.
1099 <!-- Keep this comment at the end of the file
1104 sgml-minimize-attributes:nil
1105 sgml-always-quote-attributes:t
1108 sgml-parent-document:nil
1109 sgml-default-dtd-file:nil
1110 sgml-exposed-tags:nil
1111 sgml-local-catalogs:nil
1112 sgml-local-ecat-files:nil