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>December 12, 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-cluster</refentrytitle>">
10 <!ENTITY dhpackage "gnt-cluster">
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 administration, cluster-wide</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 cluster-wide
51 administration in the ganeti system.
56 <title>COMMANDS</title>
59 <title>ADD-TAGS</title>
62 <command>add-tags</command>
63 <arg choice="opt">--from <replaceable>file</replaceable></arg>
65 rep="repeat"><replaceable>tag</replaceable></arg>
69 Add tags to the cluster. If any of the tags contains invalid
70 characters, the entire operation will abort.
74 If the <option>--from</option> option is given, the list of
75 tags will be extended with the contents of that file (each
76 line becomes a tag). In this case, there is not need to pass
77 tags on the command line (if you do, both sources will be
78 used). A file name of - will be interpreted as stdin.
83 <title>COMMAND</title>
86 <command>command</command>
87 <arg>-n <replaceable>node</replaceable></arg>
88 <arg choice="req"><replaceable>command</replaceable></arg>
92 Executes a command on all nodes. If the option
93 <option>-n</option> is not given, the command will be executed
94 on all nodes, otherwise it will be executed only on the
95 node(s) specified. Use the option multiple times for running
96 it on multiple nodes, like:
99 # gnt-cluster command -n node1.example.com -n node2.example.com date
105 The command is executed serially on the selected nodes. If the
106 master node is present in the list, the command will be
107 executed last on the master. Regarding the other nodes, the
108 execution order is somewhat alphabetic (it's smarter so that
109 node2.example.com will be earlier than node10.example.com but
110 after node1.example.com).
114 So given the node names node1, node2, node3, node10, node11,
115 with node3 being the master, the order will be: node1, node2,
116 node10, node11, node3.
120 The command is constructed by concatenating all other command
121 line arguments. For example, to list the contents of the
122 <filename class="directory">/etc</filename> directory on all
126 # gnt-cluster command ls -l /etc
129 and the command which will be executed will be
130 <computeroutput>"ls -l /etc"</computeroutput>
135 <title>COPYFILE</title>
138 <command>copyfile</command>
139 <arg>-n <replaceable>node</replaceable></arg>
140 <arg choice="req"><replaceable>file</replaceable></arg>
144 Copies a file to all or to some nodes. The argument specifies
145 the source file (on the current system), the
146 <option>-n</option> argument specifies the target node, or
147 nodes if the option is given multiple times. If
148 <option>-n</option> is not given at all, the file will be
153 # gnt-cluster -n node1.example.com -n node2.example.com copyfile /tmp/test
156 This will copy the file <filename>/tmp/test</filename> from
157 the current node to the two named nodes.
162 <title>DESTROY</title>
165 <command>destroy</command>
166 <arg choice="req">--yes-do-it</arg>
170 Remove all configuration files related to the cluster, so that
171 a <command>gnt-cluster init</command> can be done again
176 Since this is a dangerous command, you are required to pass
177 the argument <replaceable>--yes-do-it.</replaceable>
182 <title>GETMASTER</title>
185 <command>getmaster</command>
189 Displays the current master node.
197 <command>info</command>
201 Shows runtime cluster information: cluster name, architecture
202 (32 or 64 bit), master node, node list and instance list.
210 <command>init</command>
211 <arg>-s <replaceable>secondary_ip</replaceable></arg>
212 <arg>-b <replaceable>bridge</replaceable></arg>
213 <arg>-t <replaceable>hypervisor-type</replaceable></arg>
214 <arg>-g <replaceable>vg-name</replaceable></arg>
215 <arg>--master-netdev <replaceable>vg-name</replaceable></arg>
216 <arg>-m <replaceable>mac-prefix</replaceable></arg>
217 <arg>--no-lvm-storage</arg>
218 <arg choice="req"><replaceable>clustername</replaceable></arg>
222 This commands is only run once initially on the first node of
223 the cluster. It will initialize the cluster configuration and
224 setup ssh-keys and more.
228 Note that the <replaceable>clustername</replaceable> is not
229 any random name. It has to be resolvable to an IP address
230 using DNS, and it is best if you give the fully-qualified
231 domain name. This hostname must resolve to an IP address
232 reserved exclusively for this purpose.
236 The cluster can run in two modes: single-home or
237 dual-homed. In the first case, all traffic (both public
238 traffic, inter-node traffic and data replication traffic) goes
239 over the same interface. In the dual-homed case, the data
240 replication traffic goes over the second network. The
241 <option>-s</option> option here marks the cluster as
242 dual-homed and its parameter represents this node's address on
243 the second network. If you initialise the cluster with
244 <option>-s</option>, all nodes added must have a secondary IP
249 Note that for Ganeti it doesn't matter if the secondary
250 network is actually a separate physical network, or is done
251 using tunneling, etc. For performance reasons, it's
252 recommended to use a separate network, of course.
256 The <option>-b</option> option specifies the default bridge
261 The <option>-t</option> allows to set the hypervisor type of
262 the cluster. Available hypervisor types are: xen-3.0, fake and
263 xen-hvm3.1. The default is the xen-3.0 hypervisor.
264 Note that if you init the cluster with hypervisor-type
265 xen-hvm3.1 you also need to provide the cluster VNC password
266 file <filename>/etc/ganeti/vnc-cluster-password</filename>
267 because HVM instances require it for VNC console
272 The <option>-g</option> option will let you specify a volume group
273 different than 'xenvg' for ganeti to use when creating instance disks.
274 This volume group must have the same name on all nodes. Once the
275 cluster is initialized this can be altered by using the
276 <command>modify</command> command. If you don't want to use lvm
277 storage at all use the <option>--no-lvm-storage</option> option.
278 Once the cluster is initialized you can change this setup with the
279 <command>modify</command> command.
283 The <option>--master-netdev</option> option is useful for specifying a
284 different interface on which the master will activate its IP address.
285 It's important that all nodes have this interface because you'll need
286 it for a master failover.
290 The <option>-m</option> option will let you specify a three byte prefix
291 under which the virtual MAC addresses of your instances will be
292 generated. The prefix must be specified in the format XX:XX:XX and the
297 The <option>--no-lvm-storage</option> allows you to initialize the
298 cluster without lvm support. This means that only instances using
299 files as storage backend will be possible to create. Once the cluster
300 is initialized you can change this setup with the
301 <command>modify</command> command.
306 <title>LIST-TAGS</title>
309 <command>list-tags</command>
312 <para>List the tags of the cluster.</para>
316 <title>MASTERFAILOVER</title>
319 <command>masterfailover</command>
323 Failover the master role to the current node.
328 <title>MODIFY</title>
331 <command>modify</command>
332 <arg choice="opt">-g <replaceable>vg-name</replaceable></arg>
333 <arg choice="opt">--no-lvm-storage</arg>
337 Modify the options for the cluster.
341 The <option>-g</option> and <option>--no-lvm-stoarge</option> are
342 described in the <command>init</command> command.
347 <title>REMOVE-TAGS</title>
350 <command>remove-tags</command>
351 <arg choice="opt">--from <replaceable>file</replaceable></arg>
353 rep="repeat"><replaceable>tag</replaceable></arg>
357 Remove tags from the cluster. If any of the tags are not
358 existing on the cluster, the entire operation will abort.
362 If the <option>--from</option> option is given, the list of
363 tags will be extended with the contents of that file (each
364 line becomes a tag). In this case, there is not need to pass
365 tags on the command line (if you do, both sources will be
366 used). A file name of - will be interpreted as stdin.
371 <title>RENAME</title>
374 <command>rename</command>
376 <arg choice="req"><replaceable>name</replaceable></arg>
380 Renames the cluster and in the process updates the master IP
381 address to the one the new name resolves to. At least one of
382 either the name or the IP address must be different, otherwise
383 the operation will be aborted.
387 Note that since this command can be dangerous (especially when
388 run over SSH), the command will require confirmation unless
389 run with the <option>-f</option> option.
394 <title>SEARCH-TAGS</title>
397 <command>search-tags</command>
398 <arg choice="req"><replaceable>pattern</replaceable></arg>
402 Searches the tags on all objects in the cluster (the cluster
403 itself, the nodes and the instances) for a given pattern. The
404 pattern is interpreted as a regular expression and a search
405 will be done on it (i.e. the given pattern is not anchored to
406 the beggining of the string; if you want that, prefix the
407 pattern with <literal>^</literal>).
411 If no tags are matching the pattern, the exit code of the
412 command will be one. If there is at least one match, the exit
413 code will be zero. Each match is listed on one line, the
414 object and the tag separated by a space. The cluster will be
415 listed as <filename>/cluster</filename>, a node will be listed
417 <filename>/nodes/<replaceable>name</replaceable></filename>,
419 <filename>/instances/<replaceable>name</replaceable></filename>.
423 # gnt-cluster search time
424 /cluster ctime:2007-09-01
425 /nodes/node1.example.com mtime:2007-10-04
430 <title>VERIFY</title>
433 <command>verify</command>
434 <arg choice="opt">--no-nplus1-mem</arg>
438 Verify correctness of cluster configuration. This is safe with
439 respect to running instances, and incurs no downtime of the
444 If the <option>--no-nplus1-mem</option> option is given, ganeti won't
445 check whether if it loses a node it can restart all the instances on
446 their secondaries (and report an error otherwise).
451 <title>VERIFY-DISKS</title>
454 <command>verify-disks</command>
458 The command checks which instances have degraded DRBD disks
459 and activates the disks of those instances.
463 This command is run from the <command>ganeti-watcher</command>
464 tool, which also has a different, complementary algorithm for
465 doing this check. Together, these two should ensure that DRBD
466 disks are kept consistent.
471 <title>VERSION</title>
474 <command>version</command>
478 Show the cluster version.
488 <!-- Keep this comment at the end of the file
493 sgml-minimize-attributes:nil
494 sgml-always-quote-attributes:t
497 sgml-parent-document:nil
498 sgml-default-dtd-file:nil
499 sgml-exposed-tags:nil
500 sgml-local-catalogs:nil
501 sgml-local-ecat-files:nil