We automatically generate an alias for virtually all devices if a user
hasn't provided one [1]. Indicate this.

Note that I have not listed all devices that support auto-generated
aliases since that list would be liable to get stale rather quickly.

[1] https://github.com/libvirt/libvirt/blob/v11.10.0/src/qemu/qemu_alias.c#L692-L786

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 docs/formatdomain.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 1467fc7e10..5cb387dc82 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -2593,7 +2593,7 @@ guest domain. All devices occur as children of the main ``devices`` element.
 
 To help users identifying devices they care about, every device can have direct
 child ``alias`` element which then has ``name`` attribute where users can store
-identifier for the device. The identifier has to have "ua-" prefix and must be
+identifier for the device. The identifier has to have ``ua-`` prefix and must be
 unique within the domain. Additionally, the identifier must consist only of the
 following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
 
@@ -2609,6 +2609,9 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
      ...
    </devices>
 
+If a user-specified alias is not provided, one will be automatically generated
+for most devices, based on attributes of the device such as its type.
+
 
 Hard drives, floppy disks, CDROMs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.52.0

On 12/18/25 18:06, Stephen Finucane wrote:
> We automatically generate an alias for virtually all devices if a user
> hasn't provided one [1]. Indicate this.
> 
> Note that I have not listed all devices that support auto-generated
> aliases since that list would be liable to get stale rather quickly.
> 
> [1] https://github.com/libvirt/libvirt/blob/v11.10.0/src/qemu/qemu_alias.c#L692-L786
> 
> Signed-off-by: Stephen Finucane <stephen@that.guru>
> ---
>  docs/formatdomain.rst | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> index 1467fc7e10..5cb387dc82 100644
> --- a/docs/formatdomain.rst
> +++ b/docs/formatdomain.rst
> @@ -2593,7 +2593,7 @@ guest domain. All devices occur as children of the main ``devices`` element.
>  
>  To help users identifying devices they care about, every device can have direct
>  child ``alias`` element which then has ``name`` attribute where users can store
> -identifier for the device. The identifier has to have "ua-" prefix and must be
> +identifier for the device. The identifier has to have ``ua-`` prefix and must be
>  unique within the domain. Additionally, the identifier must consist only of the
>  following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
>  
> @@ -2609,6 +2609,9 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
>       ...
>     </devices>
>  
> +If a user-specified alias is not provided, one will be automatically generated
> +for most devices, based on attributes of the device such as its type.

Not every driver does this. There are plenty of drivers (e.g. libxl,
lxc, vbox, esx) that don't have the concept of generated aliases. They
may support user aliases though (currently, CH, QEMU and libxl drivers
do that).

Maybe you need to reword this?

Michal

On Mon, 2025-12-22 at 14:55 +0100, Michal Prívozník wrote:
> On 12/18/25 18:06, Stephen Finucane wrote:
> > We automatically generate an alias for virtually all devices if a user
> > hasn't provided one [1]. Indicate this.
> > 
> > Note that I have not listed all devices that support auto-generated
> > aliases since that list would be liable to get stale rather quickly.
> > 
> > [1] https://github.com/libvirt/libvirt/blob/v11.10.0/src/qemu/qemu_alias.c#L692-L786
> > 
> > Signed-off-by: Stephen Finucane <stephen@that.guru>
> > ---
> >  docs/formatdomain.rst | 5 ++++-
> >  1 file changed, 4 insertions(+), 1 deletion(-)
> > 
> > diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> > index 1467fc7e10..5cb387dc82 100644
> > --- a/docs/formatdomain.rst
> > +++ b/docs/formatdomain.rst
> > @@ -2593,7 +2593,7 @@ guest domain. All devices occur as children of the main ``devices`` element.
> >  
> >  To help users identifying devices they care about, every device can have direct
> >  child ``alias`` element which then has ``name`` attribute where users can store
> > -identifier for the device. The identifier has to have "ua-" prefix and must be
> > +identifier for the device. The identifier has to have ``ua-`` prefix and must be
> >  unique within the domain. Additionally, the identifier must consist only of the
> >  following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
> >  
> > @@ -2609,6 +2609,9 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
> >       ...
> >     </devices>
> >  
> > +If a user-specified alias is not provided, one will be automatically generated
> > +for most devices, based on attributes of the device such as its type.
> 
> Not every driver does this. There are plenty of drivers (e.g. libxl,
> lxc, vbox, esx) that don't have the concept of generated aliases. They
> may support user aliases though (currently, CH, QEMU and libxl drivers
> do that).

Oh, that's a good point. I hadn't considered that. Have you any
preference for how to word this? Perhaps I could format this as a note
admonition like below?

```
.. note::

   If a user-specified alias is not provided, select drivers will
automatically generate one for most devices based on attributes of the
device such as its type. These drivers include `QEMU`__, `Cloud
Hypervisor`__, and libxml.

   __ https://libvirt.org/drvqemu.html
   __ https://libvirt.org/drvch.html

```

Cheers,
Stephen

> 
> Maybe you need to reword this?
> 
> Michal