We documented this almost everywhere, but missed it on several places. https://bugzilla.redhat.com/show_bug.cgi?id=1208763 --- Hopefully I didn't miss any place where it should be fixed as well. I also thought about adding a check for this issue in the code, but we probably do not want to do that during parsing, as the existing domains might as well disappear. The other thing is, that if the path is invalid, "No such file or directory" is returned which in my opinion describes the problem quite well. docs/formatdomain.html.in | 35 +++++++++++++++++++---------------- docs/formatstorage.html.in | 7 ++++--- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 1b496c3..7ceb1fa 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -126,7 +126,8 @@ provides details on allowed values for these. <span class="since">Since 0.0.1</span></dd> <dt><code>loader</code></dt> - <dd>The optional <code>loader</code> tag refers to a firmware blob + <dd>The optional <code>loader</code> tag refers to a firmware blob, + which is specified by absolute path, used to assist the domain creation process. It is used by Xen fully virtualized domains as well as setting the QEMU BIOS file path for QEMU/KVM domains. <span class="since">Xen since 0.1.0, @@ -142,10 +143,10 @@ <code>pflash</code>.</dd> <dt><code>nvram</code></dt> <dd>Some UEFI firmwares may want to use a non-volatile memory to store - some variables. In the host, this is represented as a file and the path - to the file is stored in this element. Moreover, when the domain is - started up libvirt copies so called master NVRAM store file defined - in <code>qemu.conf</code>. If needed, the <code>template</code> + some variables. In the host, this is represented as a file and the + absolute path to the file is stored in this element. Moreover, when the + domain is started up libvirt copies so called master NVRAM store file + defined in <code>qemu.conf</code>. If needed, the <code>template</code> attribute can be used to per domain override map of master NVRAM stores from the config file. Note, that for transient domains if the NVRAM file has been created by libvirt it is left behind and it is management @@ -971,7 +972,7 @@ resource partitions, potentially with nesting of said partitions. The <code>resource</code> element groups together configuration related to resource partitioning. It currently supports a child - element <code>partition</code> whose content defines the path + element <code>partition</code> whose content defines the absolute path of the resource partition in which to place the domain. If no partition is listed, then the domain will be placed in a default partition. It is the responsibility of the app/admin to ensure @@ -1954,8 +1955,8 @@ <dt><code>type='block'</code> <span class="since">since 0.0.3</span></dt> <dd> - The <code>dev</code> attribute specifies the path to the - host device to serve as the disk. + The <code>dev</code> attribute specifies the fully-qualified path + to the host device to serve as the disk. </dd> <dt><code>type='dir'</code> <span class="since">since 0.7.5</span></dt> @@ -3226,7 +3227,7 @@ versions of qemu used a default of "off", while newer qemus have a default of "on"). <span class="since">Since 0.9.7 (QEMU and KVM only)</span>. The optional - <code>file</code> attribute is used to point to a binary file + <code>file</code> attribute contains an absolute path to a binary file to be presented to the guest as the device's ROM BIOS. This can be useful, for example, to provide a PXE boot ROM for a virtual function of an sr-iov capable ethernet device (which @@ -3285,7 +3286,8 @@ <p> Block / character devices from the host can be passed through to the guest using the <code>hostdev</code> element. This is - only possible with container based virtualization. + only possible with container based virtualization. Devices are specified + by a fully qualified path. <span class="since">since after 1.0.1 for LXC</span>: </p> @@ -5486,11 +5488,12 @@ qemu-kvm -net nic,model=? /dev/null <dl> <dt><code>master</code></dt> - <dd>Master device of the pair, that is passed to the hypervisor.</dd> + <dd>Master device of the pair, that is passed to the hypervisor. + Device is specified by a fully qualified path.</dd> <dt><code>slave</code></dt> <dd>Slave device of the pair, that is passed to the clients for connection - to the guest console.</dd> + to the guest console. Device is specified by a fully qualified path.</dd> </dl> <h4><a name="elementsSound">Sound devices</a></h4> @@ -5834,8 +5837,8 @@ qemu-kvm -net nic,model=? /dev/null <p> This backend type requires exclusive access to a TPM device on the host. - An example for such a device is /dev/tpm0. The filename is - specified as path attribute of the <code>source</code> element. + An example for such a device is /dev/tpm0. The fully qualified file + name is specified by path attribute of the <code>source</code> element. If no file name is specified then /dev/tpm0 is automatically used. </p> </dd> @@ -5941,8 +5944,8 @@ qemu-kvm -net nic,model=? /dev/null <dd> The optional <code>server</code> element can be used to configure a server socket the device is supposed to connect to. The optional - <code>path</code> attribute specifies the path to the unix socket and - defaults to <code>/var/lib/libvirt/shmem/$shmem-$name-sock</code>. + <code>path</code> attribute specifies the absolute path to the unix socket + and defaults to <code>/var/lib/libvirt/shmem/$shmem-$name-sock</code>. </dd> <dt><code>msi</code></dt> <dd> diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in index 9c7b1bd..479e73c 100644 --- a/docs/formatstorage.html.in +++ b/docs/formatstorage.html.in @@ -379,9 +379,10 @@ <dl> <dt><code>path</code></dt> <dd>Provides the location at which the pool will be mapped into - the local filesystem namespace. For a filesystem/directory based - pool it will be the name of the directory in which volumes will - be created. For device based pools it will be the name of the directory in which + the local filesystem namespace, as an absolute path. For a + filesystem/directory based pool it will be a fully qualified name of + the directory in which volumes will be created. For device based pools + it will be a fully qualified name of the directory in which devices nodes exist. For the latter <code>/dev/</code> may seem like the logical choice, however, devices nodes there are not guaranteed stable across reboots, since they are allocated on -- 1.9.3