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 Xen or KVM 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.

       -a ADVANCED, --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 '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.

       --cpuid CPUID
	      Present  the  fully  virtualized	VM  with  cpuid  information  for  processor  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
	      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.

       -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  virtual-
	      ized),  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/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 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 appli-
	      cable 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  con-
		     tains 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.

       -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.   Back-
	      grounded 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 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 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 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							     vm-install(8)