vm-install(8)vm-install(8)NAMEvm-install - define a virtual machine and install its operating system
SYNOPSIS
Interactive VM creation:
vm-install [options ...]
Non-interactive VM creation:
vm-install [--vm-settings vm.xml] [--os-settings os-settings] [--os-
type os-type] [--background]
DESCRIPTIONvm-install can define a KVM or Xen virtual machine, and cause an oper‐
ating system to begin installing within that virtual machine.
vm-install can be used in a variety of ways. Some examples:
It can be used interactively at the command line or graphically.
It can accept command line parameters, then interactively prompt
for the remaining parameters.
It can automatically pick reasonable VM defaults for a given
type of operating system.
It can perform completely non-interactive installs, driven via
XML files and/or command line parameters.
The supporting Python modules can be 'import'-ed into other
Python programs, to create VMs programmatically.
OPTIONSvm-install accepts three types of options: Those that affect the defi‐
nition of the virtual machine, those that affect the installation of
the operating system, and those that guide the tool itself.
Options that affect the VM settings:
-a VALUE, --audio VALUE
Sets the type of audio hardware for fully virtualized guests.
Valid values are: ac97 (Intel 82801AA Audio Codec 97), es1370
(Ensoniq AudioPCI ES1370), ich6 (Intel I/O Controller Hub 6),
sb16 (Creative Sound Blaster 16), all (Enable all audio devices
- Xen only), none (No audio support).
--advanced ADVANCED
Set an advanced option for fully virtualized guests: ADVANCED is
in the form of OPTION=VALUE[,OPTION=VALUE,...].
A list of available options that may be modified can be viewed
from within the GUI. From the ´Summary´ screen select ´Hard‐
ware´ and then the ´Advanced Settings´ button.
It is expected that the user understands the consequences of
changing these settings. An incorrect setting could result in a
failed guest installation or post installation problems.
-c N, --vcpus N
Number of virtual CPUs to allocate to the VM.
--cpuid CPUID (Xen only)
Present the fully virtualized VM with cpuid information for pro‐
cessor compatibility: CPUID is in the form of FUNC‐
TION:REG=[,[REG=],[FUNCTION:[REG=],...]].
FUNCTION contains the eax register value as defined by the cpuid
processor instruction and represents the function needed to
define a set of processor features.
REG is a register whose value represents the set of processors
feature to enable or disable. Valid REG values are (eax, ecx,
ebx, and hedx).
For example, --cpuid 1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
Valid values are x, 0, 1, k, s
See also /etc/xen/examples/xmexample.hvm.
--cpu-check CPUCHECK (Xen only)
Defines the hosts cpuid consistency checks that must be satis‐
fied for this fully virtualized VM to be allowed to run on the
hosts processor type: CPUCHECK is in the form of FUNC‐
TION:REG=[,[REG=],[FUNCTION:[REG=],...]].
FUNCTION contains the eax register value as defined by the cpuid
processor instruction and represents the function needed to
define a set of processor features.
REG is a register whose value represents the set of processors
feature to enable or disable. Valid REG values are (eax, ecx,
ebx, and hedx).
For example, --cpu-check 1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
Valid values are x, 0, 1, s
See also /etc/xen/examples/xmexample.hvm.
-d DISK, --disk DISK
Defines an additional virtual disk. Repeat for multiple disks.
DISK is of the form PDEV,VDEV[,TYPE[,MODE[,MB[,OPTIONS...]]]].
PDEV describes the physical storage. In its simplest form, PDEV
can be a path to a file or block device. More complex forms
require prefixing a protocol. Valid Xen protocols are: file,
iscsi, nbd, npiv, phy, tap:aio, tap:qcow, and tap:vmdk. Exam‐
ples: /dev/hdb, phy:/dev/hdb, tap:qcow:/disks/disk0.qcow,
iscsi:iqn.2006-09.de.suse@0ac47ee2-216e-452a-a341-a12624cd0225.
Valid KVM protocols are: file, nbd, phy, qcow2, qed, raw, vpc,
and vmdk. Other protocols are available for experimentation.
VDEV is the name of the virtual device. VDEV may be named using
Xen fully-virtualized or KVM names (hda, hdb, hdc, ...) or Linux
para-virtualized names (xvda, xvdb, xvdc, ...) or for KVM virtio
names (vda, vdb, vdc, ...) or a number (0, 1, 2, ...).
TYPE may be disk (default) or cdrom.
MODE is r for read-only or w for writable. If the mode is not
specified, a reasonable default is chosen.
MB is a number specifying how large to create the disk (only
meaningful if PDEV does not already exist). Currently, only
file, tap:aio, and tap:qcow can be created from scratch.
OPTIONS are a few protocol-specific options. For example, file
might be passed the sparse=0 option. Valid options are: For Xen
and KVM: sparse=[1|0] For KVM only: cachemode=[default|direct‐
sync|none|unsafe|writeback|writethrough]
--graphics
Sets the type of the virtualized graphics hardware. Valid val‐
ues are: cirrus (Cirrus Logic GD5446 PCI VGA; only for fully
virtualized), none (No graphics support; use serial console or
network for access), para (Paravirtualized framebuffer; requires
driver in OS), or vesa (Standard VGA with VESA extensions; only
for fully virtualized).
--graphics-viewer
Defines how the graphics (if any) are viewed. May be sdl or
vnc. Defaults to vnc.
--keymap KEYMAP
Specify the keyboard translation map file. See /usr/share/qemu-
kvm/keymaps or /usr/share/xen/qemu/keymaps.
-m N, --memory N
Initial megabytes of RAM to allocate to the VM.
-M N, --max-memory N
Maximum megabytes of RAM that can every be allocated to the VM.
This value is most useful when it is set at or below the maximum
amount of memory that the OS can handle.
-n NAME, --name NAME
Name of the VM. This must be unique among all VMs on the physi‐
cal machine. If not specified, a unique name will be chosen
based on the OS type.
--nic NIC
Defines an additional virtual network adapter. NIC is composed
of a comma-separated list of key/value pairs. Valid keys and
values are: mac=AA.BB.CC.DD.EE.FF; bridge=BRIDGE; model=MODEL.
The MAC will be randomly generated if not specified. MODEL is
only applicable for full virtualization, and currently can be
one of:
For KVM: e1000 (Intel e1000), eepro100 (Intel eepro100), i82551
(Intel i82551), i82557b (Intel i82557b), i82559er (Intel
i82559er), pcnet (AMD PCnet 32), ne2k_pci (NE2000 on PCI bus),
rtl8139 (Realtek 8139), or virtio (For guests with support for
QEMU virtualized NIC card).
For Xen: e100 (Intel e100), e1000 (Intel e1000), pcnet (AMD
PCnet 32), ne2k_isa (NE2000 on ISA bus), ne2k_pci (NE2000 on PCI
bus), rtl8139 (Realtek 8139) or para (For guests with para-vir‐
tualized NIC driver).
To define a NIC with all defaults, pass an empty string for NIC.
--passthrough HOSTDEVICE
Allows direct access from the VM to a host device at VM install
time. The device specified must not be needed or used by the
host or another VM. Upon reboot of the host the device will not
be available to the VM unless the managed flag is set allowing
libvirt to acquire the device from the host when the VM is
started. See also documentation on hiding pci devices from the
host at boot time. The syntax for specifiying a HOSTDEVICE is of
the form pci=[DOMAIN:BUS:SLOT.FUNC[:MANAGED]] or
usb=[BUS:DEVICE:VENDOR_ID:PRODUCT_ID[:MANAGED]]. MANAGED is
optional and is set to have libvirt manage the device.
-u UUID, --uuid UUID
UUID for the VM. If none is given, a random UUID will be gener‐
ated.
-v, --para-virt
This VM should be paravirtualized. The OS must support paravir‐
tualization. Not applicable to KVM.
-V, --full-virt
This VM should be fully virtualized. The hardware must support
full virtualization.
--vnc-password PASSWORD
Password used to protect VNC access. Defaults to no password.
Be aware that the password may be visible in the process list.
For better security, pass the password in the --vm-settings
file.
--vnc-port N
Port to use for VNC server. If this is not specified, a VNC
port will be selected dynamically.
--vm-settings FILE
An XML file describing the VM's settings. Subsequent command-
line arguments will override settings from the XML, which allows
the XML to be treated as a template.
Options that affect the OS:
-o TYPE, --os-type TYPE
Type of guest OS. This defines many defaults, and helps decide
how to bootstrap paravirtualized OSs.
--os-settings FILE
A file or directory to be given to the OS at install time, via a
temporary virtual disk, used to automate the installation of the
OS. The format of this file (or layout of the directory)
depends on the OS. Not all OSs support automated installations.
Some OS-specific notes:
SUSE Installations of SUSE operating systems are primarily
automated via AutoYaST. If a file is specified, it is
assumed to be an AutoYaST XML file. If you wish to pass
both an AutoYaST file and a linuxrc info file, specify a
directory that contains the files "autoinst.xml" and
"info".
NetWare
NetWare installations are primarily automated via NetWare
Response Files. If a file is specified, it is assumed to
be a response file. Sometimes it is useful to automati‐
cally install license(s) also; in that case, specify a
directory that contains both the response file and the
license(s). The response file must be named with a
".rsp" extension. The licenses must be named with ".nlf"
extensions.
-p, --pxe-boot
Specify PXE booting for the VM installation. An optional PXE IP
server address may be specified.
-x TEXT, --extra-args TEXT
Additional arguments to pass to the paravirtualized OS. Note
that the tool will automatically generate the necessary OS-spe‐
cific arguments to bootstrap the installation.
-s URL, --source URL
Installation source of the operating system (eg, nfs:host:/path,
http://host/path, ftp://host/path). To install from an existing
virtual disk, use the syntax dev:/VDEV such as dev:/xvda. The
types of installation sources supported varies based on the OS
type.
Other options:
--background
Run in the background. Do not interactively prompt for set‐
tings; use defaults if necessary. Implies --no-autoconsole.
Backgrounded VM creation jobs can be managed with the vm-
install-jobs command.
--config-dir DIRECTORY
Specify the location to write the VM configuration files.
--debug
Print debugging information.
-e, --existing-os
Generate a configuration file based on an existing disk or disk
image with an installed operating system.
-O, --os-types
List valid OS types for -o, then quit.
--no-autoconsole
Don't automatically try to connect to the VM console. This tool
will pause (waiting for the installation to finish) until the VM
is caused to shutdown by some other means.
--no-install
Generate a configuration file but do not perform the install.
--no-restart
Don't automatically restart the VM after the first portion of
the installation finishes.
--preserve-on-error
Should an error occur, do not delete temporary, configuration
and image files.
--upgrade
Upgrade an existing paravirtualized VM.
EXAMPLES
As a trivial way to get started, run vm-install with no arguments:
# vm-install
By default, vm-install will interactively ask questions about the vir‐
tual machine and operating system you wish to install. Once enough
information is gathered, the VM is started. After the first stage of
the installation is completed, the final configuration file for the VM
is written to disk, and the VM is then re-started.
The tool can pick reasonable defaults based on the type of OS. This
makes it quick to automatically create a generic VM:
# vm-install--os-type sles10 --vcpus 2 \
--source ftp://10.0.0.1/install/sles10/i386/
The tool also saves the settings that started an installation to an XML
file. Therefore, after interacting with the tool to start a SLES 10
installation (and after copying the resulting autoinst.xml file from
the VM back to the local filesystem), an identical SLES 10 VM can be
created with a command such as this:
# vm-install--background --os-type sles10 \
--vm-settings /etc/xen/vm/sles10.xml \
--os-settings ~/autoinst.xml
Suppose instead you want to make the second VM slightly different.
Simply specify the changes you want, but be sure they are listed after
the VM settings file:
# vm-install--background --os-type sles10 \
--vm-settings /etc/xen/vm/sles10.xml \
--os-settings ~/autoinst.xml --name sles10-big --memory 1024
Finally, suppose you want to script the installation of a SLES 10 VM
onto your SAN:
# vm-install--background --os-type sles10 \
--disk iscsi:iqn.2006-09.de.suse@0ac47ee2-216e-452a-
a341-a12624cd0225,0 \
--os-settings ~/autoinst.xml
DIAGNOSTICS
A zero exit code indicates success; non-zero indicates failure. Fail‐
ure exit codes are grouped based on the underlying cause of the fail‐
ure.
General
0 Success
1 Other runtime error
Xen Errors
10 An error occurred in Xen.
11 The hypervisor is not running.
12 An incompatible version of the hypervisor is running.
13 Unable to connect to the Xen daemon.
14 Must be the 'root' user to manage Xen.
VM Errors
20 Failed to start the VM.
21 The VM has crashed.
22 A VM by that name is already running.
23 A VM configuration already exists with that name.
24 A valid boot sector was not found. The installation may have
failed.
25 No kernel was found. The installation may have failed.
26 You must shutdown the VM before upgrading
Installation Source Errors
30 The installation source is using an unsupported protocol.
31 An error occurred while reading from the installation source.
32 The installation source was not found.
33 The installation source is unusable.
34 No installation source was defined.
35 A CD-ROM or DVD must be specified from which to boot.
36 An error occurred while reading the configuration file
Resources: Architecture
40 The operating system is incompatible with the processor archi‐
tecture of this machine.
41 The processor(s) in this machine do not support full virtualiza‐
tion.
Resources: Memory
50 Not enough memory.
Resources: Disk
60 The disk does not exist.
61 The disk is read-only.
62 Permission was denied while attempting to access the disk.
63 Two of the virtual disks have conflicting virtual names or phys‐
ical devices.
64 Not enough space on device for disk image
65 Create disk image failed
Job Errors
70 The job was canceled.
71 The job was not found.
72 The job is in the wrong state to perform that action.
Parameter Errors
80 A parameter is invalid or missing.
81 The operating system does not support paravirtualization.
82 The operating system does not support automated installations.
83 The operating system does not support full virtualization
TO DO
Need ability to reserve memory, so that multiple simultaneous installa‐
tion jobs do not race and over-commit.
SEE ALSOvm-install-jobs(8)
To report problems with this software or its documentation, visit
http://bugzilla.novell.com
2007-02-01 vm-install(8)
