Chapter 25. Configuration files

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.

Item Description

pae

Specifies the physical address extension configuration data.

apic

Specifies the advanced programmable interrupt controller configuration data.

memory

Specifies the memory size in megabytes.

vcpus

Specifies the numbers of virtual CPUs.

console

Specifies the port numbers to export the domain consoles to.

nic

Specifies the number of virtual network interfaces.

vif

Lists the randomly-assigned MAC addresses and bridges assigned to use for the domain's network addresses.

disk

Lists the block devices to export to the domain and exports physical devices to domain with read only access.

dhcp

Enables networking using DHCP.

netmask

Specifies the configured IP netmasks.

gateway

Specifies the configured IP gateways.

acpi

Specifies the advanced configuration power interface configuration data.

Table 25.1. Red Hat Virtualization configuration files

The table below, Table 25.2, “Red Hat Virtualization configuration files reference”, is formatted output from xm create --help_config.

Parameter

Description

vncpasswd=NAME Password for VNC console on HVM domain.
vncviewer=no | yes 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.
restart=onreboot | always | never Deprecated. Use on_poweroff, on_reboot, and on_crash instead. Whether the domain should be restarted on exit. - onreboot: restart on exit with shutdown code reboot - always: always restart on exit, ignore exit code - never: never restart on exit, ignore exit code
on_poweroff=destroy | restart | preserve | destroy 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.