Revision 6bf0c9bb

b/docs/Makefile.am
1 1
docdir = $(datadir)/doc/$(PACKAGE)
2 2

  
3
dist_doc_DATA = hooks.html hooks.pdf installing.html installing.pdf
4
EXTRA_DIST = hooks.sgml installing.sgml
3
dist_doc_DATA = hooks.html hooks.pdf installing.html installing.pdf admin.html admin.pdf
4
EXTRA_DIST = hooks.sgml installing.sgml admin.sgml
5 5

  
6 6
%.html: %.sgml
7 7
	docbook2html --nochunks $<
b/docs/admin.sgml
1
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
2
]>
3
  <article class="specification">
4
  <articleinfo>
5
    <title>Ganeti administrator's guide</title>
6
  </articleinfo>
7
  <para>Documents Ganeti version 1.2</para>
8
  <sect1>
9
    <title>Introduction</title>
10

  
11
    <para>Ganeti is a virtualization cluster management software. You are
12
    expected to be a system administrator familiar with your Linux distribution
13
    and the Xen virtualization environment before using it.
14
    </para>
15

  
16
    <para>The various components of Ganeti all have man pages and interactive
17
    help. This manual though will help you getting familiar with the system by
18
    explaining the most common operations, grouped by related use.
19
    </para>
20

  
21
    <para>After a terminology glossary and a section on the prerequisites
22
    needed to use this manual, the rest of this document is divided in three
23
    main sections, which group different features of Ganeti:
24
      <itemizedlist>
25
        <listitem>
26
          <simpara>Instance Management</simpara>
27
        </listitem>
28
        <listitem>
29
          <simpara>High Availability Features</simpara>
30
        </listitem>
31
        <listitem>
32
          <simpara>Debugging Features</simpara>
33
        </listitem>
34
      </itemizedlist>
35
    </para>
36

  
37
    <sect2>
38
      <title>Ganeti Terminology</title>
39

  
40
      <para>This section provides a small introduction to Ganeti terminology,
41
      which might be useful to read the rest of the document.
42

  
43
      <variablelist>
44
        <varlistentry>
45
          <term>Cluster</term>
46
	  <listitem><para>A set of machines (nodes) that cooperate to offer a
47
	  coherent highly available virtualization service.</para></listitem>
48
        </varlistentry>
49

  
50
        <varlistentry>
51
          <term>Node</term>
52
	  <listitem><para>A physical machine which is member of a cluster.
53
	  Nodes are the basic cluster infrastructure, and are not fault
54
	  tolerant.</para></listitem>
55
        </varlistentry>
56

  
57
        <varlistentry>
58
          <term>Master Node</term>
59
	  <listitem><para>The node which controls the Cluster, from which all
60
	  Ganeti commands must be given.</para></listitem>
61
        </varlistentry>
62

  
63
        <varlistentry>
64
          <term>Instance</term>
65
	  <listitem><para>A virtual machine which runs on a cluster. It can be
66
	  a fault tolerant highly available entity.</para></listitem>
67
        </varlistentry>
68

  
69
        <varlistentry>
70
          <term>Pool</term>
71
	  <listitem><para>A pool is a set of clusters sharing the same
72
	  network.</para></listitem>
73
        </varlistentry>
74

  
75
        <varlistentry>
76
          <term>Meta-Cluster</term>
77
	  <listitem><para>Anything that concerns more than one
78
	  cluster.</para></listitem>
79
        </varlistentry>
80

  
81
      </variablelist>
82

  
83
      </para>
84
    </sect2>
85

  
86
    <sect2>
87
      <title>Prerequisites</title>
88

  
89
      <para>You need to have your Ganeti cluster installed and configured
90
      before you try any of the commands in this document. Please follow the
91
      "installing tutorial" for instructions on how to do that.
92
      </para>
93
    </sect2>
94

  
95
  </sect1>
96

  
97
  <sect1>
98
    <title>Managing Instances</title>
99

  
100
    <sect2>
101
      <title>Adding/Removing an instance</title>
102

  
103
      <para>Adding a new virtual instance to your Ganeti cluster is really
104
      easy. The command is:
105
      <programlisting>
106
gnt-instance add -n TARGET_NODE -o OS_TYPE -t DISK_TEMPLATE INSTANCE_NAME
107
      </programlisting>
108
      The instance name must exist in dns and of course map to an address in
109
      the same subnet as the cluster itself. Options you can give to this
110
      command include:
111
      <itemizedlist>
112
        <listitem>
113
          <simpara>The disk size (-s)</simpara>
114
        </listitem>
115
        <listitem>
116
          <simpara>The swap size (--swap-size)</simpara>
117
        </listitem>
118
        <listitem>
119
          <simpara>The memory size (-m)</simpara>
120
        </listitem>
121
        <listitem>
122
          <simpara>The number of virtual CPUs (-p)</simpara>
123
        </listitem>
124
        <listitem>
125
	  <simpara>The instance ip address (-i) (use -i auto to make Ganeti
126
	  record the address from dns)</simpara>
127
        </listitem>
128
        <listitem>
129
	  <simpara>The bridge to connect the instance to (-b), if you don't
130
	  want to use the default one</simpara>
131
        </listitem>
132
      </itemizedlist>
133
      If you want to create an highly available instance use the remote_raid1
134
      disk template:
135
      <programlisting>
136
gnt-instance add -n TARGET_NODE -o OS_TYPE -t remote_raid1 \
137
  --secondary-node=SECONDARY_NODE INSTANCE_NAME
138
      </programlisting>
139
      To know which operating systems your cluster supports you can use:
140
      <programlisting>
141
gnt-os list
142
      </programlisting>
143
      </para>
144

  
145
      <para>
146
      Removing an instance is even easier than creating one. This operation is
147
      non-reversible and destroys all the contents of your instance. Use with
148
      care:
149
      <programlisting>
150
gnt-instance remove INSTANCE_NAME
151
      </programlisting>
152
      </para>
153
    </sect2>
154

  
155
    <sect2>
156
      <title>Starting/Stopping an instance</title>
157

  
158
      <para>Instances are automatically started at instance creation time. To
159
      manually start one which is currently stopped you can run:
160
      <programlisting>
161
gnt-instance startup INSTANCE_NAME
162
      </programlisting>
163
      While the command to stop one is:
164
      <programlisting>
165
gnt-instance shutdown INSTANCE_NAME
166
      </programlisting>
167
      The command to see all the instances configured and their status is:
168
      <programlisting>
169
gnt-instance list
170
      </programlisting>
171
      </para>
172
    </sect2>
173

  
174
    <sect2>
175
      <title>Exporting/Importing an instance</title>
176

  
177
      <para>You can create a snapshot of an instance disk and Ganeti
178
      configuration, which then you can backup, or import into another cluster.
179
      The way to export an instance is:
180
      <programlisting>
181
gnt-backup export -n TARGET_NODE INSTANCE_NAME
182
      </programlisting>
183
      The target node can be any node in the cluster with enough space under
184
      /srv/ganeti to hold the instance image. Use the --noshutdown option to
185
      snapshot an instance without rebooting it. Any previous snapshot of the
186
      same instance existing cluster-wide under /srv/ganeti will be removed by
187
      this operation: if you want to keep them move them out of the Ganeti
188
      exports directory.
189
      </para>
190

  
191
      <para>Importing an instance is as easy as creating a new one. The command
192
      is:
193
      <programlisting>
194
gnt-backup import -n TRGT_NODE -t DISK_TMPL --src-node=NODE --src-dir=DIR INST_NAME
195
      </programlisting>
196
      Most of the options available for gnt-instance add are supported here
197
      too.
198
      </para>
199
    </sect2>
200

  
201
  </sect1>
202

  
203

  
204
  <sect1>
205
    <title>High availability features</title>
206

  
207
    <sect2>
208
      <title>Failing over an instance</title>
209

  
210
      <para>If an instance is built in highly available mode you can at any
211
      time fail it over to its secondary node, even if the primary has somehow
212
      failed and it's not up anymore. Doing it is really easy, on the master
213
      node you can just run:
214
      <programlisting>
215
gnt-instance failover INSTANCE_NAME
216
      </programlisting>
217
      That's it. After the command completes the secondary node is now the
218
      primary, and vice versa.
219
      </para>
220
    </sect2>
221
    <sect2>
222
      <title>Replacing an instance disks</title>
223

  
224
      <para>So what if instead the secondary node for an instance has failed,
225
      or you plan to remove a node from your cluster, and you failed over all
226
      its instances, but it's still secondary for some? The solution here is to
227
      replace the instance disks, changing the secondary node:
228
      <programlisting>
229
gnt-instance replace-disks -n NEW_SECONDARY INSTANCE_NAME
230
      </programlisting>
231
      This process is a bit longer, but involves no instance downtime, and at
232
      the end of it the instance has changed its secondary node, to which it
233
      can if necessary be failed over.
234
      </para>
235
    </sect2>
236
    <sect2>
237
      <title>Failing over the master node</title>
238

  
239
      <para>This is all good as long as the Ganeti Master Node is up. Should it
240
      go down, or should you wish to decommission it, just run on any other node
241
      the command:
242
      <programlisting>
243
gnt-cluster masterfailover
244
      </programlisting>
245
      and the node you ran it on is now the new master.
246
      </para>
247
    </sect2>
248
    <sect2>
249
      <title>Adding/Removing nodes</title>
250

  
251
      <para>And of course, now that you know how to move instances around, it's
252
      easy to free up a node, and then you can remove it from the cluster:
253
      <programlisting>
254
gnt-node remove NODE_NAME
255
      </programlisting>
256
      and maybe add a new one:
257
      <programlisting>
258
gnt-node add [--secondary-ip=ADDRESS] NODE_NAME
259
      </programlisting>
260
      </para>
261
    </sect2>
262
  </sect1>
263

  
264
  <sect1>
265
    <title>Debugging Features</title>
266

  
267
    <para>At some point you might need to do some debugging operations on your
268
    cluster or on your instances. This section will help you with the most used
269
    debugging functionalities.
270
    </para>
271

  
272
    <sect2>
273
      <title>Accessing an instance's disks</title>
274

  
275
      <para>From an instance's primary node you have access to its disks. Never
276
      ever mount the underlying logical volume manually on a fault tolerant
277
      instance, though or you risk breaking replication. The correct way to
278
      access them is to run the command:
279
      <programlisting>
280
gnt-instance activate-disks INSTANCE_NAME
281
      </programlisting>
282
      And then access the device that gets created.  Of course after you've
283
      finished you can deactivate them with the deactivate-disks command, which
284
      works in the same way.
285
      </para>
286
    </sect2>
287

  
288
    <sect2>
289
      <title>Accessing an instance's console</title>
290

  
291
      <para>The command to access a running instance's console is:
292
      <programlisting>
293
gnt-instance console INSTANCE_NAME
294
      </programlisting>
295
      Use the console normally and then type ^] when done, to exit.
296
      </para>
297
    </sect2>
298

  
299
    <sect2>
300
      <title>Instance Operating System Debugging</title>
301

  
302
      <para>Should you have any problems with operating systems support the
303
      command to ran to see a complete status for all your nodes is:
304
      <programlisting>
305
gnt-os diagnose
306
      </programlisting>
307
      </para>
308

  
309
    </sect2>
310

  
311
    <sect2>
312
      <title>Cluster-wide debugging</title>
313

  
314
      <para>The gnt-cluster command offers several options to run tests or
315
      execute cluster-wide operations. For example:
316
      <programlisting>
317
gnt-cluster command
318
gnt-cluster copyfile
319
gnt-cluster verify
320
gnt-cluster getmaster
321
gnt-cluster version
322
      </programlisting>
323
      See the respective help to know more about their usage.
324
      </para>
325
    </sect2>
326

  
327
  </sect1>
328

  
329
  </article>
b/docs/installing.sgml
39 39
      management system, and Xen before trying to use Ganeti.
40 40
    </para>
41 41

  
42
    <para>A basic Ganeti terminology glossary is provided in the introductory
43
      section of the "admin guide". Please refer to that if you are uncertain
44
      about the terms we are using.
45
    </para>
46

  
42 47
  </sect1>
43 48

  
44 49
  <sect1>

Also available in: Unified diff