Statistics
| Branch: | Tag: | Revision:

root / man / gnt-cluster.sgml @ 48c4dfa8

History | View | Annotate | Download (15.2 kB)

1
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2

    
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">
11

    
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">
16
]>
17

    
18
<refentry>
19
  <refentryinfo>
20
    <copyright>
21
      <year>2006</year>
22
      <year>2007</year>
23
      <holder>Google Inc.</holder>
24
    </copyright>
25
    &dhdate;
26
  </refentryinfo>
27
  <refmeta>
28
    &dhucpackage;
29

    
30
    &dhsection;
31
    <refmiscinfo>ganeti 1.2</refmiscinfo>
32
  </refmeta>
33
  <refnamediv>
34
    <refname>&dhpackage;</refname>
35

    
36
    <refpurpose>ganeti administration, cluster-wide</refpurpose>
37
  </refnamediv>
38
  <refsynopsisdiv>
39
    <cmdsynopsis>
40
      <command>&dhpackage; </command>
41

    
42
      <arg choice="req">command</arg>
43
      <arg>arguments...</arg>
44
    </cmdsynopsis>
45
  </refsynopsisdiv>
46
  <refsect1>
47
    <title>DESCRIPTION</title>
48

    
49
    <para>
50
      The <command>&dhpackage;</command> is used for cluster-wide
51
      administration in the ganeti system.
52
    </para>
53

    
54
  </refsect1>
55
  <refsect1>
56
    <title>COMMANDS</title>
57

    
58
    <refsect2>
59
      <title>ADD-TAGS</title>
60

    
61
      <cmdsynopsis>
62
        <command>add-tags</command>
63
        <arg choice="opt">--from <replaceable>file</replaceable></arg>
64
        <arg choice="req"
65
        rep="repeat"><replaceable>tag</replaceable></arg>
66
      </cmdsynopsis>
67

    
68
      <para>
69
        Add tags to the cluster. If any of the tags contains invalid
70
        characters, the entire operation will abort.
71
      </para>
72

    
73
      <para>
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.
79
      </para>
80
    </refsect2>
81

    
82
    <refsect2>
83
      <title>COMMAND</title>
84

    
85
      <cmdsynopsis>
86
        <command>command</command>
87
        <arg>-n <replaceable>node</replaceable></arg>
88
        <arg choice="req"><replaceable>command</replaceable></arg>
89
      </cmdsynopsis>
90

    
91
      <para>
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:
97

    
98
        <screen>
99
          # gnt-cluster command -n node1.example.com -n node2.example.com date
100
        </screen>
101

    
102
      </para>
103

    
104
      <para>
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).
111
      </para>
112

    
113
      <para>
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.
117
      </para>
118

    
119
      <para>
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
123
        nodes, run:
124

    
125
        <screen>
126
          # gnt-cluster command ls -l /etc
127
        </screen>
128

    
129
        and the command which will be executed will be
130
        <computeroutput>"ls -l /etc"</computeroutput>
131
      </para>
132
    </refsect2>
133

    
134
    <refsect2>
135
      <title>COPYFILE</title>
136

    
137
      <cmdsynopsis>
138
        <command>copyfile</command>
139
        <arg>-n <replaceable>node</replaceable></arg>
140
        <arg choice="req"><replaceable>file</replaceable></arg>
141
      </cmdsynopsis>
142

    
143
      <para>
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
149
        copied to all nodes.
150

    
151
        Example:
152
        <screen>
153
          # gnt-cluster -n node1.example.com -n node2.example.com copyfile /tmp/test
154
        </screen>
155

    
156
        This will copy the file <filename>/tmp/test</filename> from
157
        the current node to the two named nodes.
158
      </para>
159
    </refsect2>
160

    
161
    <refsect2>
162
      <title>DESTROY</title>
163

    
164
      <cmdsynopsis>
165
        <command>destroy</command>
166
        <arg choice="req">--yes-do-it</arg>
167
      </cmdsynopsis>
168

    
169
      <para>
170
        Remove all configuration files related to the cluster, so that
171
        a <command>gnt-cluster init</command> can be done again
172
        afterwards.
173
      </para>
174

    
175
      <para>
176
        Since this is a dangerous command, you are required to pass
177
        the argument <replaceable>--yes-do-it.</replaceable>
178
      </para>
179
    </refsect2>
180

    
181
    <refsect2>
182
      <title>GETMASTER</title>
183

    
184
      <cmdsynopsis>
185
        <command>getmaster</command>
186
      </cmdsynopsis>
187

    
188
      <para>
189
        Displays the current master node.
190
      </para>
191
    </refsect2>
192

    
193
    <refsect2>
194
      <title>INFO</title>
195

    
196
      <cmdsynopsis>
197
        <command>info</command>
198
      </cmdsynopsis>
199

    
200
      <para>
201
        Shows runtime cluster information: cluster name, architecture
202
        (32 or 64 bit), master node, node list and instance list.
203
      </para>
204
    </refsect2>
205

    
206
    <refsect2>
207
      <title>INIT</title>
208

    
209
      <cmdsynopsis>
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>
219
      </cmdsynopsis>
220

    
221
      <para>
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.
225
      </para>
226

    
227
      <para>
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. Also it is advisable to reserve a per-cluster
232
        unique name, and not try to reuse one of the nodes' names.
233
      </para>
234

    
235
      <para>
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
245
        as well.
246
      </para>
247

    
248
      <para>
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.
253
      </para>
254

    
255
      <para>
256
        The <option>-b</option> option specifies the default bridge
257
        for instances.
258
      </para>
259

    
260
      <para>
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> and
267
        the HVM boot ISO image
268
        <filename>/srv/ganeti/iso/hvm-install.iso</filename> because
269
        instances created by the experimental HVM support require them.
270
      </para>
271

    
272
      <para>
273
        The <option>-g</option> option will let you specify a volume group
274
        different than 'xenvg' for ganeti to use when creating instance disks.
275
        This volume group must have the same name on all nodes. Once the
276
        cluster is initialized this can be altered by using the
277
        <command>modify</command> command. If you don't want to use lvm
278
        storage at all use the <option>--no-lvm-storage</option> option.
279
        Once the cluster is initialized you can change this setup with the
280
        <command>modify</command> command.
281
      </para>
282

    
283
      <para>
284
        The <option>--master-netdev</option> option is useful for specifying a
285
        different interface on which the master will activate its IP address.
286
        It's important that all nodes have this interface because you'll need
287
        it for a master failover.
288
      </para>
289

    
290
      <para>
291
        The <option>-m</option> option will let you specify a three byte prefix
292
        under which the virtual MAC addresses of your instances will be
293
        generated. The prefix must be specified in the format XX:XX:XX and the
294
        default is aa:00:00.
295
      </para>
296

    
297
      <para>
298
        The <option>--no-lvm-storage</option> allows you to initialize the
299
        cluster without lvm support. This means that only instances using
300
        files as storage backend will be possible to create. Once the cluster
301
        is initialized you can change this setup with the
302
        <command>modify</command> command.
303
      </para>
304
    </refsect2>
305

    
306
    <refsect2>
307
      <title>LIST-TAGS</title>
308

    
309
      <cmdsynopsis>
310
        <command>list-tags</command>
311
      </cmdsynopsis>
312

    
313
      <para>List the tags of the cluster.</para>
314
    </refsect2>
315

    
316
    <refsect2>
317
      <title>MASTERFAILOVER</title>
318

    
319
      <cmdsynopsis>
320
        <command>masterfailover</command>
321
      </cmdsynopsis>
322

    
323
      <para>
324
        Failover the master role to the current node.
325
      </para>
326
    </refsect2>
327

    
328
    <refsect2>
329
      <title>MODIFY</title>
330

    
331
      <cmdsynopsis>
332
        <command>modify</command>
333
        <arg choice="opt">-g <replaceable>vg-name</replaceable></arg>
334
        <arg choice="opt">--no-lvm-storage</arg>
335
      </cmdsynopsis>
336

    
337
        <para>
338
          Modify the options for the cluster.
339
        </para>
340

    
341
        <para>
342
          The <option>-g</option> and <option>--no-lvm-stoarge</option> are
343
          described in the <command>init</command> command.
344
        </para>
345
    </refsect2>
346

    
347
    <refsect2>
348
      <title>REMOVE-TAGS</title>
349

    
350
      <cmdsynopsis>
351
        <command>remove-tags</command>
352
        <arg choice="opt">--from <replaceable>file</replaceable></arg>
353
        <arg choice="req"
354
        rep="repeat"><replaceable>tag</replaceable></arg>
355
      </cmdsynopsis>
356

    
357
      <para>
358
        Remove tags from the cluster. If any of the tags are not
359
        existing on the cluster, the entire operation will abort.
360
      </para>
361

    
362
      <para>
363
        If the <option>--from</option> option is given, the list of
364
        tags will be extended with the contents of that file (each
365
        line becomes a tag). In this case, there is not need to pass
366
        tags on the command line (if you do, both sources will be
367
        used). A file name of - will be interpreted as stdin.
368
      </para>
369
    </refsect2>
370

    
371
    <refsect2>
372
      <title>RENAME</title>
373

    
374
      <cmdsynopsis>
375
        <command>rename</command>
376
        <arg>-f</arg>
377
        <arg choice="req"><replaceable>name</replaceable></arg>
378
      </cmdsynopsis>
379

    
380
      <para>
381
        Renames the cluster and in the process updates the master IP
382
        address to the one the new name resolves to. At least one of
383
        either the name or the IP address must be different, otherwise
384
        the operation will be aborted.
385
      </para>
386

    
387
      <para>
388
        Note that since this command can be dangerous (especially when
389
        run over SSH), the command will require confirmation unless
390
        run with the <option>-f</option> option.
391
      </para>
392
    </refsect2>
393

    
394
    <refsect2>
395
      <title>SEARCH-TAGS</title>
396

    
397
      <cmdsynopsis>
398
        <command>search-tags</command>
399
        <arg choice="req"><replaceable>pattern</replaceable></arg>
400
      </cmdsynopsis>
401

    
402
      <para>
403
        Searches the tags on all objects in the cluster (the cluster
404
        itself, the nodes and the instances) for a given pattern. The
405
        pattern is interpreted as a regular expression and a search
406
        will be done on it (i.e. the given pattern is not anchored to
407
        the beggining of the string; if you want that, prefix the
408
        pattern with <literal>^</literal>).
409
      </para>
410

    
411
      <para>
412
        If no tags are matching the pattern, the exit code of the
413
        command will be one. If there is at least one match, the exit
414
        code will be zero. Each match is listed on one line, the
415
        object and the tag separated by a space. The cluster will be
416
        listed as <filename>/cluster</filename>, a node will be listed
417
        as
418
        <filename>/nodes/<replaceable>name</replaceable></filename>,
419
        and an instance as
420
        <filename>/instances/<replaceable>name</replaceable></filename>.
421
        Example:
422
      </para>
423
<screen>
424
# gnt-cluster search time
425
/cluster ctime:2007-09-01
426
/nodes/node1.example.com mtime:2007-10-04
427
</screen>
428
    </refsect2>
429

    
430
    <refsect2>
431
      <title>VERIFY</title>
432

    
433
      <cmdsynopsis>
434
        <command>verify</command>
435
      </cmdsynopsis>
436

    
437
      <para>
438
        Verify correctness of cluster configuration. This is safe with
439
        respect to running instances, and incurs no downtime of the
440
        instances.
441
      </para>
442
    </refsect2>
443

    
444
    <refsect2>
445
      <title>VERIFY-DISKS</title>
446

    
447
      <cmdsynopsis>
448
        <command>verify-disks</command>
449
      </cmdsynopsis>
450

    
451
      <para>
452
        The command checks which instances have degraded DRBD disks
453
        and activates the disks of those instances.
454
      </para>
455

    
456
      <para>
457
        This command is run from the <command>ganeti-watcher</command>
458
        tool, which also has a different, complementary algorithm for
459
        doing this check. Together, these two should ensure that DRBD
460
        disks are kept consistent.
461
      </para>
462
    </refsect2>
463

    
464
    <refsect2>
465
      <title>VERSION</title>
466

    
467
      <cmdsynopsis>
468
        <command>version</command>
469
      </cmdsynopsis>
470

    
471
      <para>
472
        Show the cluster version.
473
      </para>
474
    </refsect2>
475

    
476
  </refsect1>
477

    
478
  &footer;
479

    
480
</refentry>
481

    
482
<!-- Keep this comment at the end of the file
483
Local variables:
484
mode: sgml
485
sgml-omittag:t
486
sgml-shorttag:t
487
sgml-minimize-attributes:nil
488
sgml-always-quote-attributes:t
489
sgml-indent-step:2
490
sgml-indent-data:t
491
sgml-parent-document:nil
492
sgml-default-dtd-file:nil
493
sgml-exposed-tags:nil
494
sgml-local-catalogs:nil
495
sgml-local-ecat-files:nil
496
End:
497
-->