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="opt">-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>ACTIVATE-DISKS</title>
902 <command>activate-disks</command>
903 <arg choice="req"><replaceable>instance</replaceable></arg>
906 Activates the block devices of the given instance. If
907 successful, the command will show the location and name of
910 node1.example.com:sda:/dev/md0
911 node1.example.com:sdb:/dev/md1
914 In this example, <emphasis>node1.example.com</emphasis> is
915 the name of the node on which the devices have been
916 activated. The <emphasis>sda</emphasis> and
917 <emphasis>sdb</emphasis> are the names of the block devices
918 inside the instance. <emphasis>/dev/md0</emphasis> and
919 <emphasis>/dev/md1</emphasis> are the names of the block
920 devices as visible on the node.
924 Note that it is safe to run this command while the instance
930 <title>DEACTIVATE-DISKS</title>
933 <command>deactivate-disks</command>
934 <arg choice="req"><replaceable>instance</replaceable></arg>
937 De-activates the block devices of the given instance. Note
938 that if you run this command for a remote raid instance
939 type, while it is running, it will not be able to shutdown
940 the block devices on the primary node, but it will shutdown
941 the block devices on the secondary nodes, thus breaking the
950 <title>Recovery</title>
953 <title>FAILOVER</title>
956 <command>failover</command>
958 <arg>--ignore-consistency</arg>
959 <arg choice="req"><replaceable>instance</replaceable></arg>
963 Failover will fail the instance over its secondary
964 node. This works only for instances having a remote raid
969 Normally the failover will check the consistency of the
970 disks before failing over the instance. If you are trying to
971 migrate instances off a dead node, this will fail. Use the
972 <option>--ignore-consistency</option> option for this
973 purpose. Note that this option can be dangerous as errors in
974 shutting down the instance will be ignored, resulting in
975 possibly having the instance running on two machines in
976 parallel (on disconnected DRBD drives).
982 # gnt-instance failover instance1.example.com
993 <title>ADD-TAGS</title>
996 <command>add-tags</command>
997 <arg choice="opt">--from <replaceable>file</replaceable></arg>
998 <arg choice="req"><replaceable>instancename</replaceable></arg>
1000 rep="repeat"><replaceable>tag</replaceable></arg>
1004 Add tags to the given instance. If any of the tags contains
1005 invalid characters, the entire operation will abort.
1008 If the <option>--from</option> option is given, the list of
1009 tags will be extended with the contents of that file (each
1010 line becomes a tag). In this case, there is not need to pass
1011 tags on the command line (if you do, both sources will be
1012 used). A file name of - will be interpreted as stdin.
1017 <title>LIST-TAGS</title>
1020 <command>list-tags</command>
1021 <arg choice="req"><replaceable>instancename</replaceable></arg>
1024 <para>List the tags of the given instance.</para>
1028 <title>REMOVE-TAGS</title>
1030 <command>remove-tags</command>
1031 <arg choice="opt">--from <replaceable>file</replaceable></arg>
1032 <arg choice="req"><replaceable>instancename</replaceable></arg>
1034 rep="repeat"><replaceable>tag</replaceable></arg>
1038 Remove tags from the given instance. If any of the tags are
1039 not existing on the node, the entire operation will abort.
1043 If the <option>--from</option> option is given, the list of
1044 tags will be extended with the contents of that file (each
1045 line becomes a tag). In this case, there is not need to pass
1046 tags on the command line (if you do, both sources will be
1047 used). A file name of - will be interpreted as stdin.
1059 <!-- Keep this comment at the end of the file
1064 sgml-minimize-attributes:nil
1065 sgml-always-quote-attributes:t
1068 sgml-parent-document:nil
1069 sgml-default-dtd-file:nil
1070 sgml-exposed-tags:nil
1071 sgml-local-catalogs:nil
1072 sgml-local-ecat-files:nil