Linux Certif

Toute la documentation sur la certification Linux LPI

vm-install

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 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:

-c N, --vcpus N

Number of virtual CPUs to allocate to the VM.

-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 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.

VDEV is the name of the virtual device. VDEV may be named using Linux fully-virtualized names (hda, hdb, hdc, ...) or Linux para-virtualized names (xvda, xvdb, xvdc, ...) 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 any number of protocol-specific options. For example, file might be passed the sparse=0 option.

--graphics

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

--graphics-viewer

Defines how the graphics (if any) are viewed. May be sdl or vnc. Defaults to vnc.

-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 physical 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: pcnet (AMD PCnet 32), ne2k_isa (NE2000 on ISA bus), ne2k_pci (NE2000 on PCI bus), or rtl8139 (Realtek 8139). To define a NIC with all defaults, pass an empty string for NIC.

-u UUID, --uuid UUID

UUID for the VM. If none is given, a random UUID will be generated.

-v, --para-virt

This VM should be paravirtualized. The OS must support paravirtualization.

-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 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.

-x TEXT, --extra-args TEXT Additional arguments to pass to the paravirtualized OS. Note that the tool will automatically generate the necessary OS-specific 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 settings; use defaults if necessary. Implies --no-autoconsole. Backgrounded VM creation jobs can be managed with the vm-install-jobs command.

--debug

Print debugging information.

-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-restart

Don't automatically restart the VM after the first portion of the installation finishes.

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.

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.

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.

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.

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