Xen Commands Reference

The xl Toolstack

The xl (Xen Light) toolstack is the primary command-line interface for managing Xen virtual machines. It replaced the older xm toolstack and provides comprehensive control over domains, resources, networking, and storage. This reference covers all essential xl commands with practical examples and use cases.

All xl commands must be run as root or with sudo privileges. Configuration files are typically stored in /etc/xen/ directory.

System Information Commands

Display hypervisor and system information

xl info

Shows detailed information about the Xen hypervisor including version, number of CPUs, total memory, and various capabilities.

List all running domains

xl list

Displays all domains (both running and paused) with their ID, name, memory, VCPUs, state, and CPU time consumed.

Show detailed domain information

xl list -l domainname

Outputs complete domain configuration in JSON format, including all settings and current state.

Display verbose domain information

xl list -v

Shows extended information including UUID, security label, and additional state details for all domains.

View hypervisor console messages

xl dmesg

Displays the Xen hypervisor console log, useful for troubleshooting boot issues and hardware problems.

Clear hypervisor console buffer

xl dmesg -c

Clears the hypervisor message buffer after displaying current contents.

Show PCPU topology

xl info -n

Displays NUMA topology information, showing CPU and memory node relationships for optimization.

Domain Lifecycle Management

Create and start a domain from config file

xl create /etc/xen/myvm.cfg

Creates and starts a new domain using the specified configuration file.

Create domain with console attachment

xl create -c /etc/xen/myvm.cfg

Creates domain and immediately attaches to its console for monitoring the boot process.

Create domain in paused state

xl create -p /etc/xen/myvm.cfg

Creates domain but leaves it paused, useful for debugging or preparing pre-start operations.

Shutdown a domain gracefully

xl shutdown domainname

Sends ACPI shutdown signal to the domain, allowing it to shut down cleanly.

Shutdown all domains

xl shutdown --all

Gracefully shuts down all running domains (except Dom0).

Shutdown domain with timeout

xl shutdown -w domainname

Waits for domain to shutdown completely before returning. Useful in scripts.

Reboot a domain

xl reboot domainname

Sends reboot signal to domain, causing it to restart.

Force destroy a domain

xl destroy domainname

Immediately terminates domain without graceful shutdown. Use only when shutdown fails.

Pause a running domain

xl pause domainname

Suspends domain execution, freezing its state. Domain remains in memory but doesn't consume CPU.

Unpause a paused domain

xl unpause domainname

Resumes execution of a paused domain from exactly where it stopped.

Domain Save and Restore

Save domain to file

xl save domainname /save/path/domain.save

Saves complete domain state to disk and destroys the running instance. Can be restored later.

Save with checkpoint

xl save -c domainname /save/path/domain.save

Saves domain state but keeps domain running (checkpoint). Useful for backup purposes.

Restore domain from saved state

xl restore /save/path/domain.save

Restores a previously saved domain, resuming exactly where it left off.

Restore with console attachment

xl restore -c /save/path/domain.save

Restores domain and immediately attaches to console.

Restore in paused state

xl restore -p /save/path/domain.save

Restores domain but leaves it paused for inspection before resuming.

Live Migration

Migrate domain to another host

xl migrate domainname host2.example.com

Live migrates running domain to another physical host with minimal downtime.

Migrate with SSH connection

xl migrate -s ssh://host2.example.com domainname

Uses SSH for secure migration channel. Recommended for untrusted networks.

Migrate with debug output

xl migrate --debug domainname host2.example.com

Enables verbose output showing migration progress and performance statistics.

Console and Monitoring

Attach to domain console

xl console domainname

Connects to domain's console for direct interaction. Press Ctrl+] to detach.

Monitor domain events

xl top

Real-time display of domain CPU, memory, and network/disk I/O usage (similar to Linux 'top').

Display domain uptime

xl uptime

Shows how long each domain has been running.

Show domain uptime with timestamp

xl uptime -s domainname

Displays exact start time for specified domain.

Memory Management

Set domain maximum memory

xl mem-max domainname 2048

Sets maximum memory limit (in MB) that domain can use. Must be done while domain is paused.

Set domain current memory

xl mem-set domainname 1024

Adjusts current memory allocation using balloon driver. Can be done while domain runs.

Display memory usage

xl list -m

Shows detailed memory statistics for all domains including current, maximum, and shared memory.

Enable memory sharing

xl sharing domainname

Displays memory sharing statistics showing deduplicated pages.

CPU Management

List VCPU configuration

xl vcpu-list

Shows all VCPUs across all domains with their affinity and current physical CPU assignment.

List VCPUs for specific domain

xl vcpu-list domainname

Displays VCPU information only for the specified domain.

Set VCPU count

xl vcpu-set domainname 4

Changes number of active VCPUs for running domain (hot-plug/unplug).

Pin VCPU to physical CPU

xl vcpu-pin domainname 0 2

Pins VCPU 0 of domain to physical CPU 2, reducing cache misses and improving performance.

Pin VCPU to multiple CPUs

xl vcpu-pin domainname 0 2-5

Pins VCPU 0 to physical CPUs 2, 3, 4, and 5, allowing scheduler to choose among them.

Pin all VCPUs

xl vcpu-pin domainname all 2-5

Pins all VCPUs of domain to specified physical CPU range.

Scheduler Configuration

Show scheduler information

xl sched-credit

Displays Credit scheduler parameters for all domains.

Set domain CPU weight

xl sched-credit -d domainname -w 512

Sets CPU weight (default 256). Domain with weight 512 gets 2x CPU compared to weight 256.

Set domain CPU cap

xl sched-credit -d domainname -c 50

Caps domain CPU usage at 50% of one physical CPU (50 = 50%, 200 = 2 full CPUs).

Show Credit2 scheduler info

xl sched-credit2

Displays Credit2 scheduler parameters if Credit2 scheduler is active.

Set Credit2 weight

xl sched-credit2 -d domainname -w 512

Sets CPU weight for domain under Credit2 scheduler.

Show RTDS scheduler parameters

xl sched-rtds -v

Displays real-time scheduler parameters including period and budget for all domains.

Set RTDS parameters

xl sched-rtds -d domainname -v 0 -p 10000 -b 5000

Sets VCPU 0 to 10ms period with 5ms budget (50% CPU guaranteed).

Network Management

List network interfaces

xl network-list domainname

Shows all virtual network interfaces attached to domain with their configurations.

Attach network interface

xl network-attach domainname bridge=xenbr0

Hot-plugs new network interface to running domain connected to specified bridge.

Attach with MAC address

xl network-attach domainname bridge=xenbr0 mac=00:16:3e:xx:xx:xx

Attaches network interface with specific MAC address.

Detach network interface

xl network-detach domainname 0

Hot-unplugs network interface 0 from running domain.

Set network rate limiting

xl network-attach domainname bridge=xenbr0 rate=100Mb/s

Attaches interface with bandwidth rate limit of 100 Mbps.

Block Device Management

List block devices

xl block-list domainname

Shows all virtual block devices attached to domain with backend information.

Attach block device

xl block-attach domainname /dev/vg0/disk2 xvdb w

Hot-plugs block device to running domain as xvdb in read-write mode.

Attach read-only device

xl block-attach domainname /path/to/image.img xvdc r

Attaches disk image as read-only device xvdc.

Detach block device

xl block-detach domainname xvdb

Hot-unplugs specified block device from running domain.

Attach with backend specification

xl block-attach domainname /dev/vg0/disk backend=dom0 format=raw

Attaches device with explicit backend domain and format specification.

PCI Device Passthrough

List PCI devices

xl pci-list domainname

Shows all PCI devices assigned to domain.

Attach PCI device

xl pci-attach domainname 01:00.0

Assigns PCI device (by bus address) directly to domain for exclusive access.

Detach PCI device

xl pci-detach domainname 01:00.0

Removes PCI device assignment from domain, returning it to Dom0.

Attach with function masking

xl pci-attach domainname 01:00.0 permissive=1

Attaches PCI device in permissive mode (allows some unsafe operations, use carefully).

USB Device Management

List USB devices

xl usbctrl-list domainname

Shows USB controllers attached to domain.

Attach USB controller

xl usbctrl-attach domainname version=2 ports=4

Attaches virtual USB 2.0 controller with 4 ports to domain.

List USB devices on controller

xl usbdev-list domainname

Shows USB devices passed through to domain.

Attach USB device

xl usbdev-attach domainname 1-2

Passes through USB device at bus 1, port 2 to domain.

NUMA and CPU Pools

Show NUMA information

xl info -n

Displays NUMA node topology with CPU and memory distribution.

Display domain NUMA placement

xl vcpu-list -n

Shows VCPU placement across NUMA nodes.

Set NUMA node affinity

xl numa-pin domainname 0

Pins domain to NUMA node 0 for optimal memory locality.

List CPU pools

xl cpupool-list

Shows defined CPU pools and their CPU assignments.

Create CPU pool

xl cpupool-create name="rtpool" sched="rtds"

Creates new CPU pool with specified scheduler.

Add CPU to pool

xl cpupool-cpu-add rtpool 4

Adds physical CPU 4 to specified CPU pool.

Move domain to pool

xl cpupool-migrate domainname rtpool

Migrates domain to different CPU pool (and its scheduler).

Power Management

Show power management info

xl info | grep -i power

Displays power management capabilities and current state.

Get CPU frequency info

xenpm get-cpufreq-para

Shows CPU frequency scaling parameters for all physical CPUs.

Set CPU frequency governor

xenpm set-scaling-governor performance

Sets CPU frequency scaling governor (performance, powersave, ondemand, etc.).

Get C-state information

xenpm get-cpuidle-states

Displays CPU idle states (C-states) and their usage statistics.

Debug and Troubleshooting

Trigger debug keys

xl debug-keys h

Sends debug key 'h' (help) to hypervisor, output appears in xl dmesg.

Dump domain state

xl debug-keys d

Dumps detailed information about all domains to hypervisor console.

Show domain run queues

xl debug-keys r

Displays scheduler run queues showing which VCPUs are runnable.

Dump memory info

xl debug-keys m

Shows detailed memory allocation information in hypervisor log.

Start execution tracing

xentrace -D -e all trace.dat

Captures hypervisor execution traces for performance analysis.

Analyze trace file

xentrace_format trace.dat

Converts binary trace file to human-readable format.

Test domain creation

xl -vvv create -n /etc/xen/test.cfg

Dry-run domain creation with maximum verbosity, useful for config file testing.

Configuration File Examples

Basic PV Linux Guest

# /etc/xen/pvlinux.cfg
name = "pvlinux"
type = "pv"
kernel = "/boot/vmlinuz-xen"
ramdisk = "/boot/initrd-xen.img"
memory = 1024
vcpus = 2
disk = ['phy:/dev/vg0/pvlinux,xvda,w']
vif = ['bridge=xenbr0']
bootloader = "pygrub"
on_reboot = 'restart'
on_crash = 'restart'

HVM Windows Guest

# /etc/xen/windows.cfg
name = "windows"
type = "hvm"
memory = 4096
vcpus = 4
disk = ['file:/vm/windows.img,hda,w']
vif = ['bridge=xenbr0,model=e1000']
vnc = 1
vnclisten = "0.0.0.0"
vncpasswd = "changeme"
acpi = 1
apic = 1
pae = 1
on_poweroff = 'destroy'
on_reboot = 'restart'

Advanced Configuration with Resource Controls

# /etc/xen/production.cfg
name = "production"
type = "pv"
memory = 2048
maxmem = 4096
vcpus = 4
cpus = "2-5"
disk = ['phy:/dev/vg0/prod_root,xvda,w',
        'phy:/dev/vg0/prod_data,xvdb,w']
vif = ['bridge=xenbr0,rate=1000Mb/s']
sched_credit_weight = 512
sched_credit_cap = 0
on_reboot = 'restart'
on_crash = 'coredump-restart'
localtime = 0

Note: All xl commands require root privileges. Use 'sudo' if not running as root. Command availability may vary depending on Xen version and hypervisor configuration.

Command Quick Reference

Category	Common Commands	Purpose
Lifecycle	create, shutdown, destroy, reboot	Start, stop, and control domains
Information	list, info, top, uptime	View system and domain status
Resources	mem-set, vcpu-set, vcpu-pin	Manage CPU and memory
Devices	block-attach, network-attach, pci-attach	Hot-plug devices
Migration	migrate, save, restore	Move or backup domains
Debug	dmesg, debug-keys, console	Troubleshoot issues

Xen Hypervisor