External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 13:45:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: uri: Rewrite section about transport protocols and extra parameters

Browse Source 
Avoid the table and add a brief description of the transport protocol.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This commit is contained in:
Peter Krempa 2022-04-20 18:04:36 +02:00
parent e40645c105
commit d30be2cf25
1 changed files with 228 additions and 246 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

474
docs/uri.rst
View File

@ -168,8 +168,11 @@ Some examples:
— Connect to a remote host using a ssh connection with the libssh driver and — Connect to a remote host using a ssh connection with the libssh driver and
use a different known_hosts file. use a different known_hosts file.
Extra parameters Transport configuration
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
The remote driver supports multiple transport protocols and approaches which are
configurable via the URI.
Extra parameters can be added to remote URIs as part of the query string (the Extra parameters can be added to remote URIs as part of the query string (the
part following ``?``). Remote URIs understand the extra parameters shown part following ``?``). Remote URIs understand the extra parameters shown
@ -177,247 +180,226 @@ below. Any others are passed unmodified through to the back end. Note that
parameter values must be parameter values must be
`URI-escaped <http://xmlsoft.org/html/libxml-uri.html#xmlURIEscapeStr>`__. `URI-escaped <http://xmlsoft.org/html/libxml-uri.html#xmlURIEscapeStr>`__.
+-------------------------+-------------------------+-------------------------+ All transports support the following parameters:
| Name | Transports | Meaning |
+=========================+=========================+=========================+ ``name``
| ``name`` | *any transport* | The name passed to the |
| | | remote virConnectOpen | The name passed to the remote ``virConnectOpen`` function. The name is
| | | function. The name is | normally formed by removing transport, hostname, port number, username and
| | | normally formed by | extra parameters from the remote URI, but in certain very complex cases it
| | | removing transport, | may be better to supply the name explicitly.
| | | hostname, port number, |
| | | username and extra | **Example:** ``name=qemu:///system``
| | | parameters from the |
| | | remote URI, but in | ``ssh`` transport
| | | certain very complex | ^^^^^^^^^^^^^^^^^
| | | cases it may be better |
| | | to supply the name | The ``ssh`` transport uses the standard SSH protocol via the system installed
| | | explicitly. | binary.
+-------------------------+-------------------------+-------------------------+
| | | Example: | Supported extra parameters:
| | | ``name=qemu:///system`` |
+-------------------------+-------------------------+-------------------------+ ``mode``
| ``tls_priority`` | tls | A valid GNUTLS priority | See the info on the `mode parameter`_.
| | | string | ``proxy``
+-------------------------+-------------------------+-------------------------+ See the info on the `proxy parameter`_.
| | | Example: | ``command``
| | | ``tls_priorit | Path to the ``ssh`` binary to use.
| | | y=NORMAL:-VERS-SSL3.0`` |
+-------------------------+-------------------------+-------------------------+ **Example:** ``command=/opt/openssh/bin/ssh``
| ``mode`` | unix, ssh, libssh, | ``auto`` | ``socket``
| | libssh2 | automatically | See the info on the `socket parameter`_.
| | | determine the daemon | ``netcat``
| | | ``direct`` | See the info on the `netcat parameter`_.
| | | connect to | ``keyfile``
| | | per-driver daemons | See the info on the `keyfile parameter`_.
| | | ``legacy`` | ``no_verify``
| | | connect to libvirtd | If set to a non-zero value, this disables client's strict host key checking
| | | | making it auto-accept new host keys. Existing host keys will still be
| | | Can also be set in | validated.
| | | ``libvirt.conf`` as |
| | | ``remote_mode`` | **Example:** ``no_verify=1``
+-------------------------+-------------------------+-------------------------+ ``no_tty``
| | | Example: | If set to a non-zero value, this stops ssh from asking for a password if it
| | | ``mode=direct`` | cannot log in to the remote machine automatically (eg. using ssh-agent
+-------------------------+-------------------------+-------------------------+ etc.). Use this when you don't have access to a terminal - for example in
| ``proxy`` | auto, netcat, native | ``auto`` | graphical programs which use libvirt.
| | | try native, fallback |
| | | to netcat | **Example:** ``no_tty=1``
| | | ``netcat`` |
| | | only use netcat | ``libssh`` and ``libssh2`` transport
| | | ``native`` | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| | | only use native |
| | | | Same as the ``ssh`` transport but the SSH client is handled directly by using
| | | Can also be set in | either ``libssh`` or ``libssh2`` to handle the SSH protocol without spawning an
| | | ``libvirt.conf`` as | extra process.
| | | ``remote_proxy`` |
+-------------------------+-------------------------+-------------------------+ Supported extra parameters:
| | | Example: |
| | | ``proxy=native`` | ``mode``
+-------------------------+-------------------------+-------------------------+ See the info on the `mode parameter`_.
| ``command`` | ssh, ext | The external command. | ``proxy``
| | | For ext transport this | See the info on the `proxy parameter`_.
| | | is required. For ssh | ``socket``
| | | the default is ``ssh``. | See the info on the `socket parameter`_.
| | | The PATH is searched | ``netcat``
| | | for the command. | See the info on the `netcat parameter`_.
+-------------------------+-------------------------+-------------------------+ ``keyfile``
| | | Example: | See the info on the `keyfile parameter`_.
| | | ``command | ``known_hosts``
| | | =/opt/openssh/bin/ssh`` | Path to the known_hosts file to verify the host key against. LibSSH2 and
+-------------------------+-------------------------+-------------------------+ libssh support OpenSSH-style known_hosts files, although LibSSH2 does not
| ``socket`` | unix, ssh, libssh2, | The path to the Unix | support all key types, so using files created by the OpenSSH binary may
| | libssh | domain socket, which | result into truncating the known_hosts file. Thus, with LibSSH2 it's
| | | overrides the | recommended to use the default known_hosts file is located in libvirt's
| | | compiled-in default. | client local configuration directory e.g.: ~/.conf ig/libvirt/known_hosts.
| | | For ssh transport, this |
| | | is passed to the remote | *Note:* Use absolute paths.
| | | netcat command (see |
| | | next). | **Example:** ``known_hosts=/root/.ssh/known_hosts``
+-------------------------+-------------------------+-------------------------+
| | | Example: | ``known_hosts_verify``
| | | `` | If set to ``normal`` (default), then the user will be asked to accept new
| | | socket=/opt/libvirt/run | host keys. If set to ``auto``, new host keys will be auto-accepted, but
| | | /libvirt/libvirt-sock`` | existing host keys will still be validated. If set to ``ignore``, this
+-------------------------+-------------------------+-------------------------+ disables client's strict host key checking.
| ``netcat`` | ssh, libssh2, libssh | The name of the netcat |
| | | command on the remote | **Example:** ``known_hosts_verify=ignore``
| | | machine. The default is |
| | | ``nc``. This is not | ``sshauth``
| | | permitted when using | A comma separated list of authentication methods to use. Default (is
| | | the ``native`` proxy | "agent,privkey,password ,keyboard-interactive". The order of the methods
| | | mode. For ssh | is preserved. Some methods may require additional parameters.
| | | transport, libvirt |
| | | constructs an ssh | **Example:** ``sshauth=privkey,agent``
| | | command which looks |
| | | like: | ``tls`` transport
| | | | ^^^^^^^^^^^^^^^^^
| | | ``command -p port`` |
| | | ``[-l username]`` | This transport uses a TCP connection to the socket. The data is encrypted using
| | | ``hostname`` or | TLS to ensure security. Note that TLS certificates must be setup for this to
| | | | work.
| | | ``netcat -U socket`` |
| | | | Supported extra parameters:
| | | where *port*, |
| | | *username*, *hostname* | ``tls_priority``
| | | can be specified as | A valid GNUTLS priority string.
| | | part of the remote URI, |
| | | and *command*, *netcat* | **Example:** ``tls_priority=NORMAL:-VERS-SSL3.0``
| | | and *socket* come from |
| | | extra parameters (or | ``no_verify``
| | | sensible defaults). | If set to a non-zero value, this disables client checks of the server's
+-------------------------+-------------------------+-------------------------+ certificate. Note that to disable server checks of the client's certificate
| | | Example: | or IP address you must `change the libvirtd configuration
| | | ``netc | <#Remote_libvirtd_configuration>`__
| | | at=/opt/netcat/bin/nc`` |
+-------------------------+-------------------------+-------------------------+ **Example:** ``no_verify=1``
| ``keyfile`` | ssh, libssh2, libssh | The name of the private |
| | | key file to use to | ``pkipath``
| | | authentication to the |
| | | remote machine. If this | Specifies x509 certificates path for the client. If any of the CA
| | | option is not used the | certificate, client certificate, or client key is missing, the connection
| | | default keys are used. | will fail with a fatal error.
+-------------------------+-------------------------+-------------------------+
| | | Example: | **Example:** ``pkipath=/tmp/pki/client``
| | | ``keyfile=/ |
| | | root/.ssh/example_key`` | ``unix`` transport
+-------------------------+-------------------------+-------------------------+ ^^^^^^^^^^^^^^^^^^
| ``no_verify`` | ssh, tls | SSH: If set to a |
| | | non-zero value, this | This transport uses an unix domain socket is used to connect to the daemon.
| | | disables client's | This is the most common case. In most cases no extra parameters are needed.
| | | strict host key |
| | | checking making it | Supported extra parameters:
| | | auto-accept new host |
| | | keys. Existing host | ``mode``
| | | keys will still be | See the info on the `mode parameter`_.
| | | validated. | ``socket``
| | | TLS: If set to a | See the info on the `socket parameter`_.
| | | non-zero value, this |
| | | disables client checks | ``ext`` transport
| | | of the server's | ^^^^^^^^^^^^^^^^^
| | | certificate. Note that |
| | | to disable server | The ``ext`` transport invokes the user specified command to transport the
| | | checks of the client's | libvirt RPC protocol to the destination. The command must be able to handle
| | | certificate or IP | the proper connection. Standard input/output is used for the communication.
| | | address you must |
| | | `change the libvirtd | Supported extra parameters:
| | | conf |
| | | iguration <#Remote_libv | ``command``
| | | irtd_configuration>`__. | The external command launched to tunnel the data to the destination.
+-------------------------+-------------------------+-------------------------+
| | | Example: | ``tcp`` transport
| | | ``no_verify=1`` | ^^^^^^^^^^^^^^^^^
+-------------------------+-------------------------+-------------------------+
| ``no_tty`` | ssh | If set to a non-zero | The ``tcp`` transport uses plain unencrypted TCP connection to libvirt. This
| | | value, this stops ssh | is insecure and should not be used. This transport has no additional arguments.
| | | from asking for a |
| | | password if it cannot | Common extra parameters
| | | log in to the remote | ~~~~~~~~~~~~~~~~~~~~~~~
| | | machine automatically |
| | | (eg. using ssh-agent | Certain extra parameters are shared between multiple protocols. See the list of
| | | etc.). Use this when | transport protocols above for specific usage.
| | | you don't have access |
| | | to a terminal - for | ``mode`` parameter
| | | example in graphical | ^^^^^^^^^^^^^^^^^^
| | | programs which use |
| | | libvirt. | Controls whether to connect to per-driver daemons or libvirtd.
+-------------------------+-------------------------+-------------------------+
| | | Example: ``no_tty=1`` | Supported values:
+-------------------------+-------------------------+-------------------------+
| ``pkipath`` | tls | Specifies x509 | ``auto``
| | | certificates path for | automatically determine the daemon
| | | the client. If any of | ``direct``
| | | the CA certificate, | connect to per-driver daemons
| | | client certificate, or | ``legacy``
| | | client key is missing, | connect to libvirtd
| | | the connection will |
| | | fail with a fatal | Default is ``auto``. Can also be set in ``libvirt.conf`` as ``remote_mode``.
| | | error. |
+-------------------------+-------------------------+-------------------------+ **Example:** ``mode=direct``
| | | Example: |
| | | ``pk | ``proxy`` parameter
| | | ipath=/tmp/pki/client`` | ^^^^^^^^^^^^^^^^^^^
+-------------------------+-------------------------+-------------------------+
| ``known_hosts`` | libssh2, libssh | Path to the known_hosts | Controls which proxy binary is used on the remote side of connection to connect
| | | file to verify the host | to the daemon.
| | | key against. LibSSH2 |
| | | and libssh support | Supported values:
| | | OpenSSH-style |
| | | known_hosts files, | ``auto``
| | | although LibSSH2 does | try native, fallback to netcat
| | | not support all key | ``netcat``
| | | types, so using files | only use netcat
| | | created by the OpenSSH | ``native``
| | | binary may result into | use the libvirt native proxy binary
| | | truncating the |
| | | known_hosts file. Thus, | Default is ``auto``. Can also be set in ``libvirt.conf`` as ``remote_proxy``.
| | | with LibSSH2 it's |
| | | recommended to use the | **Example:** ``proxy=native``
| | | default known_hosts |
| | | file is located in | ``socket`` parameter
| | | libvirt's client local | ^^^^^^^^^^^^^^^^^^^^
| | | configuration directory |
| | | e.g.: | The path to the Unix domain socket, which overrides the compiled-in default.
| | | ~/.conf | This may be passed to the remote proxy command (See. `proxy parameter`).
| | | ig/libvirt/known_hosts. |
| | | Note: Use absolute | **Example:** ``socket=/opt/libvirt/run/libvirt/libvirt-sock``
| | | paths. |
+-------------------------+-------------------------+-------------------------+ ``netcat`` parameter
| | | Example: | ^^^^^^^^^^^^^^^^^^^^
| | | ``known_hosts=/ | The name of the netcat command on the remote machine. The default is ``nc``.
| | | root/.ssh/known_hosts`` | This is not permitted when using the ``native`` proxy mode.
+-------------------------+-------------------------+-------------------------+
| ``known_hosts_verify`` | libssh2, libssh | If set to ``normal`` | The command used here is used on the remote side of the connection as:
| | | (default), then the |
| | | user will be asked to | ``netcat -U socket``
| | | accept new host keys. |
| | | If set to ``auto``, new | **Example:** ``netcat=/opt/netcat/bin/nc``
| | | host keys will be |
| | | auto-accepted, but | ``keyfile`` parameter
| | | existing host keys will | ^^^^^^^^^^^^^^^^^^^^^
| | | still be validated. If |
| | | set to ``ignore``, this | The name of the private key file to use to authentication to the remote
| | | disables client's | machine. If this option is not used the default keys are used.
| | | strict host key |
| | | checking. | **Example:** ``keyfile=/root/.ssh/example_key``
+-------------------------+-------------------------+-------------------------+
| | | Example: |
| | | ``know |
| | | n_hosts_verify=ignore`` |
+-------------------------+-------------------------+-------------------------+
| ``sshauth`` | libssh2, libssh | A comma separated list |
| | | of authentication |
| | | methods to use. Default |
| | | (is |
| | | "agent,privkey,password |
| | | ,keyboard-interactive". |
| | | The order of the |
| | | methods is preserved. |
| | | Some methods may |
| | | require additional |
| | | parameters. |
+-------------------------+-------------------------+-------------------------+
| | | Example: |
| | | `` |
| | | sshauth=privkey,agent`` |
+-------------------------+-------------------------+-------------------------+