Using virt-install to Install a Domain

Chapter 38

Using `virt-install` to Install a Domain

This chapter discusses various methods for using virt-install. The virt-install tool is used to install operating systems as virtual machines.

`virt-install` Overview

The virt-install program can be run as a command-line utility, with parameters specified through options, or interactively, in response to a series of prompts.

Supported Machines

x64 and x86 based systems are supported.

To run Windows hardware-assisted virtual machine (HVM) domains, an HVM-capable machine that is running Solaris xVM dom0 is required. A machine is HVM-capable if it is has either an AMD Opteron Revision F or later, or an Intel CPU with VT extensions.

Installation Types

The types of installations that can be performed include the following:

Interactive
Command line, with options supplied
Netinstall
ISO image
JumpStart

Required Information

You will need to supply the guest domain information listed below.

Note - For more information on memory, disk, and networking requirements, see Download, Installation, and Configuration Information in the OpenSolaris documentation.

name

Name for the domU. Each domU must have a unique name. This name serves as the label of the guest operating system.

image location

Location of the installation software. Currently, installation must be over a network (which includes an NFS share from the local host operating system).

For example:

--location nfs:my.nfs.server.com:/home/install/test/mydomain

Note - Installations using http or ftp, as shown in the examples below, are not currently supported:

http://my.http.server.com:/install/test/mydomain
ftp://my.ftp.server.com:/install/test/mydomain

vcpus

The number of CPUs for the domU. The default is 1. You can assign specific CPUs, but if undefined, the hypervisor will make the selection.

memory

Amount of RAM to be allocated to the guest, in megabytes. A running domain should use a minimum of 512 megabytes. However, to install the domU, 1 gigabyte (1024 megabyte) is required.

graphics

Graphical console. Default is graphics. nographics applies to paravirtual guests only. If you intend to enable graphics support, you must decide whether the graphical installer should be used.

disk

Path to the disk image of the guest. This path is exported as an entire disk to your guest. It is on the xVM control domain. You can specify a file, or you can specify a physical device, such as a ZFS pool or a raw disk device.

Note that the root disk of a Solaris domU must be specified with a target of 0, which means that the root device of any Solaris domU will always be /dev/dsk/c0t0d0.

Virtual network interface MAC address

This is the MAC address of the dom0's network interface that you want the domU to use to send and receive internet traffic. By default, the hypervisor tools will use the first available NIC when creating guest domains.

The default values for the action to be taken on a domU shutdown, reboot, or crash are set by virt-install. There currently is no way of changing these defaults,

Options

Usage examples are provided in subsequent sections of this chapter.

--accelerate

Use kernel acceleration capabilities.

--arch=arch

The CPU architecture to simulate. Acceptable values are x86 and sparc.

--autocf=AUTOCF

JumpStart path (nfs:host:/path). The path must point to the directory containing JumpStart information,

-b bridge, --bridge=bridge

Bridge to which to connect the network interface. If you do not specify a bridge, the system attempts to determine the default.

-c cdrom, --cdrom=cdrom

File to use as a virtual CD-ROM device for fully virtualized guests. This option works with HVM domains and is ignored with paravirtualized domains. To install from cdrom, pass the ISO path to --location.

--check-cpu

Check that VCPUs do not exceed physical CPUs and warn if they do.

--connect=URI

Connect to hypervisor at URI.

-d, --debug

Display debugging information.

-f disk_image, --file=disk_image

File to use as disk image.

-h,--help

Display list of virt-install options.

-k keymap, --keymap=keymap

Set up keymap for a graphical console.

-l location, --location=location

Installation source for a paravirtualized domU, such as nfs:host:/path.

-m mac_addr, --mac=mac_addr

Fixed MAC address for the domU. If the keywords none or random are specified, a random address will be used.

-n name, --name=name

Name of the domU.

--noacpi

Disables Advanced Configuration and Power Interface (ACPI) for a fully virtualized domU. Overrides stored configuration setting specified by the --os-type and --os-variant options.

--noapic

Disables Programmable Interrupt Controller (APIC) for a fully virtualized domU. Overrides stored configuration setting specified by the --os-type and --os-variant options.

--noautoconsole

Do not automatically try to connect to the guest console.

--nographics

Do not set up a graphical console for the guest.

By default, consoles for HVM guests are graphics consoles. When using virt-install to create a paravirtualized guest, --nographics must be used to override the default mode. HVM installs may specify either VNC (--vnc) or Simple DirectMedia Layer (SDL) (--sdl) for graphics support.

--nonsparse

Do not use sparse files for disks..Note that the use of this option causes domUt creation to be significantly slower.

--ostype=os_type

The OS type for fully virtualized guests. Acceptable values are solaris, unix, linux, and windows.

--variant=os_variant

The OS variant for fully virtualized guests. Acceptable values are fedora6, rhel5, solaris10, win2k, and vista.

--vcpus=N

Sets the number of vcpus for the guest domain.

-p, --paravirt

Indicates that guest is paravirtualized.

-r mem_amount, --ram=mem_amount

Memory to allocate for domU instance, in megabytes.

-s disksize, --file-size=disksize

Size of the disk image (if it does not exist), in gigabytes.

--sdl

Use Simple DirectMedia Layer (SDL) for graphics support. This option works with some guest domains, including HVM, but cannot be used with Solaris. For more information on SDL, see Simple DirectMedia Layer.

-u UUID, --uuid=UUID

Specifies the UUID as a 32–digit hexadecimal number, for the domU. If no UUID is specified, the system generates a random UUID.

-v , --hvm

Specifies that the guest is a hardware assisted virtual machine (HVM).

--vcpus=vcpus

Number of virtual CPUs (VCPUs) to configure for the domU.

-vnc

Use Virtual Network Computing (VNC) for graphics support. This option works with HVM domains but it does not work with paravirtualized domains.

--vncport

Port to use for VNC.

-w network, --network=network

Connect the guest to a virtual network, forwarding to the physical network with Network Address Translation (NAT).

-x extra_args, --extra-args=extra_args

When installing paravirtualized guests, specifies additional arguments to pass to the installer.

After entering required information, installation starts. If you enabled graphics, a VNC window opens and presents the graphical installer. If graphics are not enabled, the text installer displays.

For more information, see the virt-install(1M) man page.

Install Using `virt-install` With Options

This example uses virt-install with options to install a Solaris domU from the command line using an ISO image. See virt-install Examples for examples of other types of guest domains. If you invoke virt-install with command line options but do not supply all required information, the tool prompts you for the needed information.

machine:root> virt-install --nographics  -n domu-x16 --parvirt \
 -f /xvm/domu-x16.img -r 1011 --mac=aa:ff:bb:aa:28:16 -s 18 \
 -l /net/inst-server/export/xVM/x_iso/63-0419-nd.iso
Starting install...
Creating domain...
SunOS Release 5.11 Version 64-bit
Copyright 1983-2007 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
Configuring /dev
Solaris Interactive Text (Console session)
Using install cd in /dev/dsk/c0d1p0
Using RPC Bootparams for network configuration information.
Attempting to configure interface xnf0...
Skipped interface xnf0
Setting up Java. Please wait...
Beginning system identification...
Searching for configuration file(s)...
Search complete.
Discovering additional network configuration...

At this point, you do the sysidcfg setup.

How to Complete the Solaris DomU `sysidcfg` Configuration

After the domain is created, the sysidcfg is initiated and you are prompted to answer a series of questions. Your screen will look similar to this:

SunOS Release 5.11 Version 64-bit
Copyright 1983-2007 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
Hostname: my-zone
Loading smf(5) service descriptions: 114/114
Select a Language

    1. English
   2. French
   3. German
   4. Italian
   5. Japanese
   6. Korean
   7. Simplified Chinese
   8. Spanish
   9. Swedish
  10. Traditional Chinese

Please make a choice (1 - 10), or press h or ? for help:

What type of terminal are you using?
      1) ANSI Standard CRT
      2) DEC VT52
      3) DEC VT100
      4) Heathkit 19
      5) Lear Siegler ADM31
      6) PC Console
      7) Sun Command Tool
      8) Sun Workstation
      9) Televideo 910
      10) Televideo 925
      11) Wyse Model 50
      12) X Terminal Emulator (xterms)
      13) CDE Terminal Emulator (dtterm)
      14) Other
Type the number of your choice and press Return:
.
.
.

For more information on the sysidcfg file, see the sysidcfg(4) man page.

`virt-install` Examples

Example 38-1 Solaris PV Guest

virt-install -n solarisPV --paravirt -r 1024 \ 
  --nographics -f /export/solarisPV/root.img -s 16 \ 
  -l /ws/xvm-gate/public/isos/72-0910/solarisdvd.iso

Example 38-2 Solaris HVM Guest

virt-install -n solarisHVM --hvm -r 1024 --vnc \ 
  -f /export/solarisHVM/root.img -s 16 \ 
  -c /ws/xvm-gate/public/isos/72-0910/solarisdvd.iso

Example 38-3 Windows HVM Guest

# virt-install -n winxp --hvm -r 1024 --vnc \ 
  -f /export/winxp/root.img -s 16 -c /windows/media.iso

Example 38-4 Install Solaris Using Network Install and JumpStart onto a ZFS Volume

zfs create -V 8G pool/solaris1-disk
virt-install --name solaris1 --ram 1024 --nographics \
--file /dev/zvol/dsk/pool/solaris1-disk \
--location nfs:install.domain.com:/export/solaris/nv75 \
--autocf nfs:install.domain.com:/export/jumpstart/solaris1

VNC Password and Remote Display Requirements

Set the VNC password property in the SMF configuration in xend before starting an HVM domain.

Example 38-5 How to Set the VNC Password Property

# svccfg -s xvm/xend setprop \ 
       config/vncpasswd = astring: \?somepwd\?
# svcadm refresh xvm/xend; svcadm restart xvm/xend

If remotely displaying the VNC session remotely, you must also set the vnc-listen property.

For more information on setting up VNC, see

Example 38-6 How to Set the vnc-listen Property

# svccfg -s xvm/xend setprop \ 
       config/vnc-listen = astring: \?0.0.0.0\? 
# svcadm refresh xvm/xend; svcadm restart xvm/xend

Note - For more information, see How to Set Up VNC in the OpenSolaris documentation.

Install a DomU Interactively by Using `virt-install`

Type virt-install at the command line to install a guest domain (domU).

# virt-install

Respond to the tool's prompts:

Provide a name for your new virtualized system, for example, Sdomain_1.
Provide the path to installation media containing the files needed to install a domU on the virtual system (URL, path).
Provide the root file system path, specifying the disk partition or file the domU should use. You are specifying how you want to assign space on the physical system for the domU. Later, you can add additional storage sources, including network-mounted, to an existing system.
Provide the network setup.
- Virtual
- Shared physical device
Provide the memory and CPU resources allocations. You can revise these values later.
Provide mem-max memory setup.
A domU can balloon, or expand, its actual memory allocation up to the maximum threshold allocated.
Provide the vcpus setting.

About Network Installations

After you configure the installation server, you can run virt-install from your dom0. Use the -d option to add_install_client to specify that the client use DHCP. If the -d option is not specified, the client uses bootparams. For xVM paravirtualized guests, both approaches work. However, xVM server installations are required to use DHCP as part of the PXE based network installation. Thus, DHCP provides a common method that can be used to install both servers and guests.

Network Installation

To do a network installation, use the -l option and give a path to the network installation image. When giving a machine name or IP address, the domU must be able to get to that install machine directly, not go through a router to another net. For example:

-l nfs:install:/export/xvm/xvmgate-70i72-nd

You can also use an IP address instead of a machine name. For example:

-l nfs:172.20.25.12:/export/xvm/xvmgate-70i72-nd

Example 38-7 Network Installation

virt-install -n gath-01 -r 1000 --nographics -f /dev/dsk/c1t0d0s3 \
-m "aa:04:03:35:a8:06" -p \
-l nfs:install48:/export/xvm/xvmgate-70i72-nd

ISO Image Installation

To use the ISO image, use the -l option with a full path to the ISO image. If a full path is given instead of the nfs:mach_name:path format of a network installation, then virt-install assumes that this is an ISO image:

-l /net/install/export/xvm/solarisdvd.iso

Example 38-8 ISO Image

virt-install -n gath-01 -r 1000 --nographics -f /dev/dsk/c1t0d0s3 \
-m aa:04:03:35:a8:06 -p \
-l /net/install48/export/xvm/solarisdvd.iso

Note - You can quote arguments to options. While arguments, such as the path to an ISO image, are generally not quoted on the command line, quotes might be used in scripts.

-l "/net/install48/export/xvm/solarisdvd.iso"

JumpStart Installation

JumpStart configuration files are manually created and managed. You can initiate a custom JumpStart through network installation after setting up the server. When you create a profile server, you must ensure that systems can access the JumpStart directory on the profile server during a custom JumpStart installation. Each time that you add a system for network installation, use the add_install_client command to specify the profile server. You use the add_install_client command to create the /etc/bootparams entry for the domU.

To do a JumpStart with virt-install, use the --autocf option. For example:

--autocf nfs:install:/export/jumpstart/jump-user/x86

You cannot use a full path such as:

--autocf /net/install/export/jumpstart/jump-user/x86

Example 38-9 JumpStart

virt-install -n gath-01 -r 1000 --nographics -f /dev/dsk/c1t0d0s3 \
-m aa:04:03:35:a8:06 -p \
-l /net/install48/export/xvm/xvmgate-70i72/solarisdvd.iso
--autocf nfs:install:/export/jumpstart/jump-user/x86

OpenSolaris

virt-install Overview

Supported Machines

Installation Types

Required Information

Options

Install Using virt-install With Options

How to Complete the Solaris DomU sysidcfg Configuration

virt-install Examples

VNC Password and Remote Display Requirements

Install a DomU Interactively by Using virt-install

About Network Installations

Network Installation

ISO Image Installation

JumpStart Installation