Statistics
| Branch: | Tag: | Revision:

root / man / gnt-cluster.sgml @ dcd7cbaf

History | View | Annotate | Download (14.8 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>-g <replaceable>vg-name</replaceable></arg>
214
        <arg>--master-netdev <replaceable>vg-name</replaceable></arg>
215
        <arg>-m <replaceable>mac-prefix</replaceable></arg>
216
        <arg>--no-lvm-storage</arg>
217
        <arg choice="req"><replaceable>clustername</replaceable></arg>
218
      </cmdsynopsis>
219

    
220
      <para>
221
        This commands is only run once initially on the first node of
222
        the cluster. It will initialize the cluster configuration and
223
        setup ssh-keys and more.
224
      </para>
225

    
226
      <para>
227
        Note that the <replaceable>clustername</replaceable> is not
228
        any random name. It has to be resolvable to an IP address
229
        using DNS, and it is best if you give the fully-qualified
230
        domain name. This hostname must resolve to an IP address
231
        reserved exclusively for this purpose.
232
      </para>
233

    
234
      <para>
235
        The cluster can run in two modes: single-home or
236
        dual-homed. In the first case, all traffic (both public
237
        traffic, inter-node traffic and data replication traffic) goes
238
        over the same interface. In the dual-homed case, the data
239
        replication traffic goes over the second network. The
240
        <option>-s</option> option here marks the cluster as
241
        dual-homed and its parameter represents this node's address on
242
        the second network. If you initialise the cluster with
243
        <option>-s</option>, all nodes added must have a secondary IP
244
        as well.
245
      </para>
246

    
247
      <para>
248
        Note that for Ganeti it doesn't matter if the secondary
249
        network is actually a separate physical network, or is done
250
        using tunneling, etc. For performance reasons, it's
251
        recommended to use a separate network, of course.
252
      </para>
253

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

    
259
      <para>
260
        The <option>-g</option> option will let you specify a volume group
261
        different than 'xenvg' for ganeti to use when creating instance disks.
262
        This volume group must have the same name on all nodes. Once the
263
        cluster is initialized this can be altered by using the
264
        <command>modify</command> command. If you don't want to use lvm
265
        storage at all use the <option>--no-lvm-storage</option> option.
266
        Once the cluster is initialized you can change this setup with the
267
        <command>modify</command> command.
268
      </para>
269

    
270
      <para>
271
        The <option>--master-netdev</option> option is useful for specifying a
272
        different interface on which the master will activate its IP address.
273
        It's important that all nodes have this interface because you'll need
274
        it for a master failover.
275
      </para>
276

    
277
      <para>
278
        The <option>-m</option> option will let you specify a three byte prefix
279
        under which the virtual MAC addresses of your instances will be
280
        generated. The prefix must be specified in the format XX:XX:XX and the
281
        default is aa:00:00.
282
      </para>
283

    
284
      <para>
285
        The <option>--no-lvm-storage</option> allows you to initialize the
286
        cluster without lvm support. This means that only instances using
287
        files as storage backend will be possible to create. Once the cluster
288
        is initialized you can change this setup with the
289
        <command>modify</command> command.
290
      </para>
291
    </refsect2>
292

    
293
    <refsect2>
294
      <title>LIST-TAGS</title>
295

    
296
      <cmdsynopsis>
297
        <command>list-tags</command>
298
      </cmdsynopsis>
299

    
300
      <para>List the tags of the cluster.</para>
301
    </refsect2>
302

    
303
    <refsect2>
304
      <title>MASTERFAILOVER</title>
305

    
306
      <cmdsynopsis>
307
        <command>masterfailover</command>
308
      </cmdsynopsis>
309

    
310
      <para>
311
        Failover the master role to the current node.
312
      </para>
313
    </refsect2>
314

    
315
    <refsect2>
316
      <title>MODIFY</title>
317

    
318
      <cmdsynopsis>
319
        <command>modify</command>
320
        <arg choice="opt">-g <replaceable>vg-name</replaceable></arg>
321
        <arg choice="opt">--no-lvm-storage</arg>
322
      </cmdsynopsis>
323

    
324
        <para>
325
          Modify the options for the cluster.
326
        </para>
327

    
328
        <para>
329
          The <option>-g</option> and <option>--no-lvm-stoarge</option> are
330
          described in the <command>init</command> command.
331
        </para>
332
    </refsect2>
333

    
334
    <refsect2>
335
      <title>REMOVE-TAGS</title>
336

    
337
      <cmdsynopsis>
338
        <command>remove-tags</command>
339
        <arg choice="opt">--from <replaceable>file</replaceable></arg>
340
        <arg choice="req"
341
        rep="repeat"><replaceable>tag</replaceable></arg>
342
      </cmdsynopsis>
343

    
344
      <para>
345
        Remove tags from the cluster. If any of the tags are not
346
        existing on the cluster, the entire operation will abort.
347
      </para>
348

    
349
      <para>
350
        If the <option>--from</option> option is given, the list of
351
        tags will be extended with the contents of that file (each
352
        line becomes a tag). In this case, there is not need to pass
353
        tags on the command line (if you do, both sources will be
354
        used). A file name of - will be interpreted as stdin.
355
      </para>
356
    </refsect2>
357

    
358
    <refsect2>
359
      <title>RENAME</title>
360

    
361
      <cmdsynopsis>
362
        <command>rename</command>
363
        <arg>-f</arg>
364
        <arg choice="req"><replaceable>name</replaceable></arg>
365
      </cmdsynopsis>
366

    
367
      <para>
368
        Renames the cluster and in the process updates the master IP
369
        address to the one the new name resolves to. At least one of
370
        either the name or the IP address must be different, otherwise
371
        the operation will be aborted.
372
      </para>
373

    
374
      <para>
375
        Note that since this command can be dangerous (especially when
376
        run over SSH), the command will require confirmation unless
377
        run with the <option>-f</option> option.
378
      </para>
379
    </refsect2>
380

    
381
    <refsect2>
382
      <title>SEARCH-TAGS</title>
383

    
384
      <cmdsynopsis>
385
        <command>search-tags</command>
386
        <arg choice="req"><replaceable>pattern</replaceable></arg>
387
      </cmdsynopsis>
388

    
389
      <para>
390
        Searches the tags on all objects in the cluster (the cluster
391
        itself, the nodes and the instances) for a given pattern. The
392
        pattern is interpreted as a regular expression and a search
393
        will be done on it (i.e. the given pattern is not anchored to
394
        the beggining of the string; if you want that, prefix the
395
        pattern with <literal>^</literal>).
396
      </para>
397

    
398
      <para>
399
        If no tags are matching the pattern, the exit code of the
400
        command will be one. If there is at least one match, the exit
401
        code will be zero. Each match is listed on one line, the
402
        object and the tag separated by a space. The cluster will be
403
        listed as <filename>/cluster</filename>, a node will be listed
404
        as
405
        <filename>/nodes/<replaceable>name</replaceable></filename>,
406
        and an instance as
407
        <filename>/instances/<replaceable>name</replaceable></filename>.
408
        Example:
409
      </para>
410
<screen>
411
# gnt-cluster search time
412
/cluster ctime:2007-09-01
413
/nodes/node1.example.com mtime:2007-10-04
414
</screen>
415
    </refsect2>
416

    
417
    <refsect2>
418
      <title>VERIFY</title>
419

    
420
      <cmdsynopsis>
421
        <command>verify</command>
422
        <arg choice="opt">--no-nplus1-mem</arg>
423
      </cmdsynopsis>
424

    
425
      <para>
426
        Verify correctness of cluster configuration. This is safe with
427
        respect to running instances, and incurs no downtime of the
428
        instances.
429
      </para>
430

    
431
      <para>
432
        If the <option>--no-nplus1-mem</option> option is given, ganeti won't
433
        check whether if it loses a node it can restart all the instances on
434
        their secondaries (and report an error otherwise).
435
      </para>
436
    </refsect2>
437

    
438
    <refsect2>
439
      <title>VERIFY-DISKS</title>
440

    
441
      <cmdsynopsis>
442
        <command>verify-disks</command>
443
      </cmdsynopsis>
444

    
445
      <para>
446
        The command checks which instances have degraded DRBD disks
447
        and activates the disks of those instances.
448
      </para>
449

    
450
      <para>
451
        This command is run from the <command>ganeti-watcher</command>
452
        tool, which also has a different, complementary algorithm for
453
        doing this check. Together, these two should ensure that DRBD
454
        disks are kept consistent.
455
      </para>
456
    </refsect2>
457

    
458
    <refsect2>
459
      <title>VERSION</title>
460

    
461
      <cmdsynopsis>
462
        <command>version</command>
463
      </cmdsynopsis>
464

    
465
      <para>
466
        Show the cluster version.
467
      </para>
468
    </refsect2>
469

    
470
  </refsect1>
471

    
472
  &footer;
473

    
474
</refentry>
475

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