diff --git a/docs/remote.html.in b/docs/remote.html.in index 5a0ebe4790..0b0dc87f6f 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -34,7 +34,7 @@ the system-wide QEMU daemon on a remote machine called qemu://compute1.libvirt.org/system.

-The section on remote URIs +The section on remote URIs describes in more detail these remote URIs.

@@ -109,279 +109,9 @@ even with graphical management applications. As with the classic ssh transport netcat is required on the remote side.

-The default transport, if no other is specified, is tls. -

-

- Remote URIs -

-

-See also: documentation on ordinary ("local") URIs. -

-

-Remote URIs have the general form ("[...]" meaning an optional part): -

-

driver[+transport]://[username@][hostname][:port]/[path][?extraparameters] -

-

-Either the transport or the hostname must be given in order -to distinguish this from a local URI. -

-

-Some examples: -

- -

- Extra parameters -

-

-Extra parameters can be added to remote URIs as part -of the query string (the part following ?). -Remote URIs understand the extra parameters shown below. -Any others are passed unmodified through to the back end. -Note that parameter values must be -URI-escaped. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name Transports Meaning
- name - - any transport - - The name passed to the remote virConnectOpen function. The - name is normally formed by removing transport, hostname, port - number, username and extra parameters from the remote URI, but in certain - very complex cases it may be better to supply the name explicitly. -
- Example: name=qemu:///system
- tls_priority - tls - A vaid GNUTLS priority string -
- Example: tls_priority=NORMAL:-VERS-SSL3.0
- mode - unix, ssh, libssh, libssh2 -
-
auto
automatically determine the daemon
-
direct
connect to per-driver daemons
-
legacy
connect to libvirtd
-
- Can also be set in libvirt.conf as remote_mode -
- Example: mode=direct
- command - ssh, ext - The external command. For ext transport this is required. - For ssh the default is ssh. - The PATH is searched for the command. -
- Example: command=/opt/openssh/bin/ssh
- socket - unix, ssh, libssh2, libssh - The path to the Unix domain socket, which overrides the - compiled-in default. For ssh transport, this is passed to - the remote netcat command (see next). -
- Example: socket=/opt/libvirt/run/libvirt/libvirt-sock
- netcat - ssh, libssh2, libssh - The name of the netcat command on the remote machine. - The default is nc. For ssh transport, libvirt - constructs an ssh command which looks like: - -
command -p port [-l username] hostname netcat -U socket
-
- - where port, username, hostname can be - specified as part of the remote URI, and command, netcat - and socket come from extra parameters (or - sensible defaults). - -
- Example: netcat=/opt/netcat/bin/nc
- keyfile - ssh, libssh2, libssh - The name of the private key file to use to authentication to the remote - machine. If this option is not used the default keys are used. -
- Example: keyfile=/root/.ssh/example_key
- no_verify - ssh, tls - SSH: 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 validated. -
-
- TLS: 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 or IP address you must - change the libvirtd - configuration. -
- Example: no_verify=1
- no_tty - ssh - If set to a non-zero value, this stops ssh from asking for - a password if it 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 graphical programs which use libvirt. -
- Example: no_tty=1
- pkipath - tls - Specifies x509 certificates path for the client. If any of - the CA certificate, client certificate, or client key is - missing, the connection will fail with a fatal error. -
- Example: pkipath=/tmp/pki/client
- known_hosts - libssh2, libssh - 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 - support all key types, so using files created by the OpenSSH binary may - result into truncating the known_hosts file. Thus, with LibSSH2 it's - recommended to use the default known_hosts file is located in libvirt's - client local configuration directory e.g.: ~/.config/libvirt/known_hosts. - Note: Use absolute paths. -
- Example: known_hosts=/root/.ssh/known_hosts
- 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
+ The choice of transport is determined by the URI scheme, + with tls as the default if no explicit transport is requested. +

libvirtd configuration file

diff --git a/docs/uri.html.in b/docs/uri.html.in index 6da9eb9746..49f92773f8 100644 --- a/docs/uri.html.in +++ b/docs/uri.html.in @@ -153,65 +153,270 @@ here. Remote URIs

-Remote URIs are formed by taking ordinary local URIs and adding a -hostname and/or transport name. As a special case, using a URI -scheme of 'remote', will tell the remote libvirtd server to probe -for the optimal hypervisor driver. This is equivalent to passing -a NULL URI for a local connection. For example: +Remote URIs have the general form ("[...]" meaning an optional part): +

+

driver[+transport]://[username@][hostname][:port]/[path][?extraparameters] +

+

+Either the transport or the hostname must be given in order +to distinguish this from a local URI. +

+

+Some examples: +

+ +

+ Extra parameters +

+

+Extra parameters can be added to remote URIs as part +of the query string (the part following ?). +Remote URIs understand the extra parameters shown below. +Any others are passed unmodified through to the back end. +Note that parameter values must be +URI-escaped.

- - + + - + + + + + - + A vaid GNUTLS priority string + + + + + - + + + + + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Local URI Remote URI Name Transports Meaning
- xen:///system + name - xen://oirase/system + any transport Connect to the Xen hypervisor running on host oirase - using TLS. + The name passed to the remote virConnectOpen function. The + name is normally formed by removing transport, hostname, port + number, username and extra parameters from the remote URI, but in certain + very complex cases it may be better to supply the name explicitly. +
+ Example: name=qemu:///system
- NULL + tls_priority tls - remote://oirase/ - Connect to the "default" hypervisor running on host oirase - using TLS.
+ Example: tls_priority=NORMAL:-VERS-SSL3.0
- xen:///system + mode unix, ssh, libssh, libssh2 - xen+ssh://oirase/system +
+
auto
automatically determine the daemon
+
direct
connect to per-driver daemons
+
legacy
connect to libvirtd
+
+ Can also be set in libvirt.conf as remote_mode 		Connect to the Xen hypervisor running on host oirase - by going over an ssh connection.
+ Example: mode=direct
- test:///default + command ssh, ext - test+tcp://oirase/default + The external command. For ext transport this is required. + For ssh the default is ssh. + The PATH is searched for the command. +
+ Example: command=/opt/openssh/bin/ssh
+ socket Connect to the test driver on host oirase - using an unsecured TCP connection. unix, ssh, libssh2, libssh + The path to the Unix domain socket, which overrides the + compiled-in default. For ssh transport, this is passed to + the remote netcat command (see next). +
+ Example: socket=/opt/libvirt/run/libvirt/libvirt-sock
+ netcat + ssh, libssh2, libssh + The name of the netcat command on the remote machine. + The default is nc. For ssh transport, libvirt + constructs an ssh command which looks like: + +
command -p port [-l username] hostname netcat -U socket
+
+ + where port, username, hostname can be + specified as part of the remote URI, and command, netcat + and socket come from extra parameters (or + sensible defaults). + +
+ Example: netcat=/opt/netcat/bin/nc
+ keyfile + ssh, libssh2, libssh + The name of the private key file to use to authentication to the remote + machine. If this option is not used the default keys are used. +
+ Example: keyfile=/root/.ssh/example_key
+ no_verify + ssh, tls + SSH: 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 validated. +
+
+ TLS: 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 or IP address you must + change the libvirtd + configuration. +
+ Example: no_verify=1
+ no_tty + ssh + If set to a non-zero value, this stops ssh from asking for + a password if it 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 graphical programs which use libvirt. +
+ Example: no_tty=1
+ pkipath + tls + Specifies x509 certificates path for the client. If any of + the CA certificate, client certificate, or client key is + missing, the connection will fail with a fatal error. +
+ Example: pkipath=/tmp/pki/client
+ known_hosts + libssh2, libssh + 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 + support all key types, so using files created by the OpenSSH binary may + result into truncating the known_hosts file. Thus, with LibSSH2 it's + recommended to use the default known_hosts file is located in libvirt's + client local configuration directory e.g.: ~/.config/libvirt/known_hosts. + Note: Use absolute paths. +
+ Example: known_hosts=/root/.ssh/known_hosts
+ 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
-

-Remote URIs in libvirt offer a rich syntax and many features. -We refer you to the libvirt -remote URI reference and full documentation -for libvirt remote support. -

test:///... Test URIs