Summary

This article describes the behavior of VM.xenstore_data. This behavior might affect customers who use the xenstore-data parameter of a Virtual Machine (VM), especially those customers who are writing software that interacts with XenServer and uses this parameter.

Behavior of VM.xenstore_data

• If there is a running guest VM in domain N then any changes to xenstore node /local/domain/N/vm-data (or its subtree of nodes) are reflected immediately in the contents of that VM's xenstore-data parameter.
• When a guest VM starts up in domain N:
  • The subtree /local/domain/N/vm-data in xenstore is populated based on the key-value entries of the xenstore-data parameter, but only for keys that start with the vm-data node. Intermediate nodes are created where needed.
  • The contents of the xenstore-data parameter are made to match exactly the contents of the relevant vm-data subtree of xenstore. Thus any keys that do not start with the vm-data node are deleted.

Examples and more detailed explanation

The examples in this section show the behavior on XenServer 6.1 and later. For XenServer 6.0.2 and earlier, this behavior is slightly different. This section highlights any differences in behavior shown by earlier versions.

The following example shows the initial state with a freshly installed guest VM. It happens to have been assigned domain 6. For convenience, we define a variable U with the uuid of the guest VM. This variable is used in subsequent commands.

[root@xenhost61 ~]# xe vm-list
uuid ( RO)           : 37f59a08-bbf7-86d3-c156-6911e9888996
     name-label ( RW): C6.4
    power-state ( RO): running


uuid ( RO)           : 78a50e33-8a0e-4c56-babb-9a761dbb7c54
     name-label ( RW): Control domain on host: xenhost61
    power-state ( RO): running


[root@xenhost61 ~]# U=37f59a08-bbf7-86d3-c156-6911e9888996
[root@xenhost61 ~]# xenstore-ls -f | grep vm-data
/local/domain/6/vm-data = ""
[root@xenhost61 ~]# xe vm-param-get uuid=$U param-name=xenstore-data 
vm-data: 

The following example shows that xenstore uses a tree structure: each node in the tree contains zero or more child nodes and has a string value which may be the empty string. The xenstore-ls -f command displays the entire tree, with a slash as the separator character in the paths; this is piped to grep to filter out only the parts of interest (lines containing the string "vm-data").

Changes in xenstore (for a running VM) are reflected immediately in the value of the parameter. In this sense the parameter is "live".

Note that in XenServer 6.0.2 and older, changes in xenstore are not reflected in the xenstore-data parameter of the VM.

[root@xenhost61 ~]# xenstore-write /local/domain/6/vm-data/a/b/c v123
[root@xenhost61 ~]# xenstore-ls -f | grep vm-data
/local/domain/6/vm-data = ""
/local/domain/6/vm-data/a = ""
/local/domain/6/vm-data/a/b = ""
/local/domain/6/vm-data/a/b/c = "v123"
[root@xenhost61 ~]# xe vm-param-get uuid=$U param-name=xenstore-data 
vm-data: ; vm-data/a: ; vm-data/a/b: ; vm-data/a/b/c: v123
[root@xenhost61 ~]# xenstore-write /local/domain/6/vm-data/a value_for_a
[root@xenhost61 ~]# xenstore-ls -f | grep vm-data
/local/domain/6/vm-data = ""
/local/domain/6/vm-data/a = "value_for_a"
/local/domain/6/vm-data/a/b = ""
/local/domain/6/vm-data/a/b/c = "v123"
[root@xenhost61 ~]# xe vm-param-get uuid=$U param-name=xenstore-data 
vm-data: ; vm-data/a: value_for_a; vm-data/a/b: ; vm-data/a/b/c: v123

The converse is not true: setting the parameter does not cause immediate change in xenstore, as shown in the following example. This example also demonstrates a path that does not start with the "vm-data" node.

[root@xenhost61 ~]# xe vm-param-set uuid=$U xenstore-data:vm-data/t1/t2/t3=abx
[root@xenhost61 ~]# xe vm-param-get uuid=$U param-name=xenstore-data 
vm-data/t1/t2/t3: abx; vm-data: ; vm-data/a: value_for_a; vm-data/a/b: ; vm-data/a/b/c: v123
[root@xenhost61 ~]# xe vm-param-set uuid=$U xenstore-data:not-vm-data/z1/z2/z3=foo
[root@xenhost61 ~]# xe vm-param-get uuid=$U param-name=xenstore-data 
not-vm-data/z1/z2/z3: foo; vm-data/t1/t2/t3: abx; vm-data: ; vm-data/a: value_for_a; vm-data/a/b: ; vm-data/a/b/c: v123
[root@xenhost61 ~]# xenstore-ls -f | grep vm-data
/local/domain/6/vm-data = ""
/local/domain/6/vm-data/a = "value_for_a"
/local/domain/6/vm-data/a/b = ""
/local/domain/6/vm-data/a/b/c = "v123"

When the VM is shut down, the xenstore entries disappear but the data in the VM parameter remains available unchanged, as shown in the following example. (While the VM is halted it still possible to use xe vm-param-set, but this is not demonstrated.)

[root@xenhost61 ~]# xe vm-shutdown uuid=$U 
[root@xenhost61 ~]# xenstore-ls -f | grep vm-data
[root@xenhost61 ~]# xenstore-list /local/domain
0
[root@xenhost61 ~]# xe vm-param-get uuid=$U param-name=xenstore-data 
not-vm-data/z1/z2/z3: foo; vm-data/t1/t2/t3: abx; vm-data: ; vm-data/a: value_for_a; vm-data/a/b: ; vm-data/a/b/c: v123
[root@xenhost61 ~]# xe vm-list
uuid ( RO)           : 37f59a08-bbf7-86d3-c156-6911e9888996
     name-label ( RW): C6.4
    power-state ( RO): halted


uuid ( RO)           : 78a50e33-8a0e-4c56-babb-9a761dbb7c54
     name-label ( RW): Control domain on host: xenhost61
    power-state ( RO): running

The following example shows what happens when a VM starts.

• The relevant subtree in xenstore is populated based on the key-value entries of the xenstore-data parameter, but only for keys that start with the vm-data node. Intermediate nodes are created where needed
• The contents of the xenstore-data parameter are made to match exactly the contents of the relevant vm-data subtree of xenstore. In the example shown, this involves the deletion of a key-value pair that does not start with the vm-data node (not-vm-data/z1/z2/z3, foo). Note that in XenServer 6.0.2 and older, the contents of the xenstore-data parameter of the VM are not changed.

[root@xenhost61 ~]# xe vm-start uuid=$U 
[root@xenhost61 ~]# xenstore-ls -f | grep vm-data
/local/domain/7/vm-data = ""
/local/domain/7/vm-data/t1 = ""
/local/domain/7/vm-data/t1/t2 = ""
/local/domain/7/vm-data/t1/t2/t3 = "abx"
/local/domain/7/vm-data/a = "value_for_a"
/local/domain/7/vm-data/a/b = ""

/local/domain/7/vm-data/a/b/c = "v123"
[root@xenhost61 ~]# xe vm-param-get uuid=$U param-name=xenstore-data
vm-data: ; vm-data/t1: ; vm-data/t1/t2: ; vm-data/t1/t2/t3: abx; vm-data/a: value_for_a; vm-data/a/b: ; vm-data/a/b/c: v123

This article describes the behavior of VM.xenstore_data. This behavior might affect customers who use the xenstore-data parameter of a Virtual Machine (VM), especially those customers who are writing software that interacts with XenServer and uses this parameter.