root / man / gnt-instance.rst @ 41c25861
History | View | Annotate | Download (76.3 kB)
1 |
gnt-instance(8) Ganeti | Version @GANETI_VERSION@ |
---|---|
2 |
================================================= |
3 |
|
4 |
Name |
5 |
---- |
6 |
|
7 |
gnt-instance - Ganeti instance administration |
8 |
|
9 |
Synopsis |
10 |
-------- |
11 |
|
12 |
**gnt-instance** {command} [arguments...] |
13 |
|
14 |
DESCRIPTION |
15 |
----------- |
16 |
|
17 |
The **gnt-instance** command is used for instance administration in |
18 |
the Ganeti system. |
19 |
|
20 |
COMMANDS |
21 |
-------- |
22 |
|
23 |
Creation/removal/querying |
24 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
25 |
|
26 |
ADD |
27 |
^^^ |
28 |
|
29 |
| **add** |
30 |
| {-t|\--disk-template {diskless \| file \| plain \| drbd \| rbd}} |
31 |
| {\--disk=*N*: {size=*VAL*[,spindles=*VAL*] \| adopt=*LV*}[,options...] |
32 |
| \| {size=*VAL*,provider=*PROVIDER*}[,param=*value*... ][,options...] |
33 |
| \| {-s|\--os-size} *SIZE*} |
34 |
| [\--no-ip-check] [\--no-name-check] [\--no-conflicts-check] |
35 |
| [\--no-start] [\--no-install] |
36 |
| [\--net=*N* [:options...] \| \--no-nics] |
37 |
| [{-B|\--backend-parameters} *BEPARAMS*] |
38 |
| [{-H|\--hypervisor-parameters} *HYPERVISOR* [: option=*value*... ]] |
39 |
| [{-O|\--os-parameters} *param*=*value*... ] |
40 |
| [--os-parameters-private *param*=*value*... ] |
41 |
| [--os-parameters-secret *param*=*value*... ] |
42 |
| [\--file-storage-dir *dir\_path*] [\--file-driver {loop \| blktap \| blktap2}] |
43 |
| {{-n|\--node} *node[:secondary-node]* \| {-I|\--iallocator} *name*} |
44 |
| {{-o|\--os-type} *os-type*} |
45 |
| [\--submit] [\--print-job-id] |
46 |
| [\--ignore-ipolicy] |
47 |
| [\--no-wait-for-sync] |
48 |
| [{-c|\--communication=yes|no}] |
49 |
| {*instance*} |
50 |
|
51 |
Creates a new instance on the specified host. The *instance* argument |
52 |
must be in DNS, but depending on the bridge/routing setup, need not be |
53 |
in the same network as the nodes in the cluster. |
54 |
|
55 |
The ``disk`` option specifies the parameters for the disks of the |
56 |
instance. The numbering of disks starts at zero, and at least one disk |
57 |
needs to be passed. For each disk, either the size or the adoption |
58 |
source needs to be given. The size is interpreted (when no unit is |
59 |
given) in mebibytes. You can also use one of the suffixes *m*, *g* or |
60 |
*t* to specify the exact the units used; these suffixes map to |
61 |
mebibytes, gibibytes and tebibytes. Each disk can also take these |
62 |
parameters (all optional): |
63 |
|
64 |
spindles |
65 |
How many spindles (physical disks on the node) the disk should span. |
66 |
|
67 |
mode |
68 |
The access mode. Either ``ro`` (read-only) or the default ``rw`` |
69 |
(read-write). |
70 |
|
71 |
name |
72 |
This option specifies a name for the disk, which can be used as a disk |
73 |
identifier. An instance can not have two disks with the same name. |
74 |
|
75 |
vg |
76 |
The LVM volume group. This works only for LVM and DRBD devices. |
77 |
|
78 |
metavg |
79 |
This option specifies a different VG for the metadata device. This |
80 |
works only for DRBD devices. If not specified, the default metavg |
81 |
of the node-group (possibly inherited from the cluster-wide settings) |
82 |
will be used. |
83 |
|
84 |
access |
85 |
If 'userspace', instance will access this disk directly without going |
86 |
through a block device, avoiding expensive context switches with |
87 |
kernel space. This options works only for RBD and Gluster devices. If |
88 |
not specified, the default access of the node-group (possibly |
89 |
inherited from the cluster-wide settings) will be used. |
90 |
|
91 |
When creating ExtStorage disks, also arbitrary parameters can be passed, |
92 |
to the ExtStorage provider. Those parameters are passed as additional |
93 |
comma separated options. Therefore, an ExtStorage disk provided by |
94 |
provider ``pvdr1`` with parameters ``param1``, ``param2`` would be |
95 |
passed as ``--disk 0:size=10G,provider=pvdr1,param1=val1,param2=val2``. |
96 |
|
97 |
When using the ``adopt`` key in the disk definition, Ganeti will |
98 |
reuse those volumes (instead of creating new ones) as the |
99 |
instance's disks. Ganeti will rename these volumes to the standard |
100 |
format, and (without installing the OS) will use them as-is for the |
101 |
instance. This allows migrating instances from non-managed mode |
102 |
(e.g. plain KVM with LVM) to being managed via Ganeti. Please note that |
103 |
this works only for the \`plain' disk template (see below for |
104 |
template details). |
105 |
|
106 |
Alternatively, a single-disk instance can be created via the ``-s`` |
107 |
option which takes a single argument, the size of the disk. This is |
108 |
similar to the Ganeti 1.2 version (but will only create one disk). |
109 |
|
110 |
The minimum disk specification is therefore ``--disk 0:size=20G`` (or |
111 |
``-s 20G`` when using the ``-s`` option), and a three-disk instance |
112 |
can be specified as ``--disk 0:size=20G --disk 1:size=4G --disk |
113 |
2:size=100G``. |
114 |
|
115 |
The minimum information needed to specify an ExtStorage disk are the |
116 |
``size`` and the ``provider``. For example: |
117 |
``--disk 0:size=20G,provider=pvdr1``. |
118 |
|
119 |
The ``--no-ip-check`` skips the checks that are done to see if the |
120 |
instance's IP is not already alive (i.e. reachable from the master |
121 |
node). |
122 |
|
123 |
The ``--no-name-check`` skips the check for the instance name via |
124 |
the resolver (e.g. in DNS or /etc/hosts, depending on your setup). |
125 |
Since the name check is used to compute the IP address, if you pass |
126 |
this option you must also pass the ``--no-ip-check`` option. |
127 |
|
128 |
If you don't want the instance to automatically start after |
129 |
creation, this is possible via the ``--no-start`` option. This will |
130 |
leave the instance down until a subsequent **gnt-instance start** |
131 |
command. |
132 |
|
133 |
The NICs of the instances can be specified via the ``--net`` |
134 |
option. By default, one NIC is created for the instance, with a |
135 |
random MAC, and set up according the the cluster level NIC |
136 |
parameters. Each NIC can take these parameters (all optional): |
137 |
|
138 |
mac |
139 |
either a value or 'generate' to generate a new unique MAC |
140 |
|
141 |
ip |
142 |
specifies the IP address assigned to the instance from the Ganeti |
143 |
side (this is not necessarily what the instance will use, but what |
144 |
the node expects the instance to use). Note that if an IP in the |
145 |
range of a network configured with **gnt-network**\(8) is used, |
146 |
and the NIC is not already connected to it, this network has to be |
147 |
passed in the **network** parameter if this NIC is meant to be |
148 |
connected to the said network. ``--no-conflicts-check`` can be used |
149 |
to override this check. The special value **pool** causes Ganeti to |
150 |
select an IP from the the network the NIC is or will be connected to. |
151 |
One can pick an externally reserved IP of a network along with |
152 |
``--no-conflict-check``. Note that this IP cannot be assigned to |
153 |
any other instance until it gets released. |
154 |
|
155 |
mode |
156 |
specifies the connection mode for this NIC: routed, bridged or |
157 |
openvswitch. |
158 |
|
159 |
link |
160 |
in bridged or openvswitch mode specifies the interface to attach |
161 |
this NIC to, in routed mode it's intended to differentiate between |
162 |
different routing tables/instance groups (but the meaning is |
163 |
dependent on the network script, see **gnt-cluster**\(8) for more |
164 |
details). Note that openvswitch support is also hypervisor |
165 |
dependent. |
166 |
|
167 |
network |
168 |
derives the mode and the link from the settings of the network |
169 |
which is identified by its name. If the network option is chosen, |
170 |
link and mode must not be specified. Note that the mode and link |
171 |
depend on the network-to-nodegroup connection, thus allowing |
172 |
different nodegroups to be connected to the same network in |
173 |
different ways. |
174 |
|
175 |
name |
176 |
this option specifies a name for the NIC, which can be used as a NIC |
177 |
identifier. An instance can not have two NICs with the same name. |
178 |
|
179 |
vlan |
180 |
in openvswitch mode specifies the VLANs that the NIC will be |
181 |
connected to. To connect as an access port use ``n`` or ``.n`` with |
182 |
**n** being the VLAN ID. To connect as an trunk port use ``:n[:n]``. |
183 |
A hybrid port can be created with ``.n:n[:n]`` |
184 |
|
185 |
Of these "mode" and "link" are NIC parameters, and inherit their |
186 |
default at cluster level. Alternatively, if no network is desired for |
187 |
the instance, you can prevent the default of one NIC with the |
188 |
``--no-nics`` option. |
189 |
|
190 |
The ``-o (--os-type)`` option specifies the operating system to be |
191 |
installed. The available operating systems can be listed with |
192 |
**gnt-os list**. Passing ``--no-install`` will however skip the OS |
193 |
installation, allowing a manual import if so desired. Note that the |
194 |
no-installation mode will automatically disable the start-up of the |
195 |
instance (without an OS, it most likely won't be able to start-up |
196 |
successfully). |
197 |
|
198 |
The ``-B (--backend-parameters)`` option specifies the backend |
199 |
parameters for the instance. If no such parameters are specified, the |
200 |
values are inherited from the cluster. Possible parameters are: |
201 |
|
202 |
maxmem |
203 |
the maximum memory size of the instance; as usual, suffixes can be |
204 |
used to denote the unit, otherwise the value is taken in mebibytes |
205 |
|
206 |
minmem |
207 |
the minimum memory size of the instance; as usual, suffixes can be |
208 |
used to denote the unit, otherwise the value is taken in mebibytes |
209 |
|
210 |
vcpus |
211 |
the number of VCPUs to assign to the instance (if this value makes |
212 |
sense for the hypervisor) |
213 |
|
214 |
auto\_balance |
215 |
whether the instance is considered in the N+1 cluster checks |
216 |
(enough redundancy in the cluster to survive a node failure) |
217 |
|
218 |
always\_failover |
219 |
``True`` or ``False``, whether the instance must be failed over |
220 |
(shut down and rebooted) always or it may be migrated (briefly |
221 |
suspended) |
222 |
|
223 |
Note that before 2.6 Ganeti had a ``memory`` parameter, which was the |
224 |
only value of memory an instance could have. With the |
225 |
``maxmem``/``minmem`` change Ganeti guarantees that at least the minimum |
226 |
memory is always available for an instance, but allows more memory to be |
227 |
used (up to the maximum memory) should it be free. |
228 |
|
229 |
The ``-H (--hypervisor-parameters)`` option specified the hypervisor |
230 |
to use for the instance (must be one of the enabled hypervisors on the |
231 |
cluster) and optionally custom parameters for this instance. If not |
232 |
other options are used (i.e. the invocation is just -H *NAME*) the |
233 |
instance will inherit the cluster options. The defaults below show the |
234 |
cluster defaults at cluster creation time. |
235 |
|
236 |
The possible hypervisor options are as follows: |
237 |
|
238 |
boot\_order |
239 |
Valid for the Xen HVM and KVM hypervisors. |
240 |
|
241 |
A string value denoting the boot order. This has different meaning |
242 |
for the Xen HVM hypervisor and for the KVM one. |
243 |
|
244 |
For Xen HVM, The boot order is a string of letters listing the boot |
245 |
devices, with valid device letters being: |
246 |
|
247 |
a |
248 |
floppy drive |
249 |
|
250 |
c |
251 |
hard disk |
252 |
|
253 |
d |
254 |
CDROM drive |
255 |
|
256 |
n |
257 |
network boot (PXE) |
258 |
|
259 |
The default is not to set an HVM boot order, which is interpreted |
260 |
as 'dc'. |
261 |
|
262 |
For KVM the boot order is either "floppy", "cdrom", "disk" or |
263 |
"network". Please note that older versions of KVM couldn't netboot |
264 |
from virtio interfaces. This has been fixed in more recent versions |
265 |
and is confirmed to work at least with qemu-kvm 0.11.1. Also note |
266 |
that if you have set the ``kernel_path`` option, that will be used |
267 |
for booting, and this setting will be silently ignored. |
268 |
|
269 |
blockdev\_prefix |
270 |
Valid for the Xen HVM and PVM hypervisors. |
271 |
|
272 |
Relevant to non-pvops guest kernels, in which the disk device names |
273 |
are given by the host. Allows one to specify 'xvd', which helps run |
274 |
Red Hat based installers, driven by anaconda. |
275 |
|
276 |
floppy\_image\_path |
277 |
Valid for the KVM hypervisor. |
278 |
|
279 |
The path to a floppy disk image to attach to the instance. This |
280 |
is useful to install Windows operating systems on Virt/IO disks |
281 |
because you can specify here the floppy for the drivers at |
282 |
installation time. |
283 |
|
284 |
cdrom\_image\_path |
285 |
Valid for the Xen HVM and KVM hypervisors. |
286 |
|
287 |
The path to a CDROM image to attach to the instance. |
288 |
|
289 |
cdrom2\_image\_path |
290 |
Valid for the KVM hypervisor. |
291 |
|
292 |
The path to a second CDROM image to attach to the instance. |
293 |
**NOTE**: This image can't be used to boot the system. To do that |
294 |
you have to use the 'cdrom\_image\_path' option. |
295 |
|
296 |
nic\_type |
297 |
Valid for the Xen HVM and KVM hypervisors. |
298 |
|
299 |
This parameter determines the way the network cards are presented |
300 |
to the instance. The possible options are: |
301 |
|
302 |
- rtl8139 (default for Xen HVM) (HVM & KVM) |
303 |
- ne2k\_isa (HVM & KVM) |
304 |
- ne2k\_pci (HVM & KVM) |
305 |
- i82551 (KVM) |
306 |
- i82557b (KVM) |
307 |
- i82559er (KVM) |
308 |
- pcnet (KVM) |
309 |
- e1000 (KVM) |
310 |
- paravirtual (default for KVM) (HVM & KVM) |
311 |
|
312 |
vif\_type |
313 |
Valid for the Xen HVM hypervisor. |
314 |
|
315 |
This parameter specifies the vif type of the nic configuration |
316 |
of the instance. Unsetting the value leads to no type being specified |
317 |
in the configuration. Note that this parameter only takes effect when |
318 |
the 'nic_type' is not set. The possible options are: |
319 |
|
320 |
- ioemu |
321 |
- vif |
322 |
|
323 |
disk\_type |
324 |
Valid for the Xen HVM and KVM hypervisors. |
325 |
|
326 |
This parameter determines the way the disks are presented to the |
327 |
instance. The possible options are: |
328 |
|
329 |
- ioemu [default] (HVM & KVM) |
330 |
- paravirtual (HVM & KVM) |
331 |
- ide (KVM) |
332 |
- scsi (KVM) |
333 |
- sd (KVM) |
334 |
- mtd (KVM) |
335 |
- pflash (KVM) |
336 |
|
337 |
|
338 |
cdrom\_disk\_type |
339 |
Valid for the KVM hypervisor. |
340 |
|
341 |
This parameter determines the way the cdroms disks are presented |
342 |
to the instance. The default behavior is to get the same value of |
343 |
the earlier parameter (disk_type). The possible options are: |
344 |
|
345 |
- paravirtual |
346 |
- ide |
347 |
- scsi |
348 |
- sd |
349 |
- mtd |
350 |
- pflash |
351 |
|
352 |
|
353 |
vnc\_bind\_address |
354 |
Valid for the Xen HVM and KVM hypervisors. |
355 |
|
356 |
Specifies the address that the VNC listener for this instance |
357 |
should bind to. Valid values are IPv4 addresses. Use the address |
358 |
0.0.0.0 to bind to all available interfaces (this is the default) |
359 |
or specify the address of one of the interfaces on the node to |
360 |
restrict listening to that interface. |
361 |
|
362 |
vnc\_password\_file |
363 |
Valid for the Xen HVM and KVM hypervisors. |
364 |
|
365 |
Specifies the location of the file containing the password for |
366 |
connections using VNC. The default is a file named |
367 |
vnc-cluster-password which can be found in the configuration |
368 |
directory. |
369 |
|
370 |
vnc\_tls |
371 |
Valid for the KVM hypervisor. |
372 |
|
373 |
A boolean option that controls whether the VNC connection is |
374 |
secured with TLS. |
375 |
|
376 |
vnc\_x509\_path |
377 |
Valid for the KVM hypervisor. |
378 |
|
379 |
If ``vnc_tls`` is enabled, this options specifies the path to the |
380 |
x509 certificate to use. |
381 |
|
382 |
vnc\_x509\_verify |
383 |
Valid for the KVM hypervisor. |
384 |
|
385 |
spice\_bind |
386 |
Valid for the KVM hypervisor. |
387 |
|
388 |
Specifies the address or interface on which the SPICE server will |
389 |
listen. Valid values are: |
390 |
|
391 |
- IPv4 addresses, including 0.0.0.0 and 127.0.0.1 |
392 |
- IPv6 addresses, including :: and ::1 |
393 |
- names of network interfaces |
394 |
|
395 |
If a network interface is specified, the SPICE server will be bound |
396 |
to one of the addresses of that interface. |
397 |
|
398 |
spice\_ip\_version |
399 |
Valid for the KVM hypervisor. |
400 |
|
401 |
Specifies which version of the IP protocol should be used by the |
402 |
SPICE server. |
403 |
|
404 |
It is mainly intended to be used for specifying what kind of IP |
405 |
addresses should be used if a network interface with both IPv4 and |
406 |
IPv6 addresses is specified via the ``spice_bind`` parameter. In |
407 |
this case, if the ``spice_ip_version`` parameter is not used, the |
408 |
default IP version of the cluster will be used. |
409 |
|
410 |
spice\_password\_file |
411 |
Valid for the KVM hypervisor. |
412 |
|
413 |
Specifies a file containing the password that must be used when |
414 |
connecting via the SPICE protocol. If the option is not specified, |
415 |
passwordless connections are allowed. |
416 |
|
417 |
spice\_image\_compression |
418 |
Valid for the KVM hypervisor. |
419 |
|
420 |
Configures the SPICE lossless image compression. Valid values are: |
421 |
|
422 |
- auto_glz |
423 |
- auto_lz |
424 |
- quic |
425 |
- glz |
426 |
- lz |
427 |
- off |
428 |
|
429 |
spice\_jpeg\_wan\_compression |
430 |
Valid for the KVM hypervisor. |
431 |
|
432 |
Configures how SPICE should use the jpeg algorithm for lossy image |
433 |
compression on slow links. Valid values are: |
434 |
|
435 |
- auto |
436 |
- never |
437 |
- always |
438 |
|
439 |
spice\_zlib\_glz\_wan\_compression |
440 |
Valid for the KVM hypervisor. |
441 |
|
442 |
Configures how SPICE should use the zlib-glz algorithm for lossy image |
443 |
compression on slow links. Valid values are: |
444 |
|
445 |
- auto |
446 |
- never |
447 |
- always |
448 |
|
449 |
spice\_streaming\_video |
450 |
Valid for the KVM hypervisor. |
451 |
|
452 |
Configures how SPICE should detect video streams. Valid values are: |
453 |
|
454 |
- off |
455 |
- all |
456 |
- filter |
457 |
|
458 |
spice\_playback\_compression |
459 |
Valid for the KVM hypervisor. |
460 |
|
461 |
Configures whether SPICE should compress audio streams or not. |
462 |
|
463 |
spice\_use\_tls |
464 |
Valid for the KVM hypervisor. |
465 |
|
466 |
Specifies that the SPICE server must use TLS to encrypt all the |
467 |
traffic with the client. |
468 |
|
469 |
spice\_tls\_ciphers |
470 |
Valid for the KVM hypervisor. |
471 |
|
472 |
Specifies a list of comma-separated ciphers that SPICE should use |
473 |
for TLS connections. For the format, see man **cipher**\(1). |
474 |
|
475 |
spice\_use\_vdagent |
476 |
Valid for the KVM hypervisor. |
477 |
|
478 |
Enables or disables passing mouse events via SPICE vdagent. |
479 |
|
480 |
cpu\_type |
481 |
Valid for the KVM hypervisor. |
482 |
|
483 |
This parameter determines the emulated cpu for the instance. If this |
484 |
parameter is empty (which is the default configuration), it will not |
485 |
be passed to KVM. |
486 |
|
487 |
Be aware of setting this parameter to ``"host"`` if you have nodes |
488 |
with different CPUs from each other. Live migration may stop working |
489 |
in this situation. |
490 |
|
491 |
For more information please refer to the KVM manual. |
492 |
|
493 |
acpi |
494 |
Valid for the Xen HVM and KVM hypervisors. |
495 |
|
496 |
A boolean option that specifies if the hypervisor should enable |
497 |
ACPI support for this instance. By default, ACPI is disabled. |
498 |
|
499 |
ACPI should be enabled for user shutdown detection. See |
500 |
``user_shutdown``. |
501 |
|
502 |
pae |
503 |
Valid for the Xen HVM and KVM hypervisors. |
504 |
|
505 |
A boolean option that specifies if the hypervisor should enable |
506 |
PAE support for this instance. The default is false, disabling PAE |
507 |
support. |
508 |
|
509 |
viridian |
510 |
Valid for the Xen HVM hypervisor. |
511 |
|
512 |
A boolean option that specifies if the hypervisor should enable |
513 |
viridian (Hyper-V) for this instance. The default is false, |
514 |
disabling viridian support. |
515 |
|
516 |
use\_localtime |
517 |
Valid for the Xen HVM and KVM hypervisors. |
518 |
|
519 |
A boolean option that specifies if the instance should be started |
520 |
with its clock set to the localtime of the machine (when true) or |
521 |
to the UTC (When false). The default is false, which is useful for |
522 |
Linux/Unix machines; for Windows OSes, it is recommended to enable |
523 |
this parameter. |
524 |
|
525 |
kernel\_path |
526 |
Valid for the Xen PVM and KVM hypervisors. |
527 |
|
528 |
This option specifies the path (on the node) to the kernel to boot |
529 |
the instance with. Xen PVM instances always require this, while for |
530 |
KVM if this option is empty, it will cause the machine to load the |
531 |
kernel from its disks (and the boot will be done accordingly to |
532 |
``boot_order``). |
533 |
|
534 |
kernel\_args |
535 |
Valid for the Xen PVM and KVM hypervisors. |
536 |
|
537 |
This options specifies extra arguments to the kernel that will be |
538 |
loaded. device. This is always used for Xen PVM, while for KVM it |
539 |
is only used if the ``kernel_path`` option is also specified. |
540 |
|
541 |
The default setting for this value is simply ``"ro"``, which |
542 |
mounts the root disk (initially) in read-only one. For example, |
543 |
setting this to single will cause the instance to start in |
544 |
single-user mode. |
545 |
|
546 |
initrd\_path |
547 |
Valid for the Xen PVM and KVM hypervisors. |
548 |
|
549 |
This option specifies the path (on the node) to the initrd to boot |
550 |
the instance with. Xen PVM instances can use this always, while |
551 |
for KVM if this option is only used if the ``kernel_path`` option |
552 |
is also specified. You can pass here either an absolute filename |
553 |
(the path to the initrd) if you want to use an initrd, or use the |
554 |
format no\_initrd\_path for no initrd. |
555 |
|
556 |
root\_path |
557 |
Valid for the Xen PVM and KVM hypervisors. |
558 |
|
559 |
This options specifies the name of the root device. This is always |
560 |
needed for Xen PVM, while for KVM it is only used if the |
561 |
``kernel_path`` option is also specified. |
562 |
|
563 |
Please note, that if this setting is an empty string and the |
564 |
hypervisor is Xen it will not be written to the Xen configuration |
565 |
file |
566 |
|
567 |
serial\_console |
568 |
Valid for the KVM hypervisor. |
569 |
|
570 |
This boolean option specifies whether to emulate a serial console |
571 |
for the instance. Note that some versions of KVM have a bug that |
572 |
will make an instance hang when configured to use the serial console |
573 |
unless a connection is made to it within about 2 seconds of the |
574 |
instance's startup. For such case it's recommended to disable this |
575 |
option, which is enabled by default. |
576 |
|
577 |
serial\_speed |
578 |
Valid for the KVM hypervisor. |
579 |
|
580 |
This integer option specifies the speed of the serial console. |
581 |
Common values are 9600, 19200, 38400, 57600 and 115200: choose the |
582 |
one which works on your system. (The default is 38400 for historical |
583 |
reasons, but newer versions of kvm/qemu work with 115200) |
584 |
|
585 |
disk\_cache |
586 |
Valid for the KVM hypervisor. |
587 |
|
588 |
The disk cache mode. It can be either default to not pass any |
589 |
cache option to KVM, or one of the KVM cache modes: none (for |
590 |
direct I/O), writethrough (to use the host cache but report |
591 |
completion to the guest only when the host has committed the |
592 |
changes to disk) or writeback (to use the host cache and report |
593 |
completion as soon as the data is in the host cache). Note that |
594 |
there are special considerations for the cache mode depending on |
595 |
version of KVM used and disk type (always raw file under Ganeti), |
596 |
please refer to the KVM documentation for more details. |
597 |
|
598 |
disk\_aio |
599 |
Valid for the KVM hypervisor. |
600 |
|
601 |
This is an optional parameter that specifies the aio mode |
602 |
for the disks. KVM default is to use the 'threads' mode, |
603 |
so if not explicitly specified, the native mode will not |
604 |
be used. Possible values are: threads or native. |
605 |
|
606 |
security\_model |
607 |
Valid for the KVM hypervisor. |
608 |
|
609 |
The security model for kvm. Currently one of *none*, *user* or |
610 |
*pool*. Under *none*, the default, nothing is done and instances |
611 |
are run as the Ganeti daemon user (normally root). |
612 |
|
613 |
Under *user* kvm will drop privileges and become the user |
614 |
specified by the security\_domain parameter. |
615 |
|
616 |
Under *pool* a global cluster pool of users will be used, making |
617 |
sure no two instances share the same user on the same node. (this |
618 |
mode is not implemented yet) |
619 |
|
620 |
security\_domain |
621 |
Valid for the KVM hypervisor. |
622 |
|
623 |
Under security model *user* the username to run the instance |
624 |
under. It must be a valid username existing on the host. |
625 |
|
626 |
Cannot be set under security model *none* or *pool*. |
627 |
|
628 |
kvm\_flag |
629 |
Valid for the KVM hypervisor. |
630 |
|
631 |
If *enabled* the -enable-kvm flag is passed to kvm. If *disabled* |
632 |
-disable-kvm is passed. If unset no flag is passed, and the |
633 |
default running mode for your kvm binary will be used. |
634 |
|
635 |
mem\_path |
636 |
Valid for the KVM hypervisor. |
637 |
|
638 |
This option passes the -mem-path argument to kvm with the path (on |
639 |
the node) to the mount point of the hugetlbfs file system, along |
640 |
with the -mem-prealloc argument too. |
641 |
|
642 |
use\_chroot |
643 |
Valid for the KVM hypervisor. |
644 |
|
645 |
This boolean option determines whether to run the KVM instance in a |
646 |
chroot directory. |
647 |
|
648 |
If it is set to ``true``, an empty directory is created before |
649 |
starting the instance and its path is passed via the -chroot flag |
650 |
to kvm. The directory is removed when the instance is stopped. |
651 |
|
652 |
It is set to ``false`` by default. |
653 |
|
654 |
user\_shutdown |
655 |
Valid for the KVM hypervisor. |
656 |
|
657 |
This boolean option determines whether the KVM instance suports user |
658 |
shutdown detection. This option does not necessarily require ACPI |
659 |
enabled, but ACPI must be enabled for users to poweroff their KVM |
660 |
instances. |
661 |
|
662 |
If it is set to ``true``, the user can shutdown this KVM instance |
663 |
and its status is reported as ``USER_down``. |
664 |
|
665 |
It is set to ``false`` by default. |
666 |
|
667 |
migration\_downtime |
668 |
Valid for the KVM hypervisor. |
669 |
|
670 |
The maximum amount of time (in ms) a KVM instance is allowed to be |
671 |
frozen during a live migration, in order to copy dirty memory |
672 |
pages. Default value is 30ms, but you may need to increase this |
673 |
value for busy instances. |
674 |
|
675 |
This option is only effective with kvm versions >= 87 and qemu-kvm |
676 |
versions >= 0.11.0. |
677 |
|
678 |
cpu\_mask |
679 |
Valid for the Xen, KVM and LXC hypervisors. |
680 |
|
681 |
The processes belonging to the given instance are only scheduled |
682 |
on the specified CPUs. |
683 |
|
684 |
The format of the mask can be given in three forms. First, the word |
685 |
"all", which signifies the common case where all VCPUs can live on |
686 |
any CPU, based on the hypervisor's decisions. |
687 |
|
688 |
Second, a comma-separated list of CPU IDs or CPU ID ranges. The |
689 |
ranges are defined by a lower and higher boundary, separated by a |
690 |
dash, and the boundaries are inclusive. In this form, all VCPUs of |
691 |
the instance will be mapped on the selected list of CPUs. Example: |
692 |
``0-2,5``, mapping all VCPUs (no matter how many) onto physical CPUs |
693 |
0, 1, 2 and 5. |
694 |
|
695 |
The last form is used for explicit control of VCPU-CPU pinnings. In |
696 |
this form, the list of VCPU mappings is given as a colon (:) |
697 |
separated list, whose elements are the possible values for the |
698 |
second or first form above. In this form, the number of elements in |
699 |
the colon-separated list _must_ equal the number of VCPUs of the |
700 |
instance. |
701 |
|
702 |
Example: |
703 |
|
704 |
.. code-block:: bash |
705 |
|
706 |
# Map the entire instance to CPUs 0-2 |
707 |
gnt-instance modify -H cpu_mask=0-2 my-inst |
708 |
|
709 |
# Map vCPU 0 to physical CPU 1 and vCPU 1 to CPU 3 (assuming 2 vCPUs) |
710 |
gnt-instance modify -H cpu_mask=1:3 my-inst |
711 |
|
712 |
# Pin vCPU 0 to CPUs 1 or 2, and vCPU 1 to any CPU |
713 |
gnt-instance modify -H cpu_mask=1-2:all my-inst |
714 |
|
715 |
# Pin vCPU 0 to any CPU, vCPU 1 to CPUs 1, 3, 4 or 5, and CPU 2 to |
716 |
# CPU 0 (backslashes for escaping the comma) |
717 |
gnt-instance modify -H cpu_mask=all:1\\,3-5:0 my-inst |
718 |
|
719 |
# Pin entire VM to CPU 0 |
720 |
gnt-instance modify -H cpu_mask=0 my-inst |
721 |
|
722 |
# Turn off CPU pinning (default setting) |
723 |
gnt-instance modify -H cpu_mask=all my-inst |
724 |
|
725 |
cpu\_cap |
726 |
Valid for the Xen hypervisor. |
727 |
|
728 |
Set the maximum amount of cpu usage by the VM. The value is a percentage |
729 |
between 0 and (100 * number of VCPUs). Default cap is 0: unlimited. |
730 |
|
731 |
cpu\_weight |
732 |
Valid for the Xen hypervisor. |
733 |
|
734 |
Set the cpu time ratio to be allocated to the VM. Valid values are |
735 |
between 1 and 65535. Default weight is 256. |
736 |
|
737 |
usb\_mouse |
738 |
Valid for the KVM hypervisor. |
739 |
|
740 |
This option specifies the usb mouse type to be used. It can be |
741 |
"mouse" or "tablet". When using VNC it's recommended to set it to |
742 |
"tablet". |
743 |
|
744 |
keymap |
745 |
Valid for the KVM hypervisor. |
746 |
|
747 |
This option specifies the keyboard mapping to be used. It is only |
748 |
needed when using the VNC console. For example: "fr" or "en-gb". |
749 |
|
750 |
reboot\_behavior |
751 |
Valid for Xen PVM, Xen HVM and KVM hypervisors. |
752 |
|
753 |
Normally if an instance reboots, the hypervisor will restart it. If |
754 |
this option is set to ``exit``, the hypervisor will treat a reboot |
755 |
as a shutdown instead. |
756 |
|
757 |
It is set to ``reboot`` by default. |
758 |
|
759 |
cpu\_cores |
760 |
Valid for the KVM hypervisor. |
761 |
|
762 |
Number of emulated CPU cores. |
763 |
|
764 |
cpu\_threads |
765 |
Valid for the KVM hypervisor. |
766 |
|
767 |
Number of emulated CPU threads. |
768 |
|
769 |
cpu\_sockets |
770 |
Valid for the KVM hypervisor. |
771 |
|
772 |
Number of emulated CPU sockets. |
773 |
|
774 |
soundhw |
775 |
Valid for the KVM and XEN hypervisors. |
776 |
|
777 |
Comma separated list of emulated sounds cards, or "all" to enable |
778 |
all the available ones. |
779 |
|
780 |
cpuid |
781 |
Valid for the XEN hypervisor. |
782 |
|
783 |
Modify the values returned by CPUID_ instructions run within instances. |
784 |
|
785 |
This allows you to enable migration between nodes with different CPU |
786 |
attributes like cores, threads, hyperthreading or SS4 support by hiding |
787 |
the extra features where needed. |
788 |
|
789 |
See the XEN documentation for syntax and more information. |
790 |
|
791 |
.. _CPUID: http://en.wikipedia.org/wiki/CPUID |
792 |
|
793 |
usb\_devices |
794 |
Valid for the KVM hypervisor. |
795 |
|
796 |
Space separated list of usb devices. These can be emulated devices |
797 |
or passthrough ones, and each one gets passed to kvm with its own |
798 |
``-usbdevice`` option. See the **qemu**\(1) manpage for the syntax |
799 |
of the possible components. Note that values set with this |
800 |
parameter are split on a space character and currently don't support |
801 |
quoting. For backwards compatibility reasons, the RAPI interface keeps |
802 |
accepting comma separated lists too. |
803 |
|
804 |
vga |
805 |
Valid for the KVM hypervisor. |
806 |
|
807 |
Emulated vga mode, passed the the kvm -vga option. |
808 |
|
809 |
kvm\_extra |
810 |
Valid for the KVM hypervisor. |
811 |
|
812 |
Any other option to the KVM hypervisor, useful tweaking anything |
813 |
that Ganeti doesn't support. Note that values set with this |
814 |
parameter are split on a space character and currently don't support |
815 |
quoting. |
816 |
|
817 |
machine\_version |
818 |
Valid for the KVM hypervisor. |
819 |
|
820 |
Use in case an instance must be booted with an exact type of |
821 |
machine version (due to e.g. outdated drivers). In case it's not set |
822 |
the default version supported by your version of kvm is used. |
823 |
|
824 |
migration\_caps |
825 |
Valid for the KVM hypervisor. |
826 |
|
827 |
Enable specific migration capabilities by providing a ":" separated |
828 |
list of supported capabilites. QEMU version 1.7.0 defines |
829 |
x-rdma-pin-all, auto-converge, zero-blocks, and xbzrle. Please note |
830 |
that while a combination of xbzrle and auto-converge might speed up |
831 |
the migration process significantly, the first may cause BSOD on |
832 |
Windows8r2 instances running on drbd. |
833 |
|
834 |
kvm\_path |
835 |
Valid for the KVM hypervisor. |
836 |
|
837 |
Path to the userspace KVM (or qemu) program. |
838 |
|
839 |
vnet\_hdr |
840 |
Valid for the KVM hypervisor. |
841 |
|
842 |
This boolean option determines whether the tap devices used by the |
843 |
KVM paravirtual nics (virtio-net) will get created with VNET_HDR |
844 |
(IFF_VNET_HDR) support. |
845 |
|
846 |
If set to false, it effectively disables offloading on the virio-net |
847 |
interfaces, which prevents host kernel tainting and log flooding, |
848 |
when dealing with broken or malicious virtio-net drivers. |
849 |
|
850 |
It is set to ``true`` by default. |
851 |
|
852 |
The ``-O (--os-parameters)`` option allows customisation of the OS |
853 |
parameters. The actual parameter names and values depends on the OS |
854 |
being used, but the syntax is the same key=value. For example, setting |
855 |
a hypothetical ``dhcp`` parameter to yes can be achieved by:: |
856 |
|
857 |
gnt-instance add -O dhcp=yes ... |
858 |
|
859 |
You can also specify OS parameters that should not be logged but reused |
860 |
at the next reinstall with ``--os-parameters-private`` and OS parameters |
861 |
that should not be logged or saved to configuration with |
862 |
``--os-parameters-secret``. Bear in mind that: |
863 |
|
864 |
* Launching the daemons in debug mode will cause debug logging to |
865 |
happen, which leaks private and secret parameters to the log files. |
866 |
Do not use the debug mode in production. Deamons will emit a warning |
867 |
on startup if they are in debug mode. |
868 |
* You will have to pass again all ``--os-parameters-secret`` parameters |
869 |
should you want to reinstall this instance. |
870 |
|
871 |
The ``-I (--iallocator)`` option specifies the instance allocator plugin |
872 |
to use (``.`` means the default allocator). If you pass in this option |
873 |
the allocator will select nodes for this instance automatically, so you |
874 |
don't need to pass them with the ``-n`` option. For more information |
875 |
please refer to the instance allocator documentation. |
876 |
|
877 |
The ``-t (--disk-template)`` options specifies the disk layout type |
878 |
for the instance. If no disk template is specified, the default disk |
879 |
template is used. The default disk template is the first in the list |
880 |
of enabled disk templates, which can be adjusted cluster-wide with |
881 |
``gnt-cluster modify``. The available choices for disk templates are: |
882 |
|
883 |
diskless |
884 |
This creates an instance with no disks. Its useful for testing only |
885 |
(or other special cases). |
886 |
|
887 |
file |
888 |
Disk devices will be regular files. |
889 |
|
890 |
sharedfile |
891 |
Disk devices will be regulare files on a shared directory. |
892 |
|
893 |
plain |
894 |
Disk devices will be logical volumes. |
895 |
|
896 |
drbd |
897 |
Disk devices will be drbd (version 8.x) on top of lvm volumes. |
898 |
|
899 |
rbd |
900 |
Disk devices will be rbd volumes residing inside a RADOS cluster. |
901 |
|
902 |
blockdev |
903 |
Disk devices will be adopted pre-existent block devices. |
904 |
|
905 |
ext |
906 |
Disk devices will be provided by external shared storage, |
907 |
through the ExtStorage Interface using ExtStorage providers. |
908 |
|
909 |
The optional second value of the ``-n (--node)`` is used for the drbd |
910 |
template type and specifies the remote node. |
911 |
|
912 |
If you do not want gnt-instance to wait for the disk mirror to be |
913 |
synced, use the ``--no-wait-for-sync`` option. |
914 |
|
915 |
The ``--file-storage-dir`` specifies the relative path under the |
916 |
cluster-wide file storage directory to store file-based disks. It is |
917 |
useful for having different subdirectories for different |
918 |
instances. The full path of the directory where the disk files are |
919 |
stored will consist of cluster-wide file storage directory + optional |
920 |
subdirectory + instance name. This option is only relevant for |
921 |
instances using the file storage backend. |
922 |
|
923 |
The ``--file-driver`` specifies the driver to use for file-based |
924 |
disks. Note that currently these drivers work with the xen hypervisor |
925 |
only. This option is only relevant for instances using the file |
926 |
storage backend. The available choices are: |
927 |
|
928 |
loop |
929 |
Kernel loopback driver. This driver uses loopback devices to |
930 |
access the filesystem within the file. However, running I/O |
931 |
intensive applications in your instance using the loop driver |
932 |
might result in slowdowns. Furthermore, if you use the loopback |
933 |
driver consider increasing the maximum amount of loopback devices |
934 |
(on most systems it's 8) using the max\_loop param. |
935 |
|
936 |
blktap |
937 |
The blktap driver (for Xen hypervisors). In order to be able to |
938 |
use the blktap driver you should check if the 'blktapctrl' user |
939 |
space disk agent is running (usually automatically started via |
940 |
xend). This user-level disk I/O interface has the advantage of |
941 |
better performance. Especially if you use a network file system |
942 |
(e.g. NFS) to store your instances this is the recommended choice. |
943 |
|
944 |
blktap2 |
945 |
Analogous to the blktap driver, but used by newer versions of Xen. |
946 |
|
947 |
If ``--ignore-ipolicy`` is given any instance policy violations occuring |
948 |
during this operation are ignored. |
949 |
|
950 |
The ``-c`` and ``--communication`` specify whether to enable/disable |
951 |
instance communication, which is a communication mechanism between the |
952 |
instance and the host. |
953 |
|
954 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
955 |
options. |
956 |
|
957 |
Example:: |
958 |
|
959 |
# gnt-instance add -t file --disk 0:size=30g -B maxmem=512 -o debian-etch \ |
960 |
-n node1.example.com --file-storage-dir=mysubdir instance1.example.com |
961 |
# gnt-instance add -t plain --disk 0:size=30g -B maxmem=1024,minmem=512 \ |
962 |
-o debian-etch -n node1.example.com instance1.example.com |
963 |
# gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \ |
964 |
-B maxmem=512 -o debian-etch -n node1.example.com instance1.example.com |
965 |
# gnt-instance add -t drbd --disk 0:size=30g -B maxmem=512 -o debian-etch \ |
966 |
-n node1.example.com:node2.example.com instance2.example.com |
967 |
# gnt-instance add -t rbd --disk 0:size=30g -B maxmem=512 -o debian-etch \ |
968 |
-n node1.example.com instance1.example.com |
969 |
# gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1 -B maxmem=512 \ |
970 |
-o debian-etch -n node1.example.com instance1.example.com |
971 |
# gnt-instance add -t ext --disk 0:size=30g,provider=pvdr1,param1=val1 \ |
972 |
--disk 1:size=40g,provider=pvdr2,param2=val2,param3=val3 -B maxmem=512 \ |
973 |
-o debian-etch -n node1.example.com instance1.example.com |
974 |
|
975 |
|
976 |
BATCH-CREATE |
977 |
^^^^^^^^^^^^ |
978 |
|
979 |
| **batch-create** |
980 |
| [{-I|\--iallocator} *instance allocator*] |
981 |
| {instances\_file.json} |
982 |
|
983 |
This command (similar to the Ganeti 1.2 **batcher** tool) submits |
984 |
multiple instance creation jobs based on a definition file. This |
985 |
file can contain all options which are valid when adding an instance |
986 |
with the exception of the ``iallocator`` field. The IAllocator is, |
987 |
for optimization purposes, only allowed to be set for the whole batch |
988 |
operation using the ``--iallocator`` parameter. |
989 |
|
990 |
The instance file must be a valid-formed JSON file, containing an |
991 |
array of dictionaries with instance creation parameters. All parameters |
992 |
(except ``iallocator``) which are valid for the instance creation |
993 |
OP code are allowed. The most important ones are: |
994 |
|
995 |
instance\_name |
996 |
The FQDN of the new instance. |
997 |
|
998 |
disk\_template |
999 |
The disk template to use for the instance, the same as in the |
1000 |
**add** command. |
1001 |
|
1002 |
disks |
1003 |
Array of disk specifications. Each entry describes one disk as a |
1004 |
dictionary of disk parameters. |
1005 |
|
1006 |
beparams |
1007 |
A dictionary of backend parameters. |
1008 |
|
1009 |
hypervisor |
1010 |
The hypervisor for the instance. |
1011 |
|
1012 |
hvparams |
1013 |
A dictionary with the hypervisor options. If not passed, the default |
1014 |
hypervisor options will be inherited. |
1015 |
|
1016 |
nics |
1017 |
List of NICs that will be created for the instance. Each entry |
1018 |
should be a dict, with mac, ip, mode and link as possible keys. |
1019 |
Please don't provide the "mac, ip, mode, link" parent keys if you |
1020 |
use this method for specifying NICs. |
1021 |
|
1022 |
pnode, snode |
1023 |
The primary and optionally the secondary node to use for the |
1024 |
instance (in case an iallocator script is not used). If those |
1025 |
parameters are given, they have to be given consistently for all |
1026 |
instances in the batch operation. |
1027 |
|
1028 |
start |
1029 |
whether to start the instance |
1030 |
|
1031 |
ip\_check |
1032 |
Skip the check for already-in-use instance; see the description in |
1033 |
the **add** command for details. |
1034 |
|
1035 |
name\_check |
1036 |
Skip the name check for instances; see the description in the |
1037 |
**add** command for details. |
1038 |
|
1039 |
file\_storage\_dir, file\_driver |
1040 |
Configuration for the file disk type, see the **add** command for |
1041 |
details. |
1042 |
|
1043 |
|
1044 |
A simple definition for one instance can be (with most of the |
1045 |
parameters taken from the cluster defaults):: |
1046 |
|
1047 |
[ |
1048 |
{ |
1049 |
"mode": "create", |
1050 |
"instance_name": "instance1.example.com", |
1051 |
"disk_template": "drbd", |
1052 |
"os_type": "debootstrap", |
1053 |
"disks": [{"size":"1024"}], |
1054 |
"nics": [{}], |
1055 |
"hypervisor": "xen-pvm" |
1056 |
}, |
1057 |
{ |
1058 |
"mode": "create", |
1059 |
"instance_name": "instance2.example.com", |
1060 |
"disk_template": "drbd", |
1061 |
"os_type": "debootstrap", |
1062 |
"disks": [{"size":"4096", "mode": "rw", "vg": "xenvg"}], |
1063 |
"nics": [{}], |
1064 |
"hypervisor": "xen-hvm", |
1065 |
"hvparams": {"acpi": true}, |
1066 |
"beparams": {"maxmem": 512, "minmem": 256} |
1067 |
} |
1068 |
] |
1069 |
|
1070 |
The command will display the job id for each submitted instance, as |
1071 |
follows:: |
1072 |
|
1073 |
# gnt-instance batch-create instances.json |
1074 |
Submitted jobs 37, 38 |
1075 |
|
1076 |
|
1077 |
Note: If the allocator is used for computing suitable nodes for the |
1078 |
instances, it will only take into account disk information for the |
1079 |
default disk template. That means, even if other disk templates are |
1080 |
specified for the instances, storage space information of these disk |
1081 |
templates will not be considered in the allocation computation. |
1082 |
|
1083 |
|
1084 |
REMOVE |
1085 |
^^^^^^ |
1086 |
|
1087 |
| **remove** [\--ignore-failures] [\--shutdown-timeout=*N*] [\--submit] |
1088 |
| [\--print-job-id] [\--force] {*instance*} |
1089 |
|
1090 |
Remove an instance. This will remove all data from the instance and |
1091 |
there is *no way back*. If you are not sure if you use an instance |
1092 |
again, use **shutdown** first and leave it in the shutdown state for a |
1093 |
while. |
1094 |
|
1095 |
The ``--ignore-failures`` option will cause the removal to proceed |
1096 |
even in the presence of errors during the removal of the instance |
1097 |
(e.g. during the shutdown or the disk removal). If this option is not |
1098 |
given, the command will stop at the first error. |
1099 |
|
1100 |
The ``--shutdown-timeout`` is used to specify how much time to wait |
1101 |
before forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the |
1102 |
kvm process for KVM, etc.). By default two minutes are given to each |
1103 |
instance to stop. |
1104 |
|
1105 |
The ``--force`` option is used to skip the interactive confirmation. |
1106 |
|
1107 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1108 |
options. |
1109 |
|
1110 |
Example:: |
1111 |
|
1112 |
# gnt-instance remove instance1.example.com |
1113 |
|
1114 |
|
1115 |
LIST |
1116 |
^^^^ |
1117 |
|
1118 |
| **list** |
1119 |
| [\--no-headers] [\--separator=*SEPARATOR*] [\--units=*UNITS*] [-v] |
1120 |
| [{-o|\--output} *[+]FIELD,...*] [\--filter] [instance...] |
1121 |
|
1122 |
Shows the currently configured instances with memory usage, disk |
1123 |
usage, the node they are running on, and their run status. |
1124 |
|
1125 |
The ``--no-headers`` option will skip the initial header line. The |
1126 |
``--separator`` option takes an argument which denotes what will be |
1127 |
used between the output fields. Both these options are to help |
1128 |
scripting. |
1129 |
|
1130 |
The units used to display the numeric values in the output varies, |
1131 |
depending on the options given. By default, the values will be |
1132 |
formatted in the most appropriate unit. If the ``--separator`` option |
1133 |
is given, then the values are shown in mebibytes to allow parsing by |
1134 |
scripts. In both cases, the ``--units`` option can be used to enforce |
1135 |
a given output unit. |
1136 |
|
1137 |
The ``-v`` option activates verbose mode, which changes the display of |
1138 |
special field states (see **ganeti**\(7)). |
1139 |
|
1140 |
The ``-o (--output)`` option takes a comma-separated list of output |
1141 |
fields. The available fields and their meaning are: |
1142 |
|
1143 |
@QUERY_FIELDS_INSTANCE@ |
1144 |
|
1145 |
If the value of the option starts with the character ``+``, the new |
1146 |
field(s) will be added to the default list. This allows one to quickly |
1147 |
see the default list plus a few other fields, instead of retyping the |
1148 |
entire list of fields. |
1149 |
|
1150 |
There is a subtle grouping about the available output fields: all |
1151 |
fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and |
1152 |
``status`` are configuration value and not run-time values. So if you |
1153 |
don't select any of the these fields, the query will be satisfied |
1154 |
instantly from the cluster configuration, without having to ask the |
1155 |
remote nodes for the data. This can be helpful for big clusters when |
1156 |
you only want some data and it makes sense to specify a reduced set of |
1157 |
output fields. |
1158 |
|
1159 |
If exactly one argument is given and it appears to be a query filter |
1160 |
(see **ganeti**\(7)), the query result is filtered accordingly. For |
1161 |
ambiguous cases (e.g. a single field name as a filter) the ``--filter`` |
1162 |
(``-F``) option forces the argument to be treated as a filter (e.g. |
1163 |
``gnt-instance list -F admin_state``). |
1164 |
|
1165 |
The default output field list is: ``name``, ``os``, ``pnode``, |
1166 |
``admin_state``, ``oper_state``, ``oper_ram``. |
1167 |
|
1168 |
|
1169 |
LIST-FIELDS |
1170 |
^^^^^^^^^^^ |
1171 |
|
1172 |
**list-fields** [field...] |
1173 |
|
1174 |
Lists available fields for instances. |
1175 |
|
1176 |
|
1177 |
INFO |
1178 |
^^^^ |
1179 |
|
1180 |
**info** [-s \| \--static] [\--roman] {\--all \| *instance*} |
1181 |
|
1182 |
Show detailed information about the given instance(s). This is |
1183 |
different from **list** as it shows detailed data about the instance's |
1184 |
disks (especially useful for the drbd disk template). |
1185 |
|
1186 |
If the option ``-s`` is used, only information available in the |
1187 |
configuration file is returned, without querying nodes, making the |
1188 |
operation faster. |
1189 |
|
1190 |
Use the ``--all`` to get info about all instances, rather than |
1191 |
explicitly passing the ones you're interested in. |
1192 |
|
1193 |
The ``--roman`` option can be used to cause envy among people who like |
1194 |
ancient cultures, but are stuck with non-latin-friendly cluster |
1195 |
virtualization technologies. |
1196 |
|
1197 |
MODIFY |
1198 |
^^^^^^ |
1199 |
|
1200 |
| **modify** |
1201 |
| [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*] |
1202 |
| [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*] |
1203 |
| [{-m|\--runtime-memory} *SIZE*] |
1204 |
| [\--net add[:options...] \| |
1205 |
| \--net [*N*:]add[,options...] \| |
1206 |
| \--net [*ID*:]remove \| |
1207 |
| \--net *ID*:modify[,options...]] |
1208 |
| [\--disk add:size=*SIZE*[,options...] \| |
1209 |
| \--disk *N*:add,size=*SIZE*[,options...] \| |
1210 |
| \--disk *N*:add,size=*SIZE*,provider=*PROVIDER*[,options...][,param=*value*... ] \| |
1211 |
| \--disk *ID*:modify[,options...] |
1212 |
| \--disk [*ID*:]remove] |
1213 |
| [{-t|\--disk-template} plain \| {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync] |
1214 |
| [\--new-primary=*node*] |
1215 |
| [\--os-type=*OS* [\--force-variant]] |
1216 |
| [{-O|\--os-parameters} *param*=*value*... ] |
1217 |
| [--os-parameters-private *param*=*value*... ] |
1218 |
| [\--offline \| \--online] |
1219 |
| [\--submit] [\--print-job-id] |
1220 |
| [\--ignore-ipolicy] |
1221 |
| [\--hotplug] |
1222 |
| [\--hotplug-if-possible] |
1223 |
| {*instance*} |
1224 |
|
1225 |
Modifies the memory size, number of vcpus, ip address, MAC address |
1226 |
and/or NIC parameters for an instance. It can also add and remove |
1227 |
disks and NICs to/from the instance. Note that you need to give at |
1228 |
least one of the arguments, otherwise the command complains. |
1229 |
|
1230 |
The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)`` |
1231 |
and ``-O (--os-parameters)`` options specifies hypervisor, backend and |
1232 |
OS parameter options in the form of name=value[,...]. For details |
1233 |
which options can be specified, see the **add** command. |
1234 |
|
1235 |
The ``-t (--disk-template)`` option will change the disk template of |
1236 |
the instance. Currently only conversions between the plain and drbd |
1237 |
disk templates are supported, and the instance must be stopped before |
1238 |
attempting the conversion. When changing from the plain to the drbd |
1239 |
disk template, a new secondary node must be specified via the ``-n`` |
1240 |
option. The option ``--no-wait-for-sync`` can be used when converting |
1241 |
to the ``drbd`` template in order to make the instance available for |
1242 |
startup before DRBD has finished resyncing. |
1243 |
|
1244 |
The ``-m (--runtime-memory)`` option will change an instance's runtime |
1245 |
memory to the given size (in MB if a different suffix is not specified), |
1246 |
by ballooning it up or down to the new value. |
1247 |
|
1248 |
The ``--disk add:size=*SIZE*,[options..]`` option adds a disk to the |
1249 |
instance, and ``--disk *N*:add:size=*SIZE*,[options..]`` will add a disk |
1250 |
to the the instance at a specific index. The available options are the |
1251 |
same as in the **add** command (``spindles``, ``mode``, ``name``, ``vg``, |
1252 |
``metavg`` and ``access``). Per default, gnt-instance waits for the disk |
1253 |
mirror to sync. |
1254 |
If you do not want this behavior, use the ``--no-wait-for-sync`` option. |
1255 |
When adding an ExtStorage disk, the ``provider=*PROVIDER*`` option is |
1256 |
also mandatory and specifies the ExtStorage provider. Also, for |
1257 |
ExtStorage disks arbitrary parameters can be passed as additional comma |
1258 |
separated options, same as in the **add** command. The ``--disk remove`` |
1259 |
option will remove the last disk of the instance. Use |
1260 |
``--disk `` *ID*``:remove`` to remove a disk by its identifier. *ID* |
1261 |
can be the index of the disk, the disks's name or the disks's UUID. The |
1262 |
``--disk *ID*:modify[,options...]`` will change the options of the disk. |
1263 |
Available options are: |
1264 |
|
1265 |
mode |
1266 |
The access mode. Either ``ro`` (read-only) or the default ``rw`` (read-write). |
1267 |
|
1268 |
name |
1269 |
This option specifies a name for the disk, which can be used as a disk |
1270 |
identifier. An instance can not have two disks with the same name. |
1271 |
|
1272 |
The ``--net *N*:add[,options..]`` will add a new network interface to |
1273 |
the instance. The available options are the same as in the **add** |
1274 |
command (``mac``, ``ip``, ``link``, ``mode``, ``network``). The |
1275 |
``--net *ID*,remove`` will remove the intances' NIC with *ID* identifier, |
1276 |
which can be the index of the NIC, the NIC's name or the NIC's UUID. |
1277 |
The ``--net *ID*:modify[,options..]`` option will change the parameters of |
1278 |
the instance network interface with the *ID* identifier. |
1279 |
|
1280 |
The option ``-o (--os-type)`` will change the OS name for the instance |
1281 |
(without reinstallation). In case an OS variant is specified that is |
1282 |
not found, then by default the modification is refused, unless |
1283 |
``--force-variant`` is passed. An invalid OS will also be refused, |
1284 |
unless the ``--force`` option is given. |
1285 |
|
1286 |
The option ``--new-primary`` will set the new primary node of an instance |
1287 |
assuming the disks have already been moved manually. Unless the ``--force`` |
1288 |
option is given, it is verified that the instance is no longer running |
1289 |
on its current primary node. |
1290 |
|
1291 |
The ``--online`` and ``--offline`` options are used to transition an |
1292 |
instance into and out of the ``offline`` state. An instance can be |
1293 |
turned offline only if it was previously down. The ``--online`` option |
1294 |
fails if the instance was not in the ``offline`` state, otherwise it |
1295 |
changes instance's state to ``down``. These modifications take effect |
1296 |
immediately. |
1297 |
|
1298 |
If ``--ignore-ipolicy`` is given any instance policy violations occuring |
1299 |
during this operation are ignored. |
1300 |
|
1301 |
If ``--hotplug`` is given any disk and NIC modifications will take |
1302 |
effect without the need of actual reboot. Please note that this feature |
1303 |
is currently supported only for KVM hypervisor and there are some |
1304 |
restrictions: a) KVM versions >= 1.0 support it b) instances with chroot |
1305 |
or uid pool security model do not support disk hotplug c) RBD disks with |
1306 |
userspace access mode can not be hotplugged (yet) d) if hotplug fails |
1307 |
(for any reason) a warning is printed but execution is continued e) |
1308 |
for existing NIC modification interactive verification is needed unless |
1309 |
``--force`` option is passed. |
1310 |
|
1311 |
If ``--hotplug-if-possible`` is given then ganeti won't abort in case |
1312 |
hotplug is not supported. It will continue execution and modification |
1313 |
will take place after reboot. This covers use cases where instances are |
1314 |
not running or hypervisor is not KVM. |
1315 |
|
1316 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1317 |
options. |
1318 |
|
1319 |
Most of the changes take effect at the next restart. If the instance is |
1320 |
running, there is no effect on the instance. |
1321 |
|
1322 |
REINSTALL |
1323 |
^^^^^^^^^ |
1324 |
|
1325 |
| **reinstall** [{-o|\--os-type} *os-type*] [\--select-os] [-f *force*] |
1326 |
| [\--force-multiple] |
1327 |
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all] |
1328 |
| [{-O|\--os-parameters} *OS\_PARAMETERS*] |
1329 |
| [--os-parameters-private} *OS\_PARAMETERS*] |
1330 |
| [--os-parameters-secret} *OS\_PARAMETERS*] |
1331 |
| [\--submit] [\--print-job-id] |
1332 |
| {*instance*...} |
1333 |
|
1334 |
Reinstalls the operating system on the given instance(s). The |
1335 |
instance(s) must be stopped when running this command. If the ``-o |
1336 |
(--os-type)`` is specified, the operating system is changed. |
1337 |
|
1338 |
The ``--select-os`` option switches to an interactive OS reinstall. |
1339 |
The user is prompted to select the OS template from the list of |
1340 |
available OS templates. OS parameters can be overridden using ``-O |
1341 |
(--os-parameters)`` (more documentation for this option under the |
1342 |
**add** command). |
1343 |
|
1344 |
Since this is a potentially dangerous command, the user will be |
1345 |
required to confirm this action, unless the ``-f`` flag is passed. |
1346 |
When multiple instances are selected (either by passing multiple |
1347 |
arguments or by using the ``--node``, ``--primary``, ``--secondary`` |
1348 |
or ``--all`` options), the user must pass the ``--force-multiple`` |
1349 |
options to skip the interactive confirmation. |
1350 |
|
1351 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1352 |
options. |
1353 |
|
1354 |
RENAME |
1355 |
^^^^^^ |
1356 |
|
1357 |
| **rename** [\--no-ip-check] [\--no-name-check] [\--submit] [\--print-job-id] |
1358 |
| {*instance*} {*new\_name*} |
1359 |
|
1360 |
Renames the given instance. The instance must be stopped when running |
1361 |
this command. The requirements for the new name are the same as for |
1362 |
adding an instance: the new name must be resolvable and the IP it |
1363 |
resolves to must not be reachable (in order to prevent duplicate IPs |
1364 |
the next time the instance is started). The IP test can be skipped if |
1365 |
the ``--no-ip-check`` option is passed. |
1366 |
|
1367 |
Note that you can rename an instance to its same name, to force |
1368 |
re-executing the os-specific rename script for that instance, if |
1369 |
needed. |
1370 |
|
1371 |
The ``--no-name-check`` skips the check for the new instance name via |
1372 |
the resolver (e.g. in DNS or /etc/hosts, depending on your setup) and |
1373 |
that the resolved name matches the provided name. Since the name check |
1374 |
is used to compute the IP address, if you pass this option you must also |
1375 |
pass the ``--no-ip-check`` option. |
1376 |
|
1377 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1378 |
options. |
1379 |
|
1380 |
Starting/stopping/connecting to console |
1381 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
1382 |
|
1383 |
STARTUP |
1384 |
^^^^^^^ |
1385 |
|
1386 |
| **startup** |
1387 |
| [\--force] [\--ignore-offline] |
1388 |
| [\--force-multiple] [\--no-remember] |
1389 |
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \| |
1390 |
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags] |
1391 |
| [{-H|\--hypervisor-parameters} ``key=value...``] |
1392 |
| [{-B|\--backend-parameters} ``key=value...``] |
1393 |
| [\--submit] [\--print-job-id] [\--paused] |
1394 |
| {*name*...} |
1395 |
|
1396 |
Starts one or more instances, depending on the following options. The |
1397 |
four available modes are: |
1398 |
|
1399 |
\--instance |
1400 |
will start the instances given as arguments (at least one argument |
1401 |
required); this is the default selection |
1402 |
|
1403 |
\--node |
1404 |
will start the instances who have the given node as either primary |
1405 |
or secondary |
1406 |
|
1407 |
\--primary |
1408 |
will start all instances whose primary node is in the list of nodes |
1409 |
passed as arguments (at least one node required) |
1410 |
|
1411 |
\--secondary |
1412 |
will start all instances whose secondary node is in the list of |
1413 |
nodes passed as arguments (at least one node required) |
1414 |
|
1415 |
\--all |
1416 |
will start all instances in the cluster (no arguments accepted) |
1417 |
|
1418 |
\--tags |
1419 |
will start all instances in the cluster with the tags given as |
1420 |
arguments |
1421 |
|
1422 |
\--node-tags |
1423 |
will start all instances in the cluster on nodes with the tags |
1424 |
given as arguments |
1425 |
|
1426 |
\--pri-node-tags |
1427 |
will start all instances in the cluster on primary nodes with the |
1428 |
tags given as arguments |
1429 |
|
1430 |
\--sec-node-tags |
1431 |
will start all instances in the cluster on secondary nodes with the |
1432 |
tags given as arguments |
1433 |
|
1434 |
Note that although you can pass more than one selection option, the |
1435 |
last one wins, so in order to guarantee the desired result, don't pass |
1436 |
more than one such option. |
1437 |
|
1438 |
Use ``--force`` to start even if secondary disks are failing. |
1439 |
``--ignore-offline`` can be used to ignore offline primary nodes and |
1440 |
mark the instance as started even if the primary is not available. |
1441 |
|
1442 |
The ``--force-multiple`` will skip the interactive confirmation in the |
1443 |
case the more than one instance will be affected. |
1444 |
|
1445 |
The ``--no-remember`` option will perform the startup but not change |
1446 |
the state of the instance in the configuration file (if it was stopped |
1447 |
before, Ganeti will still think it needs to be stopped). This can be |
1448 |
used for testing, or for a one shot-start where you don't want the |
1449 |
watcher to restart the instance if it crashes. |
1450 |
|
1451 |
The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)`` |
1452 |
options specify temporary hypervisor and backend parameters that can |
1453 |
be used to start an instance with modified parameters. They can be |
1454 |
useful for quick testing without having to modify an instance back and |
1455 |
forth, e.g.:: |
1456 |
|
1457 |
# gnt-instance start -H kernel_args="single" instance1 |
1458 |
# gnt-instance start -B maxmem=2048 instance2 |
1459 |
|
1460 |
|
1461 |
The first form will start the instance instance1 in single-user mode, |
1462 |
and the instance instance2 with 2GB of RAM (this time only, unless |
1463 |
that is the actual instance memory size already). Note that the values |
1464 |
override the instance parameters (and not extend them): an instance |
1465 |
with "kernel\_args=ro" when started with -H kernel\_args=single will |
1466 |
result in "single", not "ro single". |
1467 |
|
1468 |
The ``--paused`` option is only valid for Xen and kvm hypervisors. This |
1469 |
pauses the instance at the start of bootup, awaiting ``gnt-instance |
1470 |
console`` to unpause it, allowing the entire boot process to be |
1471 |
monitored for debugging. |
1472 |
|
1473 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1474 |
options. |
1475 |
|
1476 |
Example:: |
1477 |
|
1478 |
# gnt-instance start instance1.example.com |
1479 |
# gnt-instance start --node node1.example.com node2.example.com |
1480 |
# gnt-instance start --all |
1481 |
|
1482 |
|
1483 |
SHUTDOWN |
1484 |
^^^^^^^^ |
1485 |
|
1486 |
| **shutdown** |
1487 |
| [\--timeout=*N*] |
1488 |
| [\--force] [\--force-multiple] [\--ignore-offline] [\--no-remember] |
1489 |
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \| |
1490 |
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags] |
1491 |
| [\--submit] [\--print-job-id] |
1492 |
| {*name*...} |
1493 |
|
1494 |
Stops one or more instances. If the instance cannot be cleanly stopped |
1495 |
during a hardcoded interval (currently 2 minutes), it will forcibly |
1496 |
stop the instance (equivalent to switching off the power on a physical |
1497 |
machine). |
1498 |
|
1499 |
The ``--timeout`` is used to specify how much time to wait before |
1500 |
forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the kvm |
1501 |
process for KVM, etc.). By default two minutes are given to each |
1502 |
instance to stop. |
1503 |
|
1504 |
The ``--instance``, ``--node``, ``--primary``, ``--secondary``, |
1505 |
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and |
1506 |
``--sec-node-tags`` options are similar as for the **startup** command |
1507 |
and they influence the actual instances being shutdown. |
1508 |
|
1509 |
``--ignore-offline`` can be used to ignore offline primary nodes and |
1510 |
force the instance to be marked as stopped. This option should be used |
1511 |
with care as it can lead to an inconsistent cluster state. |
1512 |
|
1513 |
Use ``--force`` to be able to shutdown an instance even when it's marked |
1514 |
as offline. This is useful is an offline instance ends up in the |
1515 |
``ERROR_up`` state, for example. |
1516 |
|
1517 |
The ``--no-remember`` option will perform the shutdown but not change |
1518 |
the state of the instance in the configuration file (if it was running |
1519 |
before, Ganeti will still thinks it needs to be running). This can be |
1520 |
useful for a cluster-wide shutdown, where some instances are marked as |
1521 |
up and some as down, and you don't want to change the running state: |
1522 |
you just need to disable the watcher, shutdown all instances with |
1523 |
``--no-remember``, and when the watcher is activated again it will |
1524 |
restore the correct runtime state for all instances. |
1525 |
|
1526 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1527 |
options. |
1528 |
|
1529 |
Example:: |
1530 |
|
1531 |
# gnt-instance shutdown instance1.example.com |
1532 |
# gnt-instance shutdown --all |
1533 |
|
1534 |
|
1535 |
REBOOT |
1536 |
^^^^^^ |
1537 |
|
1538 |
| **reboot** |
1539 |
| [{-t|\--type} *REBOOT-TYPE*] |
1540 |
| [\--ignore-secondaries] |
1541 |
| [\--shutdown-timeout=*N*] |
1542 |
| [\--force-multiple] |
1543 |
| [\--instance \| \--node \| \--primary \| \--secondary \| \--all \| |
1544 |
| \--tags \| \--node-tags \| \--pri-node-tags \| \--sec-node-tags] |
1545 |
| [\--submit] [\--print-job-id] |
1546 |
| [*name*...] |
1547 |
|
1548 |
Reboots one or more instances. The type of reboot depends on the value |
1549 |
of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot |
1550 |
does a instance stop, recreates the hypervisor config for the instance |
1551 |
and starts the instance. A full reboot does the equivalent of |
1552 |
**gnt-instance shutdown && gnt-instance startup**. The default is |
1553 |
hard reboot. |
1554 |
|
1555 |
For the hard reboot the option ``--ignore-secondaries`` ignores errors |
1556 |
for the secondary node while re-assembling the instance disks. |
1557 |
|
1558 |
The ``--instance``, ``--node``, ``--primary``, ``--secondary``, |
1559 |
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and |
1560 |
``--sec-node-tags`` options are similar as for the **startup** command |
1561 |
and they influence the actual instances being rebooted. |
1562 |
|
1563 |
The ``--shutdown-timeout`` is used to specify how much time to wait |
1564 |
before forcing the shutdown (xm destroy in xen, killing the kvm |
1565 |
process, for kvm). By default two minutes are given to each instance |
1566 |
to stop. |
1567 |
|
1568 |
The ``--force-multiple`` will skip the interactive confirmation in the |
1569 |
case the more than one instance will be affected. |
1570 |
|
1571 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1572 |
options. |
1573 |
|
1574 |
Example:: |
1575 |
|
1576 |
# gnt-instance reboot instance1.example.com |
1577 |
# gnt-instance reboot --type=full instance1.example.com |
1578 |
|
1579 |
|
1580 |
CONSOLE |
1581 |
^^^^^^^ |
1582 |
|
1583 |
**console** [\--show-cmd] {*instance*} |
1584 |
|
1585 |
Connects to the console of the given instance. If the instance is not |
1586 |
up, an error is returned. Use the ``--show-cmd`` option to display the |
1587 |
command instead of executing it. |
1588 |
|
1589 |
For HVM instances, this will attempt to connect to the serial console |
1590 |
of the instance. To connect to the virtualized "physical" console of a |
1591 |
HVM instance, use a VNC client with the connection info from the |
1592 |
**info** command. |
1593 |
|
1594 |
For Xen/kvm instances, if the instance is paused, this attempts to |
1595 |
unpause the instance after waiting a few seconds for the connection to |
1596 |
the console to be made. |
1597 |
|
1598 |
Example:: |
1599 |
|
1600 |
# gnt-instance console instance1.example.com |
1601 |
|
1602 |
|
1603 |
Disk management |
1604 |
~~~~~~~~~~~~~~~ |
1605 |
|
1606 |
REPLACE-DISKS |
1607 |
^^^^^^^^^^^^^ |
1608 |
|
1609 |
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release] |
1610 |
| [\--ignore-ipolicy] {-p} [\--disks *idx*] {*instance*} |
1611 |
|
1612 |
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release] |
1613 |
| [\--ignore-ipolicy] {-s} [\--disks *idx*] {*instance*} |
1614 |
|
1615 |
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release] |
1616 |
| [\--ignore-ipolicy] |
1617 |
| {{-I\|\--iallocator} *name* \| {{-n|\--new-secondary} *node* } {*instance*} |
1618 |
|
1619 |
| **replace-disks** [\--submit] [\--print-job-id] [\--early-release] |
1620 |
| [\--ignore-ipolicy] {-a\|\--auto} {*instance*} |
1621 |
|
1622 |
This command is a generalized form for replacing disks. It is |
1623 |
currently only valid for the mirrored (DRBD) disk template. |
1624 |
|
1625 |
The first form (when passing the ``-p`` option) will replace the disks |
1626 |
on the primary, while the second form (when passing the ``-s`` option |
1627 |
will replace the disks on the secondary node. For these two cases (as |
1628 |
the node doesn't change), it is possible to only run the replace for a |
1629 |
subset of the disks, using the option ``--disks`` which takes a list |
1630 |
of comma-delimited disk indices (zero-based), e.g. 0,2 to replace only |
1631 |
the first and third disks. |
1632 |
|
1633 |
The third form (when passing either the ``--iallocator`` or the |
1634 |
``--new-secondary`` option) is designed to change secondary node of the |
1635 |
instance. Specifying ``--iallocator`` makes the new secondary be |
1636 |
selected automatically by the specified allocator plugin (use ``.`` to |
1637 |
indicate the default allocator), otherwise the new secondary node will |
1638 |
be the one chosen manually via the ``--new-secondary`` option. |
1639 |
|
1640 |
Note that it is not possible to select an offline or drained node as a |
1641 |
new secondary. |
1642 |
|
1643 |
The fourth form (when using ``--auto``) will automatically determine |
1644 |
which disks of an instance are faulty and replace them within the same |
1645 |
node. The ``--auto`` option works only when an instance has only |
1646 |
faulty disks on either the primary or secondary node; it doesn't work |
1647 |
when both sides have faulty disks. |
1648 |
|
1649 |
The ``--early-release`` changes the code so that the old storage on |
1650 |
secondary node(s) is removed early (before the resync is completed) |
1651 |
and the internal Ganeti locks for the current (and new, if any) |
1652 |
secondary node are also released, thus allowing more parallelism in |
1653 |
the cluster operation. This should be used only when recovering from a |
1654 |
disk failure on the current secondary (thus the old storage is already |
1655 |
broken) or when the storage on the primary node is known to be fine |
1656 |
(thus we won't need the old storage for potential recovery). |
1657 |
|
1658 |
The ``--ignore-ipolicy`` let the command ignore instance policy |
1659 |
violations if replace-disks changes groups and the instance would |
1660 |
violate the new groups instance policy. |
1661 |
|
1662 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1663 |
options. |
1664 |
|
1665 |
ACTIVATE-DISKS |
1666 |
^^^^^^^^^^^^^^ |
1667 |
|
1668 |
| **activate-disks** [\--submit] [\--print-job-id] [\--ignore-size] |
1669 |
| [\--wait-for-sync] {*instance*} |
1670 |
|
1671 |
Activates the block devices of the given instance. If successful, the |
1672 |
command will show the location and name of the block devices:: |
1673 |
|
1674 |
node1.example.com:disk/0:/dev/drbd0 |
1675 |
node1.example.com:disk/1:/dev/drbd1 |
1676 |
|
1677 |
|
1678 |
In this example, *node1.example.com* is the name of the node on which |
1679 |
the devices have been activated. The *disk/0* and *disk/1* are the |
1680 |
Ganeti-names of the instance disks; how they are visible inside the |
1681 |
instance is hypervisor-specific. */dev/drbd0* and */dev/drbd1* are the |
1682 |
actual block devices as visible on the node. |
1683 |
|
1684 |
The ``--ignore-size`` option can be used to activate disks ignoring |
1685 |
the currently configured size in Ganeti. This can be used in cases |
1686 |
where the configuration has gotten out of sync with the real-world |
1687 |
(e.g. after a partially-failed grow-disk operation or due to rounding |
1688 |
in LVM devices). This should not be used in normal cases, but only |
1689 |
when activate-disks fails without it. |
1690 |
|
1691 |
The ``--wait-for-sync`` option will ensure that the command returns only |
1692 |
after the instance's disks are synchronised (mostly for DRBD); this can |
1693 |
be useful to ensure consistency, as otherwise there are no commands that |
1694 |
can wait until synchronisation is done. However when passing this |
1695 |
option, the command will have additional output, making it harder to |
1696 |
parse the disk information. |
1697 |
|
1698 |
Note that it is safe to run this command while the instance is already |
1699 |
running. |
1700 |
|
1701 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1702 |
options. |
1703 |
|
1704 |
DEACTIVATE-DISKS |
1705 |
^^^^^^^^^^^^^^^^ |
1706 |
|
1707 |
**deactivate-disks** [-f] [\--submit] [\--print-job-id] {*instance*} |
1708 |
|
1709 |
De-activates the block devices of the given instance. Note that if you |
1710 |
run this command for an instance with a drbd disk template, while it |
1711 |
is running, it will not be able to shutdown the block devices on the |
1712 |
primary node, but it will shutdown the block devices on the secondary |
1713 |
nodes, thus breaking the replication. |
1714 |
|
1715 |
The ``-f``/``--force`` option will skip checks that the instance is |
1716 |
down; in case the hypervisor is confused and we can't talk to it, |
1717 |
normally Ganeti will refuse to deactivate the disks, but with this |
1718 |
option passed it will skip this check and directly try to deactivate |
1719 |
the disks. This can still fail due to the instance actually running or |
1720 |
other issues. |
1721 |
|
1722 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1723 |
options. |
1724 |
|
1725 |
GROW-DISK |
1726 |
^^^^^^^^^ |
1727 |
|
1728 |
| **grow-disk** [\--no-wait-for-sync] [\--submit] [\--print-job-id] |
1729 |
| [\--absolute] |
1730 |
| {*instance*} {*disk*} {*amount*} |
1731 |
|
1732 |
Grows an instance's disk. This is only possible for instances having a |
1733 |
plain, drbd, file, sharedfile, rbd or ext disk template. For the ext |
1734 |
template to work, the ExtStorage provider should also support growing. |
1735 |
This means having a ``grow`` script that actually grows the volume of |
1736 |
the external shared storage. |
1737 |
|
1738 |
Note that this command only change the block device size; it will not |
1739 |
grow the actual filesystems, partitions, etc. that live on that |
1740 |
disk. Usually, you will need to: |
1741 |
|
1742 |
#. use **gnt-instance grow-disk** |
1743 |
|
1744 |
#. reboot the instance (later, at a convenient time) |
1745 |
|
1746 |
#. use a filesystem resizer, such as **ext2online**\(8) or |
1747 |
**xfs\_growfs**\(8) to resize the filesystem, or use **fdisk**\(8) to |
1748 |
change the partition table on the disk |
1749 |
|
1750 |
The *disk* argument is the index of the instance disk to grow. The |
1751 |
*amount* argument is given as a number which can have a suffix (like the |
1752 |
disk size in instance create); if the suffix is missing, the value will |
1753 |
be interpreted as mebibytes. |
1754 |
|
1755 |
By default, the *amount* value represents the desired increase in the |
1756 |
disk size (e.g. an amount of 1G will take a disk of size 3G to 4G). If |
1757 |
the optional ``--absolute`` parameter is passed, then the *amount* |
1758 |
argument doesn't represent the delta, but instead the desired final disk |
1759 |
size (e.g. an amount of 8G will take a disk of size 4G to 8G). |
1760 |
|
1761 |
For instances with a drbd template, note that the disk grow operation |
1762 |
might complete on one node but fail on the other; this will leave the |
1763 |
instance with different-sized LVs on the two nodes, but this will not |
1764 |
create problems (except for unused space). |
1765 |
|
1766 |
If you do not want gnt-instance to wait for the new disk region to be |
1767 |
synced, use the ``--no-wait-for-sync`` option. |
1768 |
|
1769 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1770 |
options. |
1771 |
|
1772 |
Example (increase the first disk for instance1 by 16GiB):: |
1773 |
|
1774 |
# gnt-instance grow-disk instance1.example.com 0 16g |
1775 |
|
1776 |
Example for increasing the disk size to a certain size:: |
1777 |
|
1778 |
# gnt-instance grow-disk --absolute instance1.example.com 0 32g |
1779 |
|
1780 |
Also note that disk shrinking is not supported; use **gnt-backup |
1781 |
export** and then **gnt-backup import** to reduce the disk size of an |
1782 |
instance. |
1783 |
|
1784 |
RECREATE-DISKS |
1785 |
^^^^^^^^^^^^^^ |
1786 |
|
1787 |
| **recreate-disks** [\--submit] [\--print-job-id] |
1788 |
| [{-n node1:[node2] \| {-I\|\--iallocator *name*}}] |
1789 |
| [\--disk=*N*[:[size=*VAL*][,spindles=*VAL*][,mode=*ro\|rw*]]] {*instance*} |
1790 |
|
1791 |
Recreates all or a subset of disks of the given instance. |
1792 |
|
1793 |
Note that this functionality should only be used for missing disks; if |
1794 |
any of the given disks already exists, the operation will fail. While |
1795 |
this is suboptimal, recreate-disks should hopefully not be needed in |
1796 |
normal operation and as such the impact of this is low. |
1797 |
|
1798 |
If only a subset should be recreated, any number of ``disk`` options can |
1799 |
be specified. It expects a disk index and an optional list of disk |
1800 |
parameters to change. Only ``size``, ``spindles``, and ``mode`` can be |
1801 |
changed while recreating disks. To recreate all disks while changing |
1802 |
parameters on a subset only, a ``--disk`` option must be given for every |
1803 |
disk of the instance. |
1804 |
|
1805 |
Optionally the instance's disks can be recreated on different |
1806 |
nodes. This can be useful if, for example, the original nodes of the |
1807 |
instance have gone down (and are marked offline), so we can't recreate |
1808 |
on the same nodes. To do this, pass the new node(s) via ``-n`` option, |
1809 |
with a syntax similar to the **add** command. The number of nodes |
1810 |
passed must equal the number of nodes that the instance currently |
1811 |
has. Note that changing nodes is only allowed when all disks are |
1812 |
replaced, e.g. when no ``--disk`` option is passed. |
1813 |
|
1814 |
Another method of choosing which nodes to place the instance on is by |
1815 |
using the specified iallocator, passing the ``--iallocator`` option. |
1816 |
The primary and secondary nodes will be chosen by the specified |
1817 |
iallocator plugin, or by the default allocator if ``.`` is specified. |
1818 |
|
1819 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1820 |
options. |
1821 |
|
1822 |
Recovery/moving |
1823 |
~~~~~~~~~~~~~~~ |
1824 |
|
1825 |
FAILOVER |
1826 |
^^^^^^^^ |
1827 |
|
1828 |
| **failover** [-f] [\--ignore-consistency] [\--ignore-ipolicy] |
1829 |
| [\--shutdown-timeout=*N*] |
1830 |
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] |
1831 |
| [\--cleanup] |
1832 |
| [\--submit] [\--print-job-id] |
1833 |
| {*instance*} |
1834 |
|
1835 |
Failover will stop the instance (if running), change its primary node, |
1836 |
and if it was originally running it will start it again (on the new |
1837 |
primary). This works for instances with drbd template (in which case you |
1838 |
can only fail to the secondary node) and for externally mirrored |
1839 |
templates (sharedfile, blockdev, rbd and ext) (in which case you can |
1840 |
fail to any other node). |
1841 |
|
1842 |
If the instance's disk template is of type sharedfile, blockdev, rbd or |
1843 |
ext, then you can explicitly specify the target node (which can be any |
1844 |
node) using the ``-n`` or ``--target-node`` option, or specify an |
1845 |
iallocator plugin using the ``-I`` or ``--iallocator`` option. If you |
1846 |
omit both, the default iallocator will be used to specify the target |
1847 |
node. |
1848 |
|
1849 |
If the instance's disk template is of type drbd, the target node is |
1850 |
automatically selected as the drbd's secondary node. Changing the |
1851 |
secondary node is possible with a replace-disks operation. |
1852 |
|
1853 |
Normally the failover will check the consistency of the disks before |
1854 |
failing over the instance. If you are trying to migrate instances off |
1855 |
a dead node, this will fail. Use the ``--ignore-consistency`` option |
1856 |
for this purpose. Note that this option can be dangerous as errors in |
1857 |
shutting down the instance will be ignored, resulting in possibly |
1858 |
having the instance running on two machines in parallel (on |
1859 |
disconnected DRBD drives). |
1860 |
|
1861 |
The ``--shutdown-timeout`` is used to specify how much time to wait |
1862 |
before forcing the shutdown (xm destroy in xen, killing the kvm |
1863 |
process, for kvm). By default two minutes are given to each instance |
1864 |
to stop. |
1865 |
|
1866 |
If ``--ignore-ipolicy`` is given any instance policy violations occuring |
1867 |
during this operation are ignored. |
1868 |
|
1869 |
If the ``--cleanup`` option is passed, the operation changes from |
1870 |
performin a failover to attempting recovery from a failed previous failover. |
1871 |
In this mode, Ganeti checks if the instance runs on the correct node (and |
1872 |
updates its configuration if not) and ensures the instances' disks |
1873 |
are configured correctly. |
1874 |
|
1875 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1876 |
options. |
1877 |
|
1878 |
Example:: |
1879 |
|
1880 |
# gnt-instance failover instance1.example.com |
1881 |
|
1882 |
For externally mirrored templates also ``-n`` is available:: |
1883 |
|
1884 |
# gnt-instance failover -n node3.example.com instance1.example.com |
1885 |
|
1886 |
|
1887 |
MIGRATE |
1888 |
^^^^^^^ |
1889 |
|
1890 |
| **migrate** [-f] [\--allow-failover] [\--non-live] |
1891 |
| [\--migration-mode=live\|non-live] [\--ignore-ipolicy] |
1892 |
| [\--no-runtime-changes] [\--submit] [\--print-job-id] |
1893 |
| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*} |
1894 |
|
1895 |
| **migrate** [-f] \--cleanup [\--submit] [\--print-job-id] {*instance*} |
1896 |
|
1897 |
Migrate will move the instance to its secondary node without shutdown. |
1898 |
As with failover, it works for instances having the drbd disk template |
1899 |
or an externally mirrored disk template type such as sharedfile, |
1900 |
blockdev, rbd or ext. |
1901 |
|
1902 |
If the instance's disk template is of type sharedfile, blockdev, rbd or |
1903 |
ext, then you can explicitly specify the target node (which can be any |
1904 |
node) using the ``-n`` or ``--target-node`` option, or specify an |
1905 |
iallocator plugin using the ``-I`` or ``--iallocator`` option. If you |
1906 |
omit both, the default iallocator will be used to specify the target |
1907 |
node. Alternatively, the default iallocator can be requested by |
1908 |
specifying ``.`` as the name of the plugin. |
1909 |
|
1910 |
If the instance's disk template is of type drbd, the target node is |
1911 |
automatically selected as the drbd's secondary node. Changing the |
1912 |
secondary node is possible with a replace-disks operation. |
1913 |
|
1914 |
The migration command needs a perfectly healthy instance for drbd |
1915 |
instances, as we rely on the dual-master capability of drbd8 and the |
1916 |
disks of the instance are not allowed to be degraded. |
1917 |
|
1918 |
The ``--non-live`` and ``--migration-mode=non-live`` options will |
1919 |
switch (for the hypervisors that support it) between a "fully live" |
1920 |
(i.e. the interruption is as minimal as possible) migration and one in |
1921 |
which the instance is frozen, its state saved and transported to the |
1922 |
remote node, and then resumed there. This all depends on the |
1923 |
hypervisor support for two different methods. In any case, it is not |
1924 |
an error to pass this parameter (it will just be ignored if the |
1925 |
hypervisor doesn't support it). The option ``--migration-mode=live`` |
1926 |
option will request a fully-live migration. The default, when neither |
1927 |
option is passed, depends on the hypervisor parameters (and can be |
1928 |
viewed with the **gnt-cluster info** command). |
1929 |
|
1930 |
If the ``--cleanup`` option is passed, the operation changes from |
1931 |
migration to attempting recovery from a failed previous migration. In |
1932 |
this mode, Ganeti checks if the instance runs on the correct node (and |
1933 |
updates its configuration if not) and ensures the instances' disks |
1934 |
are configured correctly. In this mode, the ``--non-live`` option is |
1935 |
ignored. |
1936 |
|
1937 |
The option ``-f`` will skip the prompting for confirmation. |
1938 |
|
1939 |
If ``--allow-failover`` is specified it tries to fallback to failover if |
1940 |
it already can determine that a migration won't work (e.g. if the |
1941 |
instance is shut down). Please note that the fallback will not happen |
1942 |
during execution. If a migration fails during execution it still fails. |
1943 |
|
1944 |
If ``--ignore-ipolicy`` is given any instance policy violations occuring |
1945 |
during this operation are ignored. |
1946 |
|
1947 |
The ``--no-runtime-changes`` option forbids migrate to alter an |
1948 |
instance's runtime before migrating it (eg. ballooning an instance |
1949 |
down because the target node doesn't have enough available memory). |
1950 |
|
1951 |
If an instance has the backend parameter ``always_failover`` set to |
1952 |
true, then the migration is automatically converted into a failover. |
1953 |
|
1954 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
1955 |
options. |
1956 |
|
1957 |
Example (and expected output):: |
1958 |
|
1959 |
# gnt-instance migrate instance1 |
1960 |
Instance instance1 will be migrated. Note that migration |
1961 |
might impact the instance if anything goes wrong (e.g. due to bugs in |
1962 |
the hypervisor). Continue? |
1963 |
y/[n]/?: y |
1964 |
Migrating instance instance1.example.com |
1965 |
* checking disk consistency between source and target |
1966 |
* switching node node2.example.com to secondary mode |
1967 |
* changing into standalone mode |
1968 |
* changing disks into dual-master mode |
1969 |
* wait until resync is done |
1970 |
* preparing node2.example.com to accept the instance |
1971 |
* migrating instance to node2.example.com |
1972 |
* switching node node1.example.com to secondary mode |
1973 |
* wait until resync is done |
1974 |
* changing into standalone mode |
1975 |
* changing disks into single-master mode |
1976 |
* wait until resync is done |
1977 |
* done |
1978 |
# |
1979 |
|
1980 |
|
1981 |
MOVE |
1982 |
^^^^ |
1983 |
|
1984 |
| **move** [-f] [\--ignore-consistency] |
1985 |
| [-n *node*] [\--compress=*compression-mode*] [\--shutdown-timeout=*N*] |
1986 |
| [\--submit] [\--print-job-id] [\--ignore-ipolicy] |
1987 |
| {*instance*} |
1988 |
|
1989 |
Move will move the instance to an arbitrary node in the cluster. This |
1990 |
works only for instances having a plain or file disk template. |
1991 |
|
1992 |
Note that since this operation is done via data copy, it will take a |
1993 |
long time for big disks (similar to replace-disks for a drbd |
1994 |
instance). |
1995 |
|
1996 |
The ``--compress`` option is used to specify which compression mode |
1997 |
is used during the move. Valid values are 'none' (the default) and |
1998 |
'gzip'. |
1999 |
|
2000 |
The ``--shutdown-timeout`` is used to specify how much time to wait |
2001 |
before forcing the shutdown (e.g. ``xm destroy`` in XEN, killing the |
2002 |
kvm process for KVM, etc.). By default two minutes are given to each |
2003 |
instance to stop. |
2004 |
|
2005 |
The ``--ignore-consistency`` option will make Ganeti ignore any errors |
2006 |
in trying to shutdown the instance on its node; useful if the |
2007 |
hypervisor is broken and you want to recover the data. |
2008 |
|
2009 |
If ``--ignore-ipolicy`` is given any instance policy violations occuring |
2010 |
during this operation are ignored. |
2011 |
|
2012 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
2013 |
options. |
2014 |
|
2015 |
Example:: |
2016 |
|
2017 |
# gnt-instance move -n node3.example.com instance1.example.com |
2018 |
|
2019 |
|
2020 |
CHANGE-GROUP |
2021 |
^^^^^^^^^^^^ |
2022 |
|
2023 |
| **change-group** [\--submit] [\--print-job-id] |
2024 |
| [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*} |
2025 |
|
2026 |
This command moves an instance to another node group. The move is |
2027 |
calculated by an iallocator, either given on the command line or as a |
2028 |
cluster default. Note that the iallocator does only consider disk |
2029 |
information of the default disk template, even if the instances' |
2030 |
disk templates differ from that. |
2031 |
|
2032 |
If no specific destination groups are specified using ``--to``, all |
2033 |
groups except the one containing the instance are considered. |
2034 |
|
2035 |
See **ganeti**\(7) for a description of ``--submit`` and other common |
2036 |
options. |
2037 |
|
2038 |
Example:: |
2039 |
|
2040 |
# gnt-instance change-group -I hail --to rack2 inst1.example.com |
2041 |
|
2042 |
|
2043 |
Tags |
2044 |
~~~~ |
2045 |
|
2046 |
ADD-TAGS |
2047 |
^^^^^^^^ |
2048 |
|
2049 |
**add-tags** [\--from *file*] {*instancename*} {*tag*...} |
2050 |
|
2051 |
Add tags to the given instance. If any of the tags contains invalid |
2052 |
characters, the entire operation will abort. |
2053 |
|
2054 |
If the ``--from`` option is given, the list of tags will be extended |
2055 |
with the contents of that file (each line becomes a tag). In this |
2056 |
case, there is not need to pass tags on the command line (if you do, |
2057 |
both sources will be used). A file name of ``-`` will be interpreted |
2058 |
as stdin. |
2059 |
|
2060 |
LIST-TAGS |
2061 |
^^^^^^^^^ |
2062 |
|
2063 |
**list-tags** {*instancename*} |
2064 |
|
2065 |
List the tags of the given instance. |
2066 |
|
2067 |
REMOVE-TAGS |
2068 |
^^^^^^^^^^^ |
2069 |
|
2070 |
**remove-tags** [\--from *file*] {*instancename*} {*tag*...} |
2071 |
|
2072 |
Remove tags from the given instance. If any of the tags are not |
2073 |
existing on the node, the entire operation will abort. |
2074 |
|
2075 |
If the ``--from`` option is given, the list of tags to be removed will |
2076 |
be extended with the contents of that file (each line becomes a tag). |
2077 |
In this case, there is not need to pass tags on the command line (if |
2078 |
you do, tags from both sources will be removed). A file name of ``-`` |
2079 |
will be interpreted as stdin. |
2080 |
|
2081 |
.. vim: set textwidth=72 : |
2082 |
.. Local Variables: |
2083 |
.. mode: rst |
2084 |
.. fill-column: 72 |
2085 |
.. End: |