1. Manuals
  2. Tumbleweed
  3. vm-install
  4. vm-install(8)

Scroll to navigation

vm-install(8) System Manager's Manual vm-install(8)

NAME

vm-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]

DESCRIPTION

vm-install can define a KVM or Xen virtual machine, and cause an operating 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.

OPTIONS

vm-install accepts three types of options: Those that affect the definition 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:

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).
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 ´Hardware´ 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.

Number of virtual CPUs to allocate to the VM.
Present the fully virtualized VM with cpuid information for processor compatibility: CPUID is in the form of FUNCTION: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.

Defines the hosts cpuid consistency checks that must be satisfied for this fully virtualized VM to be allowed to run on the hosts processor type: CPUCHECK is in the form of FUNCTION: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.

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. Examples: /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|directsync|none|unsafe|writeback|writethrough]

Sets the type of the virtualized graphics hardware. Valid values 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).
Defines how the graphics (if any) are viewed. May be sdl or vnc. Defaults to vnc.
Specify the keyboard translation map file. See /usr/share/qemu-kvm/keymaps or /usr/share/xen/qemu/keymaps.
Initial megabytes of RAM to allocate to the VM.
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.
Name of the VM. This must be unique among all VMs on the physical machine. If not specified, a unique name will be chosen based on the OS type.
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-virtualized NIC driver).

To define a NIC with all defaults, pass an empty string for NIC.

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.
UUID for the VM. If none is given, a random UUID will be generated.
This VM should be paravirtualized. The OS must support paravirtualization. Not applicable to KVM.
This VM should be fully virtualized. The hardware must support full virtualization.
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.
Port to use for VNC server. If this is not specified, a VNC port will be selected dynamically.
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:

Type of guest OS. This defines many defaults, and helps decide how to bootstrap paravirtualized OSs.
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:
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 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 automatically 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.
Specify PXE booting for the VM installation. An optional PXE IP server address may be specified.
Additional arguments to pass to the paravirtualized OS. Note that the tool will automatically generate the necessary OS-specific arguments to bootstrap the installation.
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:

Run in the background. Do not interactively prompt for settings; use defaults if necessary. Implies --no-autoconsole. Backgrounded VM creation jobs can be managed with the vm-install-jobs command.
Specify the location to write the VM configuration files.
Print debugging information.
Generate a configuration file based on an existing disk or disk image with an installed operating system.
List valid OS types for -o, then quit.
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.
Generate a configuration file but do not perform the install.
Don't automatically restart the VM after the first portion of the installation finishes.
Should an error occur, do not delete temporary, configuration and image files.
Upgrade an existing paravirtualized VM.
Xen only option. By default vm-install uses libvirt to create a VM. This allows the VM to to be managed through the virt-manager application or the virsh command line tool. By specifying this flag, vm-install will use the xl command to create the VM. This option will create a VM that is unknown and unmanaged by libvirt. The default viewer for a graphical VM is virt-viewer. Because virt-viewer requires a libvirt connection, only vncviewer may be used to view the graphical console of a VM created with this option.

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 virtual 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. Failure exit codes are grouped based on the underlying cause of the failure.

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 architecture of this machine.
41
The processor(s) in this machine do not support full virtualization.

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 physical 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 installation jobs do not race and over-commit.

SEE ALSO

vm-install-jobs(8)

To report problems with this software or its documentation, visit http://bugzilla.novell.com

2007-02-01