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>
70 <arg>-b <replaceable>bridge</replaceable></arg>
71 <arg>--mac <replaceable>MAC-address</replaceable></arg>
74 <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
77 <arg>--kernel<group choice="req">
79 <arg><replaceable>kernel_path</replaceable></arg>
83 <arg>--initrd<group choice="req">
86 <arg><replaceable>initrd_path</replaceable></arg>
90 <arg>--file-storage-dir <replaceable>dir_path</replaceable></arg>
91 <arg>--file-driver<group choice="req">
97 <arg choice="req">-t<group choice="req">
105 <arg choice="req">-n <replaceable>node<optional>:secondary-node</optional></replaceable></arg>
106 <arg choice="req">-o <replaceable>os-type</replaceable></arg>
109 <arg choice="req"><replaceable>instance</replaceable></arg>
113 Creates a new instance on the specified
114 host. <replaceable>instance</replaceable> must be in DNS and
115 resolve to a IP in the same network as the nodes in the
120 The <option>-s</option> option specifies the disk size for
121 the instance, in mebibytes (defaults to
122 <constant>20480MiB</constant> =
123 <constant>20GiB</constant>). You can also use one of the
124 suffixes <literal>m</literal>, <literal>g</literal> or
125 <literal>t</literal> to specificy the exact the units used;
126 these suffixes map to mebibytes, gibibytes and tebibytes.
130 The <option>--swap-size</option> option specifies the swap
131 disk size (in mebibytes) for the instance (the one presented
132 as <filename class="devicefile">/dev/sdb</filename>). The
133 default is <constant>4096MiB</constant>. As for the disk
134 size, you can specify other suffixes.
138 The <option>-m</option> option specifies the memory size for
139 the instance, in mebibytes (defaults to 128 MiB). Again, you
140 can use other suffixes (e.g. <userinput>2g</userinput>).
144 The <option>-o</option> options specifies the operating
145 system to be installed. The available operating systems can
146 be listed with <command>gnt-os list</command>.
150 The <option>-b</option> option specifies the bridge to which the
151 instance will be connected. (defaults to the cluster-wide default
152 bridge specified at cluster initialization time).
156 The <option>--mac</option> option specifies the MAC address
157 of the ethernet interface for the instance. If this option
158 is not specified, a new MAC address is generated randomly with
159 the configured MAC prefix. The randomly generated MAC
160 address is guaranteed to be unique among the instances of
165 The <option>--hvm-boot-order</option> option specifies the
166 boot device order for Xen HVM instances. The boot order is a
167 string of letters listing the boot devices, with valid
168 device letters being:
209 The option is only relevant for Xen HVM instances and
210 ignored by all other instances types.
214 The <option>--kernel</option> options allows the instance to
215 use a custom kernel (if a filename is passed) or to use the
216 default kernel (<filename>@CUSTOM_XEN_KERNEL@</filename>), if the
217 string <constant>default</constant> is passed.
221 The <option>--initrd</option> option is similar: it allows
222 the instance to use a custom initrd (if a filename is
223 passed) or to use the default initrd
224 (<filename>@CUSTOM_XEN_INITRD@</filename>), if the string
225 <constant>default</constant> is passed, or to disable the
226 use of an initrd, if the string <constant>none</constant> is
227 passed. Note that in the case the instance is set to use the
228 default initrd and it doesn't exist, it will be silently
229 ignored; if the instance is set to use a custom initrd and
230 it doesn't exist, this will be treated as an error and will
231 prevent the startup of the instance.
235 The <option>-t</option> options specifies the disk layout type for
236 the instance. The available choices are:
239 <term>diskless</term>
242 This creates an instance with no disks. Its useful for
243 testing only (or other special cases).
250 <para>Disk devices will be regular files.</para>
256 <para>Disk devices will be logical volumes.</para>
263 Disk devices will be drbd (version 8.x) on top of
272 The optional second value of the <option>--node</option> is used for
273 the remote raid template type and specifies the remote node.
277 If you do not want gnt-instance to wait for the disk mirror
278 to be synced, use the <option>--no-wait-for-sync</option>
283 The <option>--file-storage-dir</option> specifies the relative path
284 under the cluster-wide file storage directory to store file-based
285 disks. It is useful for having different subdirectories for
286 different instances. The full path of the directory where the disk
287 files are stored will consist of cluster-wide file storage directory
288 + optional subdirectory + instance name. Example:
289 /srv/ganeti/file-storage/mysubdir/instance1.example.com. This option
290 is only relevant for instances using the file storage backend.
294 The <option>--file-driver</option> specifies the driver to use for
295 file-based disks. Note that currently these drivers work with the
296 xen hypervisor only. This option is only relevant for instances using
297 the file storage backend. The available choices are:
302 <para>Kernel loopback driver.</para>
308 <para>blktap driver.</para>
315 The loop driver uses loopback devices to access the filesystem
316 within the file. However, running I/O intensive applications
317 in your instance using the loop driver might result in slowdowns.
318 Furthermore, if you use the loopback driver consider increasing
319 the maximum amount of loopback devices (on most systems it's 8)
320 using the max_loop param.
324 In order to be able to use the blktap driver you should check
325 if the 'blktapctrl' user space disk agent is running (usually
326 automatically started via xend). This user-level disk I/O
327 interface has the advantage of better performance. Especially
328 if you use a network file system (e.g. NFS) to store your instances
329 this is the recommended choice.
335 # gnt-instance add -t file -s 30g -m 512 -o debian-etch \
336 -n node1.example.com --file-storage-dir=mysubdir instance1.example.com
337 # gnt-instance add -t plain -s 30g -m 512 -o debian-etch \
338 -n node1.example.com instance1.example.com
339 # gnt-instance add -t drbd -s 30g -m 512 -o debian-etch \
340 -n node1.example.com:node2.example.com instance2.example.com
346 <title>REMOVE</title>
349 <command>remove</command>
350 <arg>--ignore-failures</arg>
351 <arg choice="req"><replaceable>instance</replaceable></arg>
355 Remove an instance. This will remove all data from the
356 instance and there is <emphasis>no way back</emphasis>. If
357 you are not sure if you use an instance again, use
358 <command>shutdown</command> first and leave it in the
359 shutdown state for a while.
364 The <option>--ignore-failures</option> option will cause the
365 removal to proceed even in the presence of errors during the
366 removal of the instance (e.g. during the shutdown or the
367 disk removal). If this option is not given, the command will
368 stop at the first error.
374 # gnt-instance remove instance1.example.com
383 <command>list</command>
384 <arg>--no-headers</arg>
385 <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
386 <arg>-o <replaceable>[+]FIELD,...</replaceable></arg>
390 Shows the currently configured instances with memory usage,
391 disk usage, the node they are running on, and the CPU time,
392 counted in seconds, used by each instance since its latest
397 The <option>--no-headers</option> option will skip the
398 initial header line. The <option>--separator</option> option
399 takes an argument which denotes what will be used between
400 the output fields. Both these options are to help scripting.
404 The <option>-o</option> option takes a comma-separated list
405 of output fields. The available fields and their meaning
411 <simpara>the instance name</simpara>
417 <simpara>the OS of the instance</simpara>
423 <simpara>the primary node of the instance</simpara>
429 <simpara>comma-separated list of secondary nodes for the
430 instance; usually this will be just one node</simpara>
434 <term>admin_state</term>
436 <simpara>the desired state of the instance (either "yes"
437 or "no" denoting the instance should run or
442 <term>admin_ram</term>
444 <simpara>the desired memory for the instance</simpara>
448 <term>disk_template</term>
450 <simpara>the disk template of the instance</simpara>
454 <term>oper_state</term>
456 <simpara>the actual state of the instance; can be
457 one of the values "running", "stopped", "(node
464 <simpara>combined form of admin_state and oper_stat;
466 <computeroutput>ERROR_nodedown</computeroutput> if the
467 node of the instance is down,
468 <computeroutput>ERROR_down</computeroutput> if the
469 instance should run but is down,
470 <computeroutput>ERROR_up</computeroutput> if the
471 instance should be stopped but is actually running,
472 <computeroutput>ADMIN_down</computeroutput> if the
473 instance has been stopped (and is stopped) and
474 <computeroutput>running</computeroutput> if the
475 instance is set to be running (and is
480 <term>oper_ram</term>
482 <simpara>the actual memory usage of the instance as seen
483 by the hypervisor</simpara>
489 <simpara>the ip address ganeti recognizes as associated with
490 the instance interface</simpara>
496 <simpara>the instance interface MAC address</simpara>
502 <simpara>bridge the instance is connected to
507 <term>sda_size</term>
509 <simpara>the size of the instance's first disk</simpara>
513 <term>sdb_size</term>
515 <simpara>the size of the instance's second disk</simpara>
521 <simpara>the number of VCPUs allocated to the
529 If the value of the option starts with the character
530 <constant>+</constant>, the new fields will be added to the
531 default list. This allows to quickly see the default list
532 plus a few other fields, instead of retyping the entire list
537 There is a subtle grouping about the available output
538 fields: all fields except for <option>oper_state</option>,
539 <option>oper_ram</option> and <option>status</option> are
540 configuration value and not run-time values. So if you don't
541 select any of the these fields, the query will be satisfied
542 instantly from the cluster configuration, without having to
543 ask the remote nodes for the data. This can be helpful for
544 big clusters when you only want some data and it makes sense
545 to specify a reduced set of output fields.
548 <para>The default output field list is:
549 <simplelist type="inline">
550 <member>name</member>
552 <member>pnode</member>
553 <member>admin_state</member>
554 <member>oper_state</member>
555 <member>oper_ram</member>
564 <command>info</command>
565 <arg rep="repeat"><replaceable>instance</replaceable></arg>
569 Show detailed information about the (given) instances. This
570 is different from <command>list</command> as it shows
571 detailed data about the instance's disks (especially useful
572 for remote raid templates).
577 <title>MODIFY</title>
580 <command>modify</command>
581 <arg choice="opt">-m <replaceable>memsize</replaceable></arg>
582 <arg choice="opt">-p <replaceable>vcpus</replaceable></arg>
583 <arg choice="opt">-i <replaceable>ip</replaceable></arg>
584 <arg choice="opt">-b <replaceable>bridge</replaceable></arg>
585 <arg choice="opt">--mac <replaceable>MAC-address</replaceable></arg>
586 <arg>--hvm-boot-order <replaceable>boot-order</replaceable></arg>
588 <arg>--kernel <group choice="req">
590 <arg><replaceable>kernel_path</replaceable></arg>
593 <arg>--initrd <group choice="req">
596 <arg><replaceable>initrd_path</replaceable></arg>
599 <arg choice="req"><replaceable>instance</replaceable></arg>
603 Modify the memory size, number of vcpus, ip address, MAC
604 address and/or bridge for an instance.
608 The memory size is given in MiB. Note that you need to give
609 at least one of the arguments, otherwise the command
614 The <option>--kernel</option>, <option>--initrd</option>
615 and <option>--hvm-boot-order</option>
616 options are described in the <command>add</command> command.
620 Additionally, the HVM boot order can be reset to the default
621 values by using <option>--hvm-boot-order=default</option>.
625 All the changes take effect at the next restart. If the
626 instance is running, there is no effect on the instance.
631 <title>REINSTALL</title>
634 <command>reinstall</command>
635 <arg choice="opt">-o <replaceable>os-type</replaceable></arg>
636 <arg choice="opt">-f <replaceable>force</replaceable></arg>
637 <arg choice="req"><replaceable>instance</replaceable></arg>
641 Reinstalls the operating system on the given instance. The instance
642 must be stopped when running this command. If the
643 <option>--os-type</option> is specified, the operating system is
649 <title>RENAME</title>
652 <command>rename</command>
653 <arg>--no-ip-check</arg>
654 <arg choice="req"><replaceable>instance</replaceable></arg>
655 <arg choice="req"><replaceable>new_name</replaceable></arg>
659 Renames the given instance. The instance must be stopped
660 when running this command. The requirements for the new name
661 are the same as for adding an instance: the new name must be
662 resolvable and the IP it resolves to must not be reachable
663 (in order to prevent duplicate IPs the next time the
664 instance is started). The IP test can be skipped if the
665 <option>--no-ip-check</option> option is passed.
672 <title>Starting/stopping/connecting to console</title>
675 <title>STARTUP</title>
678 <command>startup</command>
679 <arg>--extra=<replaceable>PARAMS</replaceable></arg>
683 <arg>--instance</arg>
686 <arg>--secondary</arg>
691 rep="repeat"><replaceable>name</replaceable></arg>
695 Starts one or more instances, depending on the following
696 options. The four available modes are:
699 <term><option>--instance</option></term>
701 <simpara>will start the instances given as arguments
702 (at least one argument required); this is the default
709 <simpara>will start the instances who have the given
710 node as either primary or secondary</simpara>
714 <term><option>--primary</option></term>
716 <simpara>will start all instances whose primary node
717 is in the list of nodes passed as arguments (at least
718 one node required)</simpara>
722 <term><option>--secondary</option></term>
724 <simpara>will start all instances whose secondary node
725 is in the list of nodes passed as arguments (at least
726 one node required)</simpara>
732 <simpara>will start all instances in the cluster (no
733 arguments accepted)</simpara>
740 Note that although you can pass more than one selection
741 option, the last one wins, so in order to guarantee the
742 desired result, don't pass more than one such option.
746 The <option>--extra</option> option is used to pass
747 additional argument to the instance's kernel for this start
748 only. Currently there is no way to specify a persistent set
749 of arguments (beside the one hardcoded). Note that this may
750 not apply to all virtualization types.
754 Use <option>--force</option> to start even if secondary disks are
761 # gnt-instance start instance1.example.com
762 # gnt-instance start --extra single test1.example.com
763 # gnt-instance start --node node1.example.com node2.example.com
764 # gnt-instance start --all
770 <title>SHUTDOWN</title>
773 <command>shutdown</command>
776 <arg>--instance</arg>
779 <arg>--secondary</arg>
785 rep="repeat"><replaceable>name</replaceable></arg>
789 Stops one or more instances. If the instance cannot be
790 cleanly stopped during a hardcoded interval (currently 2
791 minutes), it will forcibly stop the instance (equivalent to
792 switching off the power on a physical machine).
796 The <option>--instance</option>, <option>--node</option>,
797 <option>--primary</option>, <option>--secondary</option> and
798 <option>--all</option> options are similar as for the
799 <command>startup</command> command and they influence the
800 actual instances being shutdown.
806 # gnt-instance shutdown instance1.example.com
807 # gnt-instance shutdown --all
813 <title>REBOOT</title>
816 <command>reboot</command>
818 <arg>--extra=<replaceable>PARAMS</replaceable></arg>
820 <arg>--type=<replaceable>REBOOT-TYPE</replaceable></arg>
822 <arg>--ignore-secondaries</arg>
824 <arg>--force-multiple</arg>
827 <arg>--instance</arg>
830 <arg>--secondary</arg>
836 rep="repeat"><replaceable>name</replaceable></arg>
840 Reboots one or more instances. The type of reboot depends on
841 the value of <option>--type</option>. A soft reboot does a
842 hypervisor reboot, a hard reboot does a instance stop,
843 recreates the hypervisor config for the instance and
844 starts the instance. A full reboot does the equivalent
845 of <command>gnt-instance shutdown && gnt-instance
846 startup</command>. The default is soft reboot.
850 For the hard reboot the option
851 <option>--ignore-secondaries</option> ignores errors for the
852 secondary node while re-assembling the instance disks.
856 The <option>--instance</option>, <option>--node</option>,
857 <option>--primary</option>, <option>--secondary</option> and
858 <option>--all</option> options are similar as for the
859 <command>startup</command> command and they influence the
860 actual instances being rebooted.
864 Use the <option>--force-multiple</option> option to keep
865 gnt-instance from asking for confirmation when more than one
866 instance is affected.
872 # gnt-instance reboot instance1.example.com
873 # gnt-instance reboot --type=full instance1.example.com
879 <title>CONSOLE</title>
881 <command>console</command>
882 <arg choice="opt">--show-cmd</arg>
883 <arg choice="req"><replaceable>instance</replaceable></arg>
887 Connects to the console of the given instance. If the instance
888 is not up, an error is returned. Use the <option>--show-cmd</option>
889 option to display the command instead of executing it.
895 # gnt-instance console instance1.example.com
903 <title>Disk management</title>
906 <title>REPLACE-DISKS</title>
909 <command>replace-disks</command>
910 <arg choice="opt">--new-secondary <replaceable>NODE</replaceable></arg>
911 <arg choice="req"><replaceable>instance</replaceable></arg>
915 <command>replace-disks</command>
916 <arg choice="opt">-s</arg>
917 <arg choice="req">--new-secondary <replaceable>NODE</replaceable></arg>
918 <arg choice="req"><replaceable>instance</replaceable></arg>
922 <command>replace-disks</command>
924 <arg choice="req">-s</arg>
925 <arg choice="req">-p</arg>
927 <arg choice="req"><replaceable>instance</replaceable></arg>
931 This command is a generalized form for adding and replacing
936 The first form is usable with the
937 <literal>remote_raid1</literal> disk template. This will
938 replace the disks on both the primary and secondary node,
939 and optionally will change the secondary node to a new one
940 if you pass the <option>--new-secondary</option> option.
944 The second and third forms are usable with the
945 <literal>drbd</literal> disk template. The second form will
946 do a secondary replacement, but as opposed to the
947 <literal>remote_raid1</literal> will not replace the disks
948 on the primary, therefore it will execute faster. The third
949 form will replace the disks on either the primary
950 (<option>-p</option>) or the secondary (<option>-s</option>)
951 node of the instance only, without changing the node.
957 <title>ACTIVATE-DISKS</title>
960 <command>activate-disks</command>
961 <arg choice="req"><replaceable>instance</replaceable></arg>
964 Activates the block devices of the given instance. If
965 successful, the command will show the location and name of
968 node1.example.com:sda:/dev/md0
969 node1.example.com:sdb:/dev/md1
972 In this example, <emphasis>node1.example.com</emphasis> is
973 the name of the node on which the devices have been
974 activated. The <emphasis>sda</emphasis> and
975 <emphasis>sdb</emphasis> are the names of the block devices
976 inside the instance. <emphasis>/dev/md0</emphasis> and
977 <emphasis>/dev/md1</emphasis> are the names of the block
978 devices as visible on the node.
982 Note that it is safe to run this command while the instance
988 <title>DEACTIVATE-DISKS</title>
991 <command>deactivate-disks</command>
992 <arg choice="req"><replaceable>instance</replaceable></arg>
995 De-activates the block devices of the given instance. Note
996 that if you run this command for a remote raid instance
997 type, while it is running, it will not be able to shutdown
998 the block devices on the primary node, but it will shutdown
999 the block devices on the secondary nodes, thus breaking the
1008 <title>Recovery</title>
1011 <title>FAILOVER</title>
1014 <command>failover</command>
1016 <arg>--ignore-consistency</arg>
1017 <arg choice="req"><replaceable>instance</replaceable></arg>
1021 Failover will fail the instance over its secondary
1022 node. This works only for instances having a remote raid
1027 Normally the failover will check the consistency of the
1028 disks before failing over the instance. If you are trying to
1029 migrate instances off a dead node, this will fail. Use the
1030 <option>--ignore-consistency</option> option for this
1031 purpose. Note that this option can be dangerous as errors in
1032 shutting down the instance will be ignored, resulting in
1033 possibly having the instance running on two machines in
1034 parallel (on disconnected DRBD drives).
1040 # gnt-instance failover instance1.example.com
1051 <title>ADD-TAGS</title>
1054 <command>add-tags</command>
1055 <arg choice="opt">--from <replaceable>file</replaceable></arg>
1056 <arg choice="req"><replaceable>instancename</replaceable></arg>
1058 rep="repeat"><replaceable>tag</replaceable></arg>
1062 Add tags to the given instance. If any of the tags contains
1063 invalid characters, the entire operation will abort.
1066 If the <option>--from</option> option is given, the list of
1067 tags will be extended with the contents of that file (each
1068 line becomes a tag). In this case, there is not need to pass
1069 tags on the command line (if you do, both sources will be
1070 used). A file name of - will be interpreted as stdin.
1075 <title>LIST-TAGS</title>
1078 <command>list-tags</command>
1079 <arg choice="req"><replaceable>instancename</replaceable></arg>
1082 <para>List the tags of the given instance.</para>
1086 <title>REMOVE-TAGS</title>
1088 <command>remove-tags</command>
1089 <arg choice="opt">--from <replaceable>file</replaceable></arg>
1090 <arg choice="req"><replaceable>instancename</replaceable></arg>
1092 rep="repeat"><replaceable>tag</replaceable></arg>
1096 Remove tags from the given instance. If any of the tags are
1097 not existing on the node, the entire operation will abort.
1101 If the <option>--from</option> option is given, the list of
1102 tags will be extended with the contents of that file (each
1103 line becomes a tag). In this case, there is not need to pass
1104 tags on the command line (if you do, both sources will be
1105 used). A file name of - will be interpreted as stdin.
1117 <!-- Keep this comment at the end of the file
1122 sgml-minimize-attributes:nil
1123 sgml-always-quote-attributes:t
1126 sgml-parent-document:nil
1127 sgml-default-dtd-file:nil
1128 sgml-exposed-tags:nil
1129 sgml-local-catalogs:nil
1130 sgml-local-ecat-files:nil