1# XenStore Paths 2 3This document attempts to defines all the paths which are in common 4use by either guests, front-/back-end drivers, toolstacks etc. 5 6The XenStore wire protocol itself is described in 7[xenstore.txt](xenstore.txt). 8 9## Notation 10 11This document is intended to be partially machine readable, such that 12test system etc can use it to validate whether the xenstore paths used 13by a test are allowable etc. 14 15Therefore the following notation conventions apply: 16 17A xenstore path is generically defined as: 18 19 PATH = VALUES [TAGS] 20 21 PATH/* [TAGS] 22 23The first syntax defines a simple path with a single value. The second 24syntax defines an aggregated set of paths which are usually described 25externally to this document. The text will give a pointer to the 26appropriate external documentation. 27 28PATH can contain simple regex constructs following the Perl compatible 29regexp syntax described in pcre(3) or perlre(1). In addition the 30following additional wild card names are defined and are evaluated 31before regexp expansion: 32 33* ~ -- expands to an arbitrary a domain's home path (described below). 34 Only valid at the begining of a path. 35* $DEVID -- a per-device type device identifier. Typically an integer. 36* $DOMID -- a domain identifier, an integer. Typically this refers to 37 the "other" domain. i.e. ~ refers to the domain providing a service 38 while $DOMID is the consumer of that service. 39* $UUID -- a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 40* $INDEX -- an integer used as part of a path when listing a set of 41 values. Typically these integers are contiguous. 42 43VALUES are strings and can take the following forms: 44 45* PATH -- a XenStore path. 46* STRING -- an arbitrary string. 47* INTEGER -- An integer, in decimal representation unless otherwise 48 noted. 49 * MEMKB -- the decimal representation of a number of kilobytes. 50 * EVTCHN -- the decimal representation of an event channel. 51 * GNTREF -- the decimal representation of a grant reference. 52* "a literal string" -- literal strings are contained within quotes. 53* (VALUE | VALUE | ... ) -- a set of alternatives. Alternatives are 54 separated by a "|" and all the alternatives are enclosed in "(" and 55 ")". 56* DISTRIBUTION -- information about a software distribution, comprised 57 of 3 or 4 space separated UTF-8 strings as follows: 58 59 VENDOR -- Commonly used vendor short name, 60 e.g "Citrix" rather than "Citrix Systems 61 Inc." 62 63 PRODUCT -- Commonly used product (e.g. driver) name 64 without version information. 65 66 If the toolstack needs to match on either of the above 67 values it should support Unix glob style matching. 68 69 VERSION -- A version number that will sort properly 70 under coreutils version sorting (sort -V) 71 rules. 72 73 ATTRIBUTES -- Optional human readable text to denote 74 attributes of the software, e.g. "debug". 75 This text is freeform and no meaning 76 should be inferred. It is intended for 77 display purposes only. 78 79* MAC_ADDRESS -- 6 integers, in hexadecimal form, separated by ':', 80 specifying an IEEE 802.3 ethernet MAC address. 81* IPV4_ADDRESS -- 4 integers, in decimal form, separated by '.', 82 specifying an IP version 4 address as described 83 IETF RFC 791. 84* IPV6_ADDRESS -- Up to 8 integers, in hexadecimal form, separated 85 by ':', specifying an IP version 6 address as 86 described in IETF RFC 4291. 87 88Additional TAGS may follow as a comma separated set of the following 89tags enclosed in square brackets. 90 91* w -- Path is writable by the containing domain, that is the domain 92 whose home path ~ this key is under or which /vm/$UUID refers to. By 93 default paths under both of these locations are read only for the 94 domain. 95* n -- Path is neither readable nor writeable for guest domains. 96* HVM -- Path is valid for HVM domains only 97* PV -- Path is valid for PV domains only 98* BACKEND -- Path is valid for a backend domain (AKA driver domain) 99* INTERNAL -- Although a path is visible to the domain its use is 100 reserved for the virtual firmware or Xen platform code. Guest 101 Operating Systems must not read this key or otherwise rely on its 102 presence or contents. 103* DEPRECATED -- This path is deprecated and may be removed in its 104 current form in the future. Guests should not add new dependencies 105 on such paths. 106 107Owning domain means the domain whose home path this tag is found 108under. 109 110Lack of either a __HVM__ or __PV__ tag indicates that the path is 111valid for either type of domain (including PVonHVM and similar mixed 112domain types). 113 114## Domain Home Path 115 116Every domain has a home path within the xenstore hierarchy. This is 117the path where the majority of the domain-visible information about 118each domain is stored. 119 120This path is: 121 122 /local/domain/$DOMID 123 124All non-absolute paths are relative to this path. 125 126Although this path could be considered a "Home Directory" for the 127domain it would not usually be writable by the domain. The tools will 128create writable subdirectories as necessary. 129 130## Per Domain Paths 131 132## General Paths 133 134#### ~/vm = PATH [] 135 136A pointer back to the domain's /vm/$UUID path (described below). 137 138#### ~/name = STRING [] 139 140The guests name. 141 142#### ~/domid = INTEGER [] 143 144The domain's own ID. 145 146#### ~/image/device-model-pid = INTEGER [INTERNAL] 147 148The process ID of the device model associated with this domain, if it 149has one. 150 151#### ~/cpu/[0-9]+/availability = ("online"|"offline") [PV] 152 153One node for each virtual CPU up to the guest's configured 154maximum. Valid values are "online" and "offline". The guest is expected to react to changes in this path by bringing the appropriate VCPU on or offline using the VCPUOP interface described in [xen/include/public/vcpu.h][VCPU] 155 156This protocol is not currently well documented. 157 158#### ~/memory/static-max = MEMKB [] 159 160Specifies a static maximum amount memory which this domain should 161expect to be given. In the absence of in-guest memory hotplug support 162this set on domain boot and is usually the maximum amount of RAM which 163a guest can make use of. See [docs/misc/libxl_memory.txt][LIBXLMEM] 164for a description of how memory is accounted for in toolstacks using 165the libxl library. 166 167#### ~/memory/target = MEMKB [] 168 169The current balloon target for the domain. The balloon driver within 170the guest is expected to make every effort to every effort use no more 171than this amount of RAM. 172 173#### ~/memory/videoram = MEMKB [HVM,INTERNAL] 174 175The size of the video RAM this domain is configured with. 176 177#### ~/device/suspend/event-channel = ""|EVTCHN [w] 178 179The domain's suspend event channel. The toolstack will create this 180path with an empty value which the guest may choose to overwrite. 181 182If the guest overwrites this, it will be with the number of an unbound 183event channel port it has acquired. The toolstack is expected to use 184an interdomain bind, and then, when it wishes to ask the guest to 185suspend, to signal the event channel. 186 187The guest does not need to explicitly acknowledge the request; indeed, 188there is no explicit signalling by the guest in the reverse direction. 189The guest, when it is ready, simply shuts down (`SCHEDOP_shutdown`) 190with reason code `SHUTDOWN_suspend`. The toolstack is expected to use 191`XEN_DOMCTL_subscribe` to be alerted to guest state changes, and 192`XEN_SYSCTL_getdomaininfolist` to verify that the domain has 193suspended. 194 195Note that the use of this event channel suspend protocol is optional 196for both sides. By writing a non-empty string to the node, the guest 197is advertising its support. However, the toolstack is at liberty to 198use the xenstore-based protocol instead (see ~/control/shutdown, 199below) even if the guest has advertised support for the event channel 200protocol. 201 202#### ~/hvmloader/allow-memory-relocate = ("1"|"0") [HVM,INTERNAL] 203 204If the default low MMIO hole (below 4GiB) is not big enough for all 205the devices, this indicates if hvmloader should relocate guest memory 206into the high memory region (above 4GiB). If "1", hvmloader will 207relocate memory as needed, until 2GiB is reached; if "0", hvmloader 208will not relocate guest memory. 209 210#### ~/hvmloader/bios = ("rombios"|"seabios"|"OVMF") [HVM,INTERNAL] 211 212The BIOS used by this domain. 213 214#### ~/bios-strings/bios-vendor = STRING [HVM,INTERNAL] 215#### ~/bios-strings/bios-version = STRING [HVM,INTERNAL] 216#### ~/bios-strings/system-manufacturer = STRING [HVM,INTERNAL] 217#### ~/bios-strings/system-product-name = STRING [HVM,INTERNAL] 218#### ~/bios-strings/system-version = STRING [HVM,INTERNAL] 219#### ~/bios-strings/system-serial-number = STRING [HVM,INTERNAL] 220#### ~/bios-strings/enclosure-manufacturer = STRING [HVM,INTERNAL] 221#### ~/bios-strings/enclosure-serial-number = STRING [HVM,INTERNAL] 222#### ~/bios-strings/enclosure-asset-tag = STRING [HVM,INTERNAL] 223#### ~/bios-strings/battery-manufacturer = STRING [HVM,INTERNAL] 224#### ~/bios-strings/battery-device-name = STRING [HVM,INTERNAL] 225 226These xenstore values are used to override some of the default string 227values in the SMBIOS table constructed in hvmloader. See the SMBIOS 228table specification at http://www.dmtf.org/standards/smbios/ 229 230#### ~/bios-strings/oem-* = STRING [HVM,INTERNAL] 231 2321 to 99 OEM strings can be set in xenstore using values of the form 233'~/bios-strings/oem-1' to '~/bios-strings/oem-99'. These strings will be 234loaded into the SMBIOS type 11 structure. 235 236#### ~/platform/* = ("0"|"1") [HVM,INTERNAL] 237 238Various boolean platform properties. 239 240* acpi -- is ACPI enabled for this domain 241* acpi_s3 -- is ACPI S3 support enabled for this domain 242* acpi_s4 -- is ACPI S4 support enabled for this domain 243* acpi_laptop_slate -- is the ACPI laptop/slate device present in 244 this domain 245 246#### ~/platform/generation-id = INTEGER ":" INTEGER [HVM,INTERNAL] 247 248The lower and upper 64-bit words of the 128-bit VM Generation ID. 249 250This key is used by hvmloader to create the ACPI VM Generation ID 251device. It initialises a 16 octet region of guest memory with this 252value. The guest physical address of this region is saved in the 253HVM_PARAM_VM_GENERATION_ID_ADDR HVM parameter. 254 255If this key is not present, is empty, or is all-zeros ("0:0") then the 256ACPI device is not created. 257 258When restoring a guest, the toolstack may (in certain circumstances) 259need generate a new random generation ID and write it to guest memory 260at the guest physical address in HVM_PARAM_VM_GENERATION_ID_ADDR. 261 262See Microsoft's "Virtual Machine Generation ID" specification for the 263circumstances where the generation ID needs to be changed. 264 265### Frontend device paths 266 267Paravirtual device frontends are generally specified by their own 268directory within the XenStore hierarchy. Usually this is under 269~/device/$TYPE/$DEVID although there are exceptions, e.g. ~/console 270for the first PV console. 271 272#### ~/device/vbd/$DEVID/* [] 273 274A virtual block device frontend. Described by 275[xen/include/public/io/blkif.h][BLKIF] 276 277#### ~/device/vfb/$DEVID/* [] 278 279A virtual framebuffer frontend. Described by 280[xen/include/public/io/fbif.h][FBIF] 281 282#### ~/device/vkbd/$DEVID/* [] 283 284A virtual keyboard device frontend. Described by 285[xen/include/public/io/kbdif.h][KBDIF] 286 287#### ~/device/vif/$DEVID/* [] 288 289A virtual network device frontend. Described by 290[xen/include/public/io/netif.h][NETIF] 291 292#### ~/device/vscsi/$DEVID/* [] 293 294A virtual scsi device frontend. Described by 295[xen/include/public/io/vscsiif.h][SCSIIF] 296 297#### ~/device/vusb/$DEVID/* [] 298 299A virtual usb device frontend. Described by 300[xen/include/public/io/usbif.h][USBIF] 301 302#### ~/console/* [] 303 304The primary PV console device. Described in [console.txt](console.txt) 305 306#### ~/device/console/$DEVID/* [] 307 308A secondary PV console device. Described in [console.txt](console.txt) 309 310#### ~/serial/$DEVID/* [HVM] 311 312An emulated serial device. Described in [console.txt](console.txt) 313 314#### ~/store/port = EVTCHN [DEPRECATED] 315 316The event channel used by the domain's connection to XenStore. 317 318This path is deprecated since the same information is provided via the 319[start_info][SI] for PV guests and as an [HVM param][HVMPARAMS] for 320HVM guests. There is an obvious chicken and egg problem with 321extracting this value from xenstore in order to setup the xenstore 322communication ring. 323 324#### ~/store/ring-ref = GNTREF [DEPRECATED] 325 326The grant reference of the domain's XenStore ring. 327 328As with ~/store/port this path is deprecated. 329 330### Backend Device Paths 331 332Paravirtual device backends are generally specified by their own 333directory within the XenStore hierarchy. Usually this is under 334~/backend/$TYPE/$DOMID/$DEVID. 335 336#### ~/backend/vbd/$DOMID/$DEVID/* [] 337 338A virtual block device backend. Described by 339[xen/include/public/io/blkif.h][BLKIF] 340 341Uses the in-kernel blkback driver. 342 343#### ~/backend/qdisk/$DOMID/$DEVID/* [] 344 345A virtual block device backend. Described by 346[xen/include/public/io/blkif.h][BLKIF] 347 348Uses the qemu based disk backend. 349 350#### ~/backend/tap/$DOMID/$DEVID/* [] 351 352A virtual block device backend. Described by 353[xen/include/public/io/blkif.h][BLKIF] 354 355Uses the in-kernel blktap (v1) disk backend (deprecated). 356 357#### ~/backend/vfb/$DOMID/$DEVID/* [] 358 359A virtual framebuffer backend. Described by 360[xen/include/public/io/fbif.h][FBIF] 361 362#### ~/backend/vkbd/$DOMID/$DEVID/* [] 363 364A virtual keyboard device backend. Described by 365[xen/include/public/io/kbdif.h][KBDIF] 366 367#### ~/backend/vif/$DOMID/$DEVID/* [] 368 369A virtual network device backend. Described by 370[xen/include/public/io/netif.h][NETIF] 371 372#### ~/backend/vscsi/$DOMID/$DEVID/* [] 373 374A PV SCSI backend. 375 376#### ~/backend/vusb/$DOMID/$DEVID/* [] 377 378A PV USB backend. Described by 379[xen/include/public/io/usbif.h][USBIF] 380 381#### ~/backend/console/$DOMID/$DEVID/* [] 382 383A PV console backend. Described in [console.txt](console.txt) 384 385#### ~/backend/qusb/$DOMID/$DEVID/* [] 386 387A PV USB device backend. Described by 388[xen/include/public/io/usbif.h][USBIF] 389 390Uses the qemu based USB backend. 391 392#### ~/device-model/$DOMID/* [INTERNAL] 393 394Information relating to device models running in the domain. $DOMID is 395the target domain of the device model. 396 397#### ~/libxl/disable_udev = ("1"|"0") [] 398 399Indicates whether device hotplug scripts in this domain should be run 400by udev ("0") or will be run by the toolstack directly ("1"). 401 402### Platform Feature and Control Paths 403 404#### ~/control/shutdown = (""|COMMAND) [w] 405 406This is the PV shutdown control node. A toolstack can write various 407commands here to cause various guest shutdown, reboot or suspend 408activities. The guest acknowledges a request by writing the empty 409string back to the command node. 410 411The precise protocol is not yet documented. 412 413#### ~/control/feature-poweroff = (""|"0"|"1") [w] 414#### ~/control/feature-reboot = (""|"0"|"1") [w] 415#### ~/control/feature-suspend = (""|"0"|"1") [w] 416 417These may be initialized to "" by the toolstack and may then be set 418to 0 or 1 by a guest to indicate whether it is capable or incapable, 419respectively, of responding to the corresponding command when written 420to ~/control/shutdown. 421A toolstack may then sample the feature- value at the point of issuing 422a PV control command and respond accordingly: 423 424"0" -> the frontend should not be expected to respond, so fail the 425 control operation 426"1" -> the frontend should be expected to respond, so wait for it to 427 do so and maybe fail the control operation after some reasonable 428 timeout. 429"" -> the frontend may or may not respond, so wait for it to do so and 430 then maybe try an alternative control mechanism after some 431 reasonable timeout. 432 433Since a toolstack may not initialize these paths, and the parent 434~/control path is read-only to a guest, a guest should not expect a 435write to succeed. If it fails the guest may log the failure but should 436continue to process the corresponding command when written to 437~/control/shutdown regardless. 438 439#### ~/control/feature-s3 = (""|"0"|"1") [w,HVM] 440#### ~/control/feature-s4 = (""|"0"|"1") [w,HVM] 441 442These purpose of these feature flags is identical to feature-poweroff, 443feature-reboot and feature-suspend above but concern triggering the 444S3 or S4 power states of HVM guests. 445A toolstack may create these values, but should not sample them unless 446the corresponding acpi_ feature flag is set in ~/platform. 447 448#### ~/control/platform-feature-multiprocessor-suspend = (0|1) [] 449 450Indicates to the guest that this platform supports the multiprocessor 451suspend feature. 452 453#### ~/control/platform-feature-xs\_reset\_watches = (0|1) [] 454 455Indicates to the guest that this platform supports the 456XS_RESET_WATCHES xenstore message. See 457[xen/include/public/io/xs\_wire.h][XSWIRE] for the XenStore wire 458protocol definition. 459 460#### ~/control/laptop-slate-mode = (""|"laptop"|"slate") [w] 461 462This is the PV laptop/slate mode control node. If the toolstack has 463provisioned a guest with the ACPI laptop/slate mode device then it 464can write the desired mode here to cause the guest to switch modes if 465necessary. The guest acknowledges a request by writing the empty 466string back to the control node. 467 468#### ~/control/feature-laptop-slate-mode = (""|"0"|"1") [w] 469 470This may be initialized to "" by the toolstack and may then be set 471to 0 or 1 by a guest to indicate whether it is capable or incapable, 472respectively, of responding to a mode value written to 473~/control/laptop-slate-mode. 474 475### Domain Controlled Paths 476 477#### ~/data/* [w] 478 479A domain writable path. Available for arbitrary domain use. 480 481#### ~/drivers/$INDEX = DISTRIBUTION [w] 482 483A domain may write information about installed PV drivers using 484paths of this form. 485 486#### ~/feature/hotplug/vif = ("0"|"1") [w] 487#### ~/feature/hotplug/vbd = ("0"|"1") [w] 488 489By setting these paths to "1" a guest can indicate to a toolstack 490that it is capable of responding immediately to instantiation of, 491respectively, new vif by bringing online a new PV network device or 492a new vbd by bringing online a new PV block device. 493If the guest sets this path to "0" then it is indicating that it is 494definitely unable to respond immediately and hence the toolstack should 495defer instantiaton to the next VM start. However, if the path is absent 496then the toolstack may attempt the operation. 497 498#### ~/attr/vif/$DEVID/name = STRING [w] 499 500A domain may write its internal 'friendly' name for a network device 501using this path using UTF-8 encoding. A toolstack or UI may use this 502for display purposes. No particular meaning should be inferred from the 503name. 504 505#### ~/attr/vif/$DEVID/mac/$INDEX = MAC_ADDRESS [w] 506 507Paths of this form may be written by the guest to indicate MAC addresses 508it is currently using. These may be multicast or unicast addresses. For 509any of the paths the value of $INDEX is arbitrary. 510The values written are primarily for display purposes and must not be used 511for packet filtering or routing purposes. 512 513#### ~/attr/vif/$DEVID/ipv4/$INDEX = IPV4_ADDRESS [w] 514#### ~/attr/vif/$DEVID/ipv6/$INDEX = IPV6_ADDRESS [w] 515 516Paths of this form may be written by the guest to indicate IP addresses 517in use by the stack bound to the network frontend. For any of the paths 518the value of $INDEX is arbitrary. 519The values written are primarily for display purposes and must not be used 520for packet filtering or routing purposes. A toolstack may attempt to use an 521address written in one of these paths to, for example, establish a VNC 522session to the guest (although clearly some level of trust is placed 523in the value supplied by the guest in this case). 524 525### Paths private to the toolstack 526 527#### ~/device-model/$DOMID/state [w] 528 529Contains the status of the device models running on the domain. 530 531#### ~/device-model/$DOMID/backends/* [w] 532 533Backend types the device model is supporting. Each entry below backends 534is a directory which may contain further nodes specific to the backend 535type. The name of each backend directory is the same as the backend type 536(e.g. "qdisk"). 537 538#### ~/libxl/$DOMID/qdisk-backend-pid [w] 539 540Contains the PIDs of the device models running on the domain. 541 542## Virtual Machine Paths 543 544The /vm/$UUID namespace is used by toolstacks to store various 545information relating to the domain which is not intended to be guest 546visible (hence they are all tagged [n,INTERNAL]). 547 548Several of the keys here are not well defined and/or not well located 549and are liable to be replaced with more fully defined paths in the 550future. 551 552### /vm/$UUID/uuid = UUID [n,INTERNAL] 553 554Value is the same UUID as the path. 555 556### /vm/$UUID/name = STRING [n,INTERNAL] 557 558The domain's name. 559 560### /vm/$UUID/image/* [n,INTERNAL] 561 562Various information relating to the domain builder used for this guest. 563 564### /vm/$UUID/start_time = INTEGER "." INTEGER [n,INTERNAL] 565 566The time which the guest was started in SECONDS.MICROSECONDS format 567 568### /vm/$UUID/rtc/timeoffset = ""|INTEGER [n,HVM,INTERNAL] 569 570The guest's virtual time offset from UTC in seconds. 571 572## Platform-Level paths 573 574### libxl Specific Paths 575 576#### /libxl/$DOMID/device/$KIND/$DEVID 577 578Created by libxl for every frontend/backend pair created for $DOMID. 579Used by libxl for enumeration and management of the device. 580 581#### /libxl/$DOMID/device/$KIND/$DEVID/frontend 582 583Path in xenstore to the frontend, normally 584/local/domain/$DOMID/device/$KIND/$DEVID 585 586#### /libxl/$DOMID/device/$KIND/$DEVID/backend 587 588Path in xenstore to the backend, normally 589/local/domain/$BACKEND_DOMID/backend/$KIND/$DOMID/$DEVID 590 591#### /libxl/$DOMID/device/$KIND/$DEVID/$NODE 592 593Trustworthy copy of /local/domain/$DOMID/backend/$KIND/$DEVID/$NODE. 594 595#### /libxl/$DOMID/dm-version ("qemu\_xen"|"qemu\_xen\_traditional") = [n,INTERNAL] 596 597The device model version for a domain. 598 599#### /libxl/$DOMID/remus/netbuf/$DEVID/ifb = STRING [n,INTERNAL] 600 601ifb device used by Remus to buffer network output from the associated vif. 602 603### xenstored specific paths 604 605The /tool/xenstored namespace is created by the xenstore daemon or domain 606for the toolstack to obtain e.g. the domain id of a xenstore domain. 607 608#### /tool/xenstored/domid = INTEGER [n,INTERNAL] 609 610Domain Id of the xenstore domain in case xenstore is provided via a 611domain instead of a daemon in dom0. 612 613[BLKIF]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,io,blkif.h.html 614[FBIF]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,io,fbif.h.html 615[HVMPARAMS]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,hvm,params.h.html 616[KBDIF]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,io,kbdif.h.html 617[LIBXLMEM]: http://xenbits.xen.org/docs/unstable/misc/libxl_memory.txt 618[NETIF]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,io,netif.h.html 619[SCSIIF]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,io,vscsiif.h.html 620[SI]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,xen.h.html#Struct_start_info 621[USBIF]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,io,usbif.h.html 622[VCPU]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,vcpu.h.html 623[XSWIRE]: http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,io,xs_wire.h.html 624