[PATCH 1/2] docs: formatdomain: Add examples for nbd source
Signed-off-by: Han Han <hhan@redhat.com> --- docs/formatdomain.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 18e237c157..49713a12d4 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -2409,6 +2409,27 @@ paravirtualized driver is specified via the ``disk`` element. </source> <target dev='vde' bus='virtio'/> </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='nbd' tls='yes'> + <host name='example.com' port='10809'/> + </source> + <target dev='vdf' bus='virtio'/> + </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='nbd' name='bar' tls='no'> + <host name='example.com' port='10810'/> + </source> + <target dev='vdg' bus='virtio'/> + </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='nbd' name='bar'> + <host transport='unix' socket='/var/run/nbdsock'/> + </source> + <target dev='vdh' bus='virtio'/> + </disk> </devices> ... -- 2.28.0
Signed-off-by: Han Han <hhan@redhat.com> --- docs/formatdomain.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 49713a12d4..73ca4e009f 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -2518,8 +2518,11 @@ paravirtualized driver is specified via the ``disk`` element. For "nbd", the ``name`` attribute is optional. TLS transport for NBD can be enabled by setting the ``tls`` attribute to ``yes``. For the QEMU hypervisor, usage of a TLS environment can also be globally controlled on - the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` in - /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` ) + the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` + ('tls' :since:`Since 4.5.0` ), and the ``nbd_tls_x509_secret_uuid`` to + use a secret to store the passphrase for TLS client + ( :since:`Since 6.6.0` ). All these nbd configurations for QEMU is in + /etc/libvirt/qemu.conf . For protocols ``http`` and ``https`` an optional attribute ``query`` specifies the query string. ( :since:`Since 6.2.0` ) -- 2.28.0
On Wed, Sep 16, 2020 at 13:49:27 +0800, Han Han wrote:
Signed-off-by: Han Han <hhan@redhat.com> --- docs/formatdomain.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 49713a12d4..73ca4e009f 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -2518,8 +2518,11 @@ paravirtualized driver is specified via the ``disk`` element. For "nbd", the ``name`` attribute is optional. TLS transport for NBD can be enabled by setting the ``tls`` attribute to ``yes``. For the QEMU hypervisor, usage of a TLS environment can also be globally controlled on - the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` in - /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` ) + the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` + ('tls' :since:`Since 4.5.0` ), and the ``nbd_tls_x509_secret_uuid`` to + use a secret to store the passphrase for TLS client + ( :since:`Since 6.6.0` ). All these nbd configurations for QEMU is in + /etc/libvirt/qemu.conf .
I must say I'm not particularly a fan of mentioning qemu.conf options at all in the XML docs. We do have it there at this point. I'd vote for getting rid of it but let's leave some space to discuss it.
On Wed, Sep 16, 2020 at 3:12 PM Peter Krempa <pkrempa@redhat.com> wrote:
On Wed, Sep 16, 2020 at 13:49:27 +0800, Han Han wrote:
Signed-off-by: Han Han <hhan@redhat.com> --- docs/formatdomain.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 49713a12d4..73ca4e009f 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -2518,8 +2518,11 @@ paravirtualized driver is specified via the ``disk`` element. For "nbd", the ``name`` attribute is optional. TLS transport for NBD can be enabled by setting the ``tls`` attribute to ``yes``. For the QEMU hypervisor, usage of a TLS environment can also be globally controlled on - the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` in - /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` ) + the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` + ('tls' :since:`Since 4.5.0` ), and the ``nbd_tls_x509_secret_uuid`` to + use a secret to store the passphrase for TLS client + ( :since:`Since 6.6.0` ). All these nbd configurations for QEMU is in + /etc/libvirt/qemu.conf .
I must say I'm not particularly a fan of mentioning qemu.conf options at all in the XML docs.
yeah. formatdomain doc is very long now and adding the options of qemu.conf will make it more complex. Maybe we can consider put the **nbd_tls_x509_secret_uuid** to another doc, for example a detailed disk environment setup doc in kbase
We do have it there at this point. I'd vote for getting rid of it but let's leave some space to discuss it.
-- Best regards, ----------------------------------- Han Han Senior Quality Engineer Redhat. Email: hhan@redhat.com Phone: +861065339333
On Wed, Sep 16, 2020 at 09:12:34AM +0200, Peter Krempa wrote:
On Wed, Sep 16, 2020 at 13:49:27 +0800, Han Han wrote:
Signed-off-by: Han Han <hhan@redhat.com> --- docs/formatdomain.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 49713a12d4..73ca4e009f 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -2518,8 +2518,11 @@ paravirtualized driver is specified via the ``disk`` element. For "nbd", the ``name`` attribute is optional. TLS transport for NBD can be enabled by setting the ``tls`` attribute to ``yes``. For the QEMU hypervisor, usage of a TLS environment can also be globally controlled on - the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` in - /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` ) + the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` + ('tls' :since:`Since 4.5.0` ), and the ``nbd_tls_x509_secret_uuid`` to + use a secret to store the passphrase for TLS client + ( :since:`Since 6.6.0` ). All these nbd configurations for QEMU is in + /etc/libvirt/qemu.conf .
I must say I'm not particularly a fan of mentioning qemu.conf options at all in the XML docs.
We do have it there at this point. I'd vote for getting rid of it but let's leave some space to discuss it.
Yeah, the formatdomain.rst is supposed to be talking about the standard XML schema which is hypervisor agnostic. It is not the place to start talking about QEMU driver specific host level config options. Also TLS is a pretty complex topic, covering multiple different aspects. It is not a good fit for the formatdomain.rst which is really a reference documenting each option in isolation. Really this points strongly towards the need for for kbase file that talks about TLS setup for QEMU devices as a general topic. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
Peter, could you please review and merge this patch first? It is actually independent from the 2/2 rejected patch. On Wed, Sep 16, 2020 at 1:49 PM Han Han <hhan@redhat.com> wrote:
Signed-off-by: Han Han <hhan@redhat.com> --- docs/formatdomain.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 18e237c157..49713a12d4 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -2409,6 +2409,27 @@ paravirtualized driver is specified via the ``disk`` element. </source> <target dev='vde' bus='virtio'/> </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='nbd' tls='yes'> + <host name='example.com' port='10809'/> + </source> + <target dev='vdf' bus='virtio'/> + </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='nbd' name='bar' tls='no'> + <host name='example.com' port='10810'/> + </source> + <target dev='vdg' bus='virtio'/> + </disk> + <disk type='network' device='disk'> + <driver name='qemu' type='raw'/> + <source protocol='nbd' name='bar'> + <host transport='unix' socket='/var/run/nbdsock'/> + </source> + <target dev='vdh' bus='virtio'/> + </disk> </devices> ...
-- 2.28.0
participants (3)
-
Daniel P. Berrangé -
Han Han -
Peter Krempa