Applies to SUSE Linux Enterprise Server 15 SP3

29 XenStore: configuration database shared between domains #

This section introduces basic information about XenStore, its role in the Xen environment, the directory structure of files used by XenStore, and the description of XenStore's commands.

29.1 Introduction #

XenStore is a database of configuration and status information shared between VM Guests and the management tools running in Dom0. VM Guests and the management tools read and write to XenStore to convey configuration information, status updates, and state changes. The XenStore database is managed by Dom0 and supports simple operations such as reading and writing a key. VM Guests and management tools can be notified of any changes in XenStore by watching entries of interest. Note that the xenstored daemon is managed by the xencommons service.

XenStore is located on Dom0 in a single database file /var/lib/xenstored/tdb (tdb represents tree database).

29.2 File system interface #

XenStore database content is represented by a virtual file system similar to /proc (for more information on /proc, see Book “System Analysis and Tuning Guide”, Chapter 2 “System monitoring utilities”, Section 2.6 “The /proc file system”). The tree has three main paths: /vm, /local/domain, and /tool.

/vm - stores information about the VM Guest configuration.
/local/domain - stores information about VM Guest on the local node.
/tool - stores general information about various tools.

Tip

Each VM Guest has two different ID numbers. The universal unique identifier (UUID) remains the same even if the VM Guest is migrated to another machine. The domain identifier (DOMID) is an identification number that represents a particular running instance. It typically changes when the VM Guest is migrated to another machine.

29.2.1 XenStore commands #

The file system structure of the XenStore database can be operated with the following commands:

xenstore-ls: Displays the full dump of the XenStore database.
xenstore-readpath_to_xenstore_entry: Displays the value of the specified XenStore entry.
xenstore-existsxenstore_path: Reports whether the specified XenStore path exists.
xenstore-listxenstore_path: Displays all the children entries of the specified XenStore path.
xenstore-writepath_to_xenstore_entry: Updates the value of the specified XenStore entry.
xenstore-rmxenstore_path: Removes the specified XenStore entry or directory.
xenstore-chmodxenstore_pathmode: Updates the read/write permission on the specified XenStore path.
xenstore-control: Sends a command to the xenstored back-end, such as triggering an integrity check.

29.2.2 `/vm` #

The /vm path is indexed by the UUID of each VM Guest, and stores configuration information such as the number of virtual CPUs and the amount of allocated memory. There is a /vm/<uuid> directory for each VM Guest. To list the directory content, use xenstore-list.

> sudo xenstore-list /vm
00000000-0000-0000-0000-000000000000
9b30841b-43bc-2af9-2ed3-5a649f466d79-1

The first line of the output belongs to Dom0, and the second one to a running VM Guest. The following command lists all the entries related to the VM Guest:

> sudo xenstore-list /vm/9b30841b-43bc-2af9-2ed3-5a649f466d79-1
image
rtc
device
pool_name
shadow_memory
uuid
on_reboot
start_time
on_poweroff
bootloader_args
on_crash
vcpus
vcpu_avail
bootloader
name

To read a value of an entry, for example the number of virtual CPUs dedicated to the VM Guest, use xenstore-read:

> sudo xenstore-read /vm/9b30841b-43bc-2af9-2ed3-5a649f466d79-1/vcpus
1

A list of selected /vm/<uuid> entries follows:

uuid: UUID of the VM Guest. It does not change during the migration process.
on_reboot: Specifies whether to destroy or restart the VM Guest in response to a reboot request.
on_poweroff: Specifies whether to destroy or restart the VM Guest in response to a halt request.
on_crash: Specifies whether to destroy or restart the VM Guest in response to a crash.
vcpus: Number of virtual CPUs allocated to the VM Guest.
vcpu_avail: Bitmask of active virtual CPUs for the VM Guest. The bitmask has several bits equal to the value of vcpus, with a bit set for each online virtual CPU.
name: The name of the VM Guest.

Regular VM Guests (not Dom0) use the /vm/<uuid>/image path:

> sudo xenstore-list /vm/9b30841b-43bc-2af9-2ed3-5a649f466d79-1/image
ostype
kernel
cmdline
ramdisk
dmargs
device-model
display

An explanation of the used entries follows:

ostype: The OS type of the VM Guest.
kernel: The path on Dom0 to the kernel for the VM Guest.
cmdline: The kernel command line for the VM Guest used when booting.
ramdisk: The path on Dom0 to the RAM disk for the VM Guest.
dmargs: Shows arguments passed to the QEMU process. If you look at the QEMU process with ps, you should see the same arguments as in /vm/<uuid>/image/dmargs.

29.2.3 `/local/domain/<domid>` #

This path is indexed by the running domain (VM Guest) ID, and contains information about the running VM Guest. Remember that the domain ID changes during VM Guest migration. The following entries are available:

vm: The path of the /vm directory for this VM Guest.
on_reboot, on_poweroff, on_crash, name: See identical options in Section 29.2.2, “/vm”
domid: Domain identifier for the VM Guest.
cpu: The current CPU to which the VM Guest is pinned.
cpu_weight: The weight assigned to the VM Guest for scheduling purposes. Higher weights use the physical CPUs more often.

Apart from the individual entries described above, there are also several subdirectories under /local/domain/<domid>, containing specific entries. To see all entries available, refer to XenStore Reference.

/local/domain/<domid>/memory: Contains memory information. /local/domain/<domid>/memory/target contains target memory size for the VM Guest (in kilobytes).
/local/domain/<domid>/console: Contains information about a console used by the VM Guest.
/local/domain/<domid>/backend: Contains information about all back-end devices used by the VM Guest. The path has subdirectories of its own.
/local/domain/<domid>/device: Contains information about the front-end devices for the VM Guest.
/local/domain/<domid>/device-misc: Contains miscellaneous information about devices.
/local/domain/<domid>/store: Contains information about the VM Guest's store.