README.md

Xen VM management (xen_vman)

This role manages Xen VMs with systemd services.

For each configured VM a Xen VM configuration is generated. You can start and stop the VMs with systemd. Currently, iSCSI and NFS are completely supported as filesystem backends. For all other backends you manually need to install the system afterwards.

For each installed kernel, a dracut initrd will automatically created at /etc/xen/initrd.img-$VERSION (similar to /boot initrds for dom0). When starting a VM. /etc/xen/initrd.img will automatically be created as a symlink, pointing to the initrd of the currently running kernel.

Requirements

• A Xen host machine running a Debian host system (you can use xen-setup to perform this task)
• Filesystem utilities for filesystems used by the guests
• python-netaddr on the executing machine

systemd services

vm@<organisation>-<host>.service

Start and stop the given VM. For example systemd start vm@stuvus-web01 will start the web01 server from the organisation stuvus.

vm_iscsi@<organisation>-<host>.service

Does a login or a logout for the iSCSI root disk for the given VM, this is only done when iSCSI is selected as root backend, otherwise systemd will ignore any request silently.

vm_mount@<organisation>-<host>.service

Mount or umount the root filesystem from the given VM. For example systemd start vm_mount@stuvus-web02 mounts the root filesystem of web01 @stuvus into /mnt/vms/stuvus-web01. The mount point is automated created and removed.

nfs vms

All NFS exports need to be accessible for the hypervisor as well as the respective VM. The exported path for the root filesystem must be of the following scheme: {{ xen_vman_nfsroot_base }}/<org name>/<vm name>-root .

Role Variables

Name	Type	Default/Required ¹	Description
xen_vman_xl_path	string	auto determined	Fully qualified path of the xl command
xen_vman_iscsiadm_path	string	auto determined	Fully qualified path of the iscsiadm command
xen_vman_vms	list of dicts	[]	A list of all VM specifications, see below
xen_vman_vm_config_path	string	/etc/xen/vms	Path to store the generated Xen VM configurations
xen_vman_dracut_modules	list of strings	[nfs,network,base,bash,systemd,terminfo,shutdown,kernel-modules,kernel-network-modules,console-setup,systemd-initrd,dracut-systemd]	Dracut modules to include in the Xen initrd
xen_vman_dracut_extra_flags	string		Extra flags to pass to dracut when building the Xen initrds
xen_vman_start_timeout	integer	15	systemd timeout in seconds to start a VM
xen_vman_stop_timeout	integer	300	systemd timeout in seconds to stop a VM, after timeout is reached, systemd kills the VM
xen_vman_iscsi_login_timeout	integer	40	Maximum time in seconds to wait for an iSCSI login request to complete
xen_vman_iscsi_logout_timeout	integer	40	Maximum time in seconds to wait for an iSCSI logout request to complete
xen_vman_mount_timeout	integer	20	Maximum time in seconds to wait for mount before systemd unit enters failed state
xen_vman_umount_timeout	integer	20	Maximum time in seconds to wait for umount before systemd unit enters failed state
xen_vman_public_keys	list of strings	[]	List of public keys to add to the newly generated user in the VM
xen_vman_nfsroot_base	string	required for NFS	Path to prepend to all NFS paths
xen_vman_iscsi_server	string	required for iSCSI	iSCSI server to connect to
xen_vman_iscsi_base_wwn	string	required for iSCSI	Base of the WWN name
xen_vman_debootstrap_packages	list of strings	[systemd,systemd-sysv,udev,openssh-server,sudo,python,iproute2,ifupdown]	Packages to install into a newly installed VM using debootstrap
xen_vman_default_memory	integer	1024	Memory to assign to a Xen domU in MiB ²
xen_vman_default_vcpus	integer	2	Number of virtual CPU cores to assign to a VM ²
xen_vman_default_cpu_str	string	all,^1	List of which CPUs the guest is allowed to use ²
xen_vman_default_storage_type	string	nfs	Default filesystem backend to use. Valid choices are nfs and iscsi
xen_vman_default_disks	list of strings	[]	Xen disk specification (see also xl-disk-configuration.txt)
xen_vman_default_manual_root_disk	boolean	False	Use only disk specified by xen_vman_default_disks or vm.disks
xen_vman_default_filesystem	string	ext4	Filesystem to use for VMs with iSCSI root disk
xen_vman_default_gateway	string	required for a default route on newly installed vms	Default gateway of the new VM
xen_vman_default_mtu	integer		Default MTU for the new VM
xen_vman_default_nameserver	list of strings	[8.8.8.8, 8.8.4.4]	Nameservers to initially set for the new VMs
xen_vman_default_boot_after_creation	boolean	True	Start the VM after installation
xen_vman_default_auto_boot	boolean	True	Start VM when hypervisor boots
xen_vman_default_builder	string	generic	Select the domU guest type, valid values are generic (para virtualization) and hvm (all hardware is emulated)
xen_vman_default_kernel	string	auto determined	Path to the kernel to use for generic VMs
xen_vman_default_initrd	string	/etc/xen/initrd.img	Path to the initrd to use for generic VMs
xen_vman_default_cmdline	string	not required	Command line to pass to the kernel, this option also disables auto generated kernel command lines
xen_vman_default_spice	boolean	False	Allow access to the display via the SPICE protocol ²
xen_vman_default_spicehost	string (IP-Address)	0.0.0.0	Specify the interface address to listen on if given, defaults to any interface ²
xen_vman_default_spiceport	integer	3100	Specify the port to listen on by the SPICE server if SPICE is enabled ²
xen_vman_default_mouse	boolean	True	Whether SPICE agent is used for client mouse mode ²
xen_vman_default_share_clipboard	boolean	True	Enables SPICE clipboard sharing ²
xen_vman_default_spicevdagent	boolean	True	Enables SPICE vdagent, this is automatically enabled when clipboard sharing is enabled ²
xen_vman_default_max_usb_redirections	integer (0-4)	4	Enable SPICE USB redirections ²
xen_vman_default_additonal_xen_options	xl.cfg key value dict	[]	Add additional Xen options
xen_vman_default_auto_install	boolean	True	Install specified OS automatically, when no xen configuration is found
xen_vman_additional_network_scripts	list of strings	[]	List of additional network scripts
xen_vman_default_network_script	string	vif-bridge	Default xen-script used to setup vm network interfaces, for valid values see ls /etc/xen/scripts/vif* on the hypervisor
xen_vman_default_network_bridge	string	required for some xen_vman_default_network_bridge settings	Default network bridge to use for vm network interfaces
xen_vman_lazy_default_network_bridge	string	not required	Default network bridge (lazily evaluated)
xen_vman_default_xen_str	string	not required	Default for xen_str
xen_vman_default_vifname_prefix	string	not required	Default for vifname

¹ Variable is not required unless no default is given or other specified ² For further reference see man xl.cfg

Additional network scripts

This role currently supports a custom network script called vif-p2p. It is like (the official) vif-route, except that it configures the vif interface using a P2P configuration from dom0 to the guest.

vif-p2p supports IPv6. To use this IPv6 feature, you must yourself configure your VMs to use the link-local address fe80::2/64 and gateway fe80::1 on eth0. Those link-local addresses are fixed and are the same for all VMs.

That is, vif-p2p automatically configures the interface on the host like

ip address add 10.0.0.1/32 peer 10.0.0.10 dev vif10.0
ip address add fe80::1/64 dev vif10.0
ip route add 2001:DB8::10/128 via fe80::2 dev vif10.0

if 10.0.0.1 is the main IP of the hypervisor, 10.0.0.10 is the ip of the first VM interface and 2001:DB8::10 is the ipv6 of the first VM interface. (For IPv4, the kernel will automatically add the necessary route.)

In order to install vif-p2p you have to add the string "vif-p2p" to xen_vman_additional_network_scripts.

Custom additional network scripts

In order to install your own network script (that is not supplied by this role), you can add arbitrary paths to xen_vman_additional_network_scripts. Relative paths are relative to your files folder. Only the file name is preserved: For example, adding "xen_vman/vif-custom" to xen_vman_additional_network_scripts will instruct this role to copy files/xen_vman/vif-custom (on localhost) to /etc/xen/scripts/vif-custom (on the remote host).

For doing so, it is recommended to use a subfolder like xen_vman, as in the previous example. Otherwise your file name might collide with a supplied network script in a future version of this role. In the case of such a collision, the script supplied by this role takes precedence.

Default network bridge

xen_vman_default_network_bridge is written to Xen's config file, while xen_vman_lazy_default_network_bridge is lazily evaluated in order to default the bridge of VM interfaces. Therefore you can access the VM variables from within xen_vman_lazy_default_network_bridge.

VM variables

These variables can be specified for each VM. VMs are defined as elements of the xen_vman_vms list.

Name	Type	Required	Description
org	string	Y	Organization which owns this VM
name	string	Y	Name of this VM
memory	integer	N	Amount of memory to assign to this VM. The number is treated as amount of megabytes
vcpus	integer	N	Amount of virtual CPU cores
cpu_str	string	N	List of which CPU cores the VM is allowed to use. See above for more information
interfaces	list of dicts	Y	Virtual network interfaces. See below
connection_ip	string	N	IP of this VM. Will be configured as static IP. First interface IP is used when omitted
storage_type	string	N	Storage backend of the root filesystem. See above for valid options
disks	list of strings	N	Additional Xen disk specifications. See above for more information
manual_root_disk	boolean	N	Use only disk specified by xen_vman_default_disks or vm.disk
filesystem	string	N	When using iSCSI, this filesystem is used for the root
os.type	string	Y	Type of the operating system
os.version	string	Y	Version of the chosen operating system
boot_after_creation	boolean	N	Whether to boot the VM after creation
auto_boot	boolean	N	Whether to boot the VM on hypervisor boot
builder	string	N	Select the builder for this VM (generic or hvm)
kernel	string	N	(For generic VMs only) Path to the kernel to boot
initrd	string	N	(For generic VMs only) Path to the initrd to pass to the kernel
cmdline	string	N	(For generic VMs only) Command line to pass to the kernel
spice	boolean	N	(For generic VMs only) Enable SPICE
spicehost	string	N	(For HVM VMs only) Address for the SPICE server to listen on
spiceport	integer	N	(For HVM VMs only) Port for the SPICE server to listen on
spicepasswd	string	N	(For HVM VMs only) Password required when connecting to the SPICE server
share_clipboard	boolean	N	(For HVM VMs only) Share clipboard via SPICE
spicevdagent	boolean	N	(For HVM VMs only) Enable the SPICE vdagent
max_usb_redirections	integer	N	(For HVM VMs only) Maximum amount of USB redirections
additional_xen_options	xl.cfg key value dict	N	Add additional Xen options²
auto_install	boolean	N	Install specified OS automatically, when no Xen configuration is found
reinstall	boolean	N	Reinstall the VM every time Ansible is running when set to True

VM interfaces

Each network interface may have the following options. All of them are optional.

Name	Type	Description
ip	string	IPv4 address of this interface
ipv6	string	IPv6 address of this interface
mac	string	MAC address of this interface
mtu	integer	MTU of this interface
bridge	string	Bridge to attach the interface to
vifname	string	Name of the vif on dom0
xen_str	string	Additional Xen parameters for this interface

Note that if you use xen_vman_default_vifname_prefix (and don't overwrite it using the vifname option), then .DEVID is appended to the vif name, whereby DEVID is the index of the interface. (Hence the name ..._prefix.) For example, when using xen_vman_default_vifname_prefix: "example", then the vifs are named example.0, example.1 and so on.

Example Playbook

- hosts: hypervisor
  roles:
    - xen_vman
      xen_vman_vms:
        - name: testvm
          interfaces:
          - ip: 10.0.0.15
            ipv6: fd76:5eac:234:70c8::15
            mac: 00:14:22:01:23:45
            bridge: mybridge
            os:
              type: ubuntu
              version: 18.04

License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Author Information

• Markus Mroch (Mr. Pi) [email protected]