Chapter 25. Configuration files

Red Hat Virtualization configuration files contain the following standard variables. Configuration items within these files must be enclosed in single quotes('). These configuration files reside in the /etc/xen directory.

Spawn a vncviewer listening for a vnc server in the domain. The address of the vncviewer is passed to the domain on the kernel command line using VNC_SERVER=<host>:<port>. The port used by vnc is 5500 + DISPLAY. A display value with a free port is chosen if possible. Only valid when vnc=1.

vncconsole=no | yes

Spawn a vncviewer process for the domain's graphical console. Only valid when vnc=1.

name=NAME

Domain name. Must be unique.

bootloader=FILE

Path to bootloader.

bootargs=NAME

Arguments to pass to boot loader

bootentry=NAME

DEPRECATED. Entry to boot via boot loader. Use bootargs.

kernel=FILE

Path to kernel image.

ramdisk=FILE

Path to ramdisk.

features=FEATURES

Features to enable in guest kernel

builder=FUNCTION

Function to use to build the domain.

memory=MEMORY

Domain memory in MB.

maxmem=MEMORY

Maximum domain memory in MB.

shadow_memory=MEMORY

Domain shadow memory in MB.

cpu=CPU

CPU to run the VCPU0 on.

cpus=CPUS

CPUS to run the domain on.

pae=PAE

Disable or enable PAE of HVM domain.

acpi=ACPI

Disable or enable ACPI of HVM domain.

apic=APIC

Disable or enable APIC of HVM domain.

vcpus=VCPUS

# of Virtual CPUS in domain.

cpu_weight=WEIGHT

Set the new domain's cpu weight. WEIGHT is a float that controls the domain's share of the cpu.

Behavior when a domain exits with reason 'poweroff'. - destroy: the domain is cleaned up as normal; - restart: a new domain is started in place of the old one; - preserve: no clean-up is done until the domain is manually destroyed (using xm destroy, for example); - rename-restart: the old domain is not cleaned up, but is renamed and a new domain started in its place.

on_reboot=destroy | restart | preserve | destroy

Behavior when a domain exits with reason 'reboot'. - destroy: the domain is cleaned up as normal; - restart: a new domain is started in place of the old one; - preserve: no clean-up is done until the domain is manually destroyed (using xm destroy, for example); - rename-restart: the old domain is not cleaned up, but is renamed and a new domain started in its place.

on_crash=destroy | restart | preserve | destroy

Behavior when a domain exits with reason 'crash'. - destroy: the domain is cleaned up as normal; - restart: a new domain is started in place of the old one; - preserve: no clean-up is done until the domain is manually destroyed (using xm destroy, for example); - rename-restart: the old domain is not cleaned up, but is renamed and a new domain started in its place.

blkif=no | yes

Make the domain a block device backend.

netif=no | yes

Make the domain a network interface backend.

tpmif=no | yes

Make the domain a TPM interface backend.

disk=phy:DEV,VDEV,MODE[,DOM]

Add a disk device to a domain. The physical device is DEV, which is exported to the domain as VDEV. The disk is read-only if MODE is r, read-write if MODE is w. If DOM is specified it defines the backend driver domain to use for the disk. The option may be repeated to add more than one disk.

pci=BUS:DEV.FUNC

Add a PCI device to a domain, using given params (in hex). For example pci=c0:02.1a. The option may be repeated to add more than one pci device.

ioports=FROM[-TO]

Add a legacy I/O range to a domain, using given params (in hex). For example ioports=02f8-02ff. The option may be repeated to add more than one i/o range.

irq=IRQ

Add an IRQ (interrupt line) to a domain. For example irq=7. This option may be repeated to add more than one IRQ.

usbport=PATH

Add a physical USB port to a domain, as specified by the path to that port. This option may be repeated to add more than one port.

vfb=type={vnc,sdl}, vncunused=1, vncdisplay=N,

vnclisten=ADDR, display=DISPLAY,

xauthority=XAUTHORITY, vncpasswd=PASSWORD,

keymap=KEYMAP

Make the domain a framebuffer backend. The backend type should be either sdl or vnc. For type=vnc, connect an external vncviewer. The server will listen on ADDR (default 127.0.0.1) on port N+5900. N defaults to the domain id. If vncunused=1, the server will try to find an arbitrary unused port above 5900. For type=sdl, a viewer will be started automatically using the given DISPLAY and XAUTHORITY, which default to the current user's ones.

vif=type=TYPE, mac=MAC, bridge=BRIDGE, ip=IPADDR,

script=SCRIPT, backend=DOM, vifname=NAME

Add a network interface with the given MAC address and bridge. The vif is configured by calling the given configuration script. If type is not specified, default is netfront not ioemu device. If mac is not specified a random MAC address is used. If not specified then the network backend chooses it's own MAC address. If bridge is not specified the first bridge found is used. If script is not specified the default script is used. If backend is not specified the default backend driver domain is used. If vifname is not specified the backend virtual interface will have name vifD.N where D is the domain id and N is the interface id. This option may be repeated to add more than one vif. Specifying vifs will increase the number of interfaces as needed.

vtpm=instance=INSTANCE,backend=DOM

Add a TPM interface. On the backend side use the given instance as virtual TPM instance. The given number is merely the preferred instance number. The hotplug script will determine which instance number will actually be assigned to the domain. The association between virtual machine and the TPM instance number can be found in /etc/xen/vtpm.db. Use the backend in the given domain.

access_control=policy=POLICY,label=LABEL

Add a security label and the security policy reference that defines it. The local ssid reference is calculated when starting/resuming the domain. At this time, the policy is checked against the active policy as well. This way, migrating through save/restore is covered and local labels are automatically created correctly on the system where a domain is started / resumed.

nics=NUM

DEPRECATED. Use empty vif entries instead. Set the number of network interfaces. Use the vif option to define interface parameters, otherwise defaults are used. Specifying vifs will increase the number of interfaces as needed.

root=DEVICE

Set the root= parameter on the kernel command line. Use a device, e.g. /dev/sda1, or /dev/nfs for NFS root.

extra=ARGS

Set extra arguments to append to the kernel command line.

ip=IPADDR

Set the kernel IP interface address.

gateway=IPADDR

Set the kernel IP gateway.

netmask=MASK

Set the kernel IP netmask.

hostname=NAME

Set the kernel IP hostname.

interface=INTF

Set the kernel IP interface name.

dhcp=off|dhcp

Set the kernel dhcp option.

nfs_server=IPADDR

Set the address of the NFS server for NFS root.

nfs_root=PATH

Set the path of the root NFS directory.

device_model=FILE

Path to device model program.

fda=FILE

Path to fda

fdb=FILE

Path to fdb

serial=FILE

Path to serial or pty or vc

localtime=no | yes

Is RTC set to localtime?

keymap=FILE

Set keyboard layout used

usb=no | yes

Emulate USB devices?

usbdevice=NAME

Name of USB device to add?

stdvga=no | yes

Use std vga or cirrhus logic graphics

isa=no | yes

Simulate an ISA only system?

boot=a|b|c|d

Default boot device

nographic=no | yes

Should device models use graphics?

soundhw=audiodev

Should device models enable audio device?

vnc

Should the device model use VNC?

vncdisplay

VNC display to use

vnclisten

Address for VNC server to listen on.

vncunused

Try to find an unused port for the VNC server. Only valid when vnc=1.

sdl

Should the device model use SDL?

display=DISPLAY

X11 display to use

xauthority=XAUTHORITY

X11 Authority to use

uuid

xenstore UUID (universally unique identifier) to use. One will be randomly generated if this option is not set, just like MAC addresses for virtual network interfaces. This must be a unique value across the entire cluster.

Table 25.2. Red Hat Virtualization configuration files reference

Table 25.4, “Configuration parameter default values” lists all configuration parameters available, the Python parser function used to set the value and each parameter's default value. The setter function gives an idea of what the parser does with the values you specify. It reads them as Python values, then feeds them to a setter function to store them. If the value is not valid Python, you get an obscure error message. If the setter rejects your value, you should get a reasonable error message, except it appears to get lost somehow, along with your bogus setting. If the setter accepts, but the value makes no sense, the program proceeds, and you can expect it to fall flat on its face somewhere down the road.

Parser function

Valid arguments

set_bool

Accepted values:

yes

y

no

yes

set_float

Accepts a floating point number with Python's float(). For example:

3.14

10.

.001

1e100

3.14e-10

set_int

Accepts an integer with Python's int().

set_value

accepts any Python value.

append_value

accepts any Python value, and appends it to the previous value which is stored in an array.

Table 25.3. Python functions used to set parameter values

Parameter

Parser function

Default value

name

setter

default value

vncpasswd

set_value

None

vncviewer

set_bool

None

vncconsole

set_bool

None

name

set_value

None

bootloader

set_value

None

bootargs

set_value

None

bootentry

set_value

None

kernel

set_value

None

ramdisk

set_value

''

features

set_value

''

builder

set_value

'linux'

memory

set_int

128

maxmem

set_int

None

shadow_memory

set_int

0

cpu

set_int

None

cpus

set_value

None

pae

set_int

0

acpi

set_int

0

apic

set_int

0

vcpus

set_int

1

cpu_weight

set_float

None

restart

set_value

None

on_poweroff

set_value

None

on_reboot

set_value

None

on_crash

set_value

None

blkif

set_bool

0

netif

set_bool

0

tpmif

append_value

0

disk

append_value

[]

pci

append_value

[]

ioports

append_value

[]

irq

append_value

[]

usbport

append_value

[]

vfb

append_value

[]

vif

append_value

[]

vtpm

append_value

[]

access_control

append_value

[]

nics

set_int

-1

root

set_value

''

extra

set_value

''

ip

set_value

''

gateway

set_value

''

netmask

set_value

''

hostname

set_value

''

interface

set_value

"eth0"

dhcp

set_value

'off'

nfs_server

set_value

None

nfs_root

set_value

None

device_model

set_value

''

fda

set_value

''

fdb

set_value

''

serial

set_value

''

localtime

set_bool

0

keymap

set_value

''

usb

set_bool

0

usbdevice

set_value

''

stdvga

set_bool

0

isa

set_bool

0

boot

set_value

'c'

nographic

set_bool

0

soundhw

set_value

''

vnc

set_value

None

vncdisplay

set_value

None

vnclisten

set_value

None

vncunused

set_bool

1

sdl

set_value

None

display

set_value

None

xauthority

set_value

None

uuid

set_value

None

Table 25.4. Configuration parameter default values

Note: This documentation is provided {and copyrighted} by Red Hat®, Inc. and is released via the Open Publication License. The copyright holder has added the further requirement that Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. The CentOS project redistributes these original works (in their unmodified form) as a reference for CentOS-5 because CentOS-5 is built from publicly available, open source SRPMS. The documentation is unmodified to be compliant with upstream distribution policy. Neither CentOS-5 nor the CentOS Project are in any way affiliated with or sponsored by Red Hat®, Inc.