Chapter 7. Connecting and Authorizing

Chapter 7. Connecting and Authorizing¶

Contents

7.1. Authentication
7.2. Configuring Remote Connections
7.3. Connecting to a VM Host Server

Having to manage several VM Host Servers, each hosting a couple of VM Guests, quickly becomes difficult to handle. One of the major benefits of libvirt is the ability to connect to several VM Host Servers at once, providing a single interface to manage all VM Guests and to connect to their graphical console.

In order to ensure only authorized users can connect, libvirt offers several connection types that can be combined with different authorization mechanisms.

7.1. Authentication¶

The power to manage VM Guests and to access their graphical console obviously is something that should be restricted to a well defined circle of persons. In order to achieve this goal, you can use the following authentication techniques on the VM Host Server:

Access control for UNIX sockets with permissions and group ownership. This method is available for libvirtd connections only.
Access control for UNIX sockets with PolicyKit. This method is available for local libvirtd connections only.
Username and password authentication with SASL (Simple Authentication and Security Layer). This method is available for both, libvirtd and VNC connections. Using SASL does not require real user accounts on the server, since it uses its own database to store usernames and passwords.
Kerberos authentication. This method, available for libvirtd connections only, is not covered in this manual. Please refer to http://libvirt.org/auth.html#ACL_server_kerberos for details.
Single password authentication. This method is available for VNC connections only.

	Authentication for `libvirtd` and VNC need to be configured separately
Access to the VM Guest management functions (via `libvirtd`) on the one hand and to their graphical console on the other hand, always needs to be configured separately. When restricting the access to the management tools, these restrictions do not automatically apply to VNC connections!

When accessing VM Guests from remote via TLS/SSL connections, access can be indirectly controlled on each client by restricting read permissions to the certificate's key file to a certain group. See Section 7.2.2.5, “Restricting Access (Security Considerations)” for details.

7.1.1. `libvirtd` Authentication¶

libvirtd authentication is configured in /etc/libvirt/libvirtd.conf. The configuration made here applies to all libvirt tools such as the Virtual Machine Manager or virsh.

libvirt offers two sockets: a read-only socket for monitoring purposes and a read-write socket to be used for management operations. Access to both sockets can be configured independently. By default, both sockets are owned by root.root. Default access permissions on the read-write socket are restricted to the user root (0700) and fully open on the read-only socket (0777).

In the following instructions you learn how to configure access permissions for the read-write socket. The same instructions also apply to the read-only socket. All configuration steps have to be carried out on the VM Host Server.

	Default Authentication Settings on openSUSE
The default authorization method on openSUSE is access control for UNIX sockets with PolicyKit. Every user accessing the read-write socket, has to provide the `root` password once and is granted access for the current and for future sessions.

Recommended Authorization Methods

Local Connections

Section 7.1.1.2, “Access Control for UNIX Sockets with PolicyKit”

Section 7.1.1.1, “Access Control for UNIX Sockets with Permissions and Group Ownership”

Remote Tunnel over SSH

Section 7.1.1.1, “Access Control for UNIX Sockets with Permissions and Group Ownership”

Remote TLS/SSL Connection

Section 7.1.1.3, “Username and Password Authentication with SASL”

none (access controlled on the client side by restricting access to the certificates)

7.1.1.1. Access Control for UNIX Sockets with Permissions and Group Ownership¶

In order to grant access for non-root accounts, configure the sockets to be owned and accessible by a certain group (libvirt in the following example). This authentication method can be used for local and remote SSH connections.

In case it does not exist, create the group which should own the socket:
```
groupadd libvirt
```
Group Needs to Exist
The group must exist prior to restarting libvirtd. If not, the restart will fail.
Add the desired users to the group:
```
usermod -A libvirt tux
```

	Group Needs to Exist
The group must exist prior to restarting `libvirtd`. If not, the restart will fail.

Change the configuration in /etc/libvirt/libvirtd.conf as follows:

       unix_sock_group = "libvirt"
       unix_sock_rw_perms = "0770"
       auth_unix_rw = "none"

	Group ownership will be set to group `libvirt`.
	Sets the access permissions for the socket (srwxrwx---).
	Disables other authentication methods (PolicyKit or SASL). Access is solely controlled by the socket permissions.

Restart libvirtd:
```
rclibvirtd restart
```

7.1.1.2. Access Control for UNIX Sockets with PolicyKit¶

Access control for UNIX sockets with PolicyKit is the default authentication method on openSUSE. Therefore, no libvirt configuration changes are needed. With PolicyKit authorization enabled, permissions on both sockets default to 0777 and each application trying to access a socket needs to authenticate via PolicyKit. openSUSE currently supports this method for local connections only.

Two policies for accessing libvirt's sockets exist:

org.libvirt.unix.monitor: accessing the read-only socket
org.libvirt.unix.manage: accessing the read-write socket

By default, the policy for accessing the read-write socket is to authenticate with root password once and grant the privilege for the current and for future sessions (auth_admin_keep_always).

In order to grant users access to the read-write socket without having to provide the root password, there are two possibilities:

Using the polkit-auth command, you can grant the privilege without any restrictions:

polkit-auth --user tux --grant org.libvirt.unix.manage    # grant privilege
polkit-auth --user tux --revoke org.libvirt.unix.manage   # revoke privilege

Editing /etc/PolicyKit/PolicyKit.conf offers more advanced options. Add the following XML snippet in between the existing <config version="0.1"> and </config> tags:

<match action="org.libvirt.unix.manage">
  <match user="tux">
    <return result="yes"/>
  </match>
</match>

	The name of the policy; `org.libvirt.unix.manage` stands for accessing the read-write socket.
	The username(s) which to grant the privilege. Use the `\|` symbol to separate entries (`user="tux\|wilber"`).
	The privilege that is granted. The following options exist: `yes` (no restrictions), `no` (block access completely), `auth_self` or `auth_admin` (authenticate with own password/`root` password every time the privilege is requested), `auth_self_keep_session` or `auth_admin_keep_session` (authenticate with own password/`root` password once per session) and `auth_self_keep_always` or `auth_admin_keep_always` (authenticate only once with own password/`root` password).

7.1.1.3. Username and Password Authentication with SASL¶

SASL provides username and password authentication as well as data encryption (digest-md5, by default). Since SASL maintains its own user database, the users do not need to exist on the VM Host Server. SASL is required by TCP connections and on top of TLS/SSL connections.

	Plain TCP and SASL with digest-md5 Encryption
Using digest-md5 encryption on an otherwise unencrypted TCP connection does not provide enough security for production environments. It is recommended to only use it in testing environments.

	SASL Authentication on Top of TLS/SSL
Access from remote TLS/SSL connections can be indirectly controlled on the client side by restricting access to the certificate's key file. However, this might prove error-prone when dealing with a large number of clients. Utilizing SASL with TLS adds security by additionally controlling access on the server side.

To configure SASL authentication, proceed as follows:

Change the configuration in /etc/libvirt/libvirtd.conf as follows:
1. To enable SASL for TCP connections:
```
auth_tcp = "sasl"
```
2. To enable SASL for TLS/SSL connections:
```
auth_tls = "sasl"
```
Restart libvirtd:
```
rclibvirtd restart
```
The libvirt SASL configuration file is located at /etc/sasl2/libvirtd.conf. Normally, there is no need to change the defaults. However, if using SASL on top of TLS, you may turn off session encryption to avoid additional overhead— TLS connections are already encrypted— by commenting the mech_list. For TCP connections this parameter must be set to digest-md5:
```
mech_list: digest-md5   # mandatory for TCP connections
#mech_list: digest-md5   # apply default (username+password) TLS/SSL only!
```

By default, no SASL users are configured, so no logins are possible. Use the following commands to add, list, and delete users:

mercury:~ # saslpasswd2 -a libvirt tux                  # add user tux
Password: 
Again (for verification): 
mercury:~ # sasldblistusers2 -f /etc/libvirt/passwd.db  # list users
tux@mercury.example.com: userPassword
mercury:~ # saslpasswd2 -a libvirt -d tux               # delete user tux

	virsh and SASL Authentication
When using SASL authentication you will be prompted for a username and password every time you issue a virsh command. Avoid this by using virsh in shell mode.

7.1.2. VNC Authentication¶

Since access to the graphical console of a VM Guest is not controlled by libvirt, but rather by QEMU, it is always necessary to additionally configure VNC authentication. The main configuration file is /etc/libvirt/qemu.conf.

Two authentication types are available: SASL and single password authentication. If you are using SASL for libvirt authentication, it is strongly recommended to use it for VNC authentication as well—it is possible to share the same database.

A third method to restrict access to the VM Guest is to enable the use of TLS encryption on the VNC server. This requires the VNC clients to have access to x509 client certificates. By restricting access to these certificates, access can indirectly be controlled on the client side. Refer to Section 7.2.2.4.2, “VNC over TLS/SSL: Client Configuration” for details.

7.1.2.1. Username and Password Authentication with SASL¶

SASL provides username and password authentication as well as data encryption. Since SASL maintains its own user database, the users do not need to exist on the VM Host Server. As with SASL authentication for libvirt, you may use SASL on top of TLS/SSL connections. Refer to Section 7.2.2.4.2, “VNC over TLS/SSL: Client Configuration” for details on configuring these connections.

To configure SASL authentication for VNC, proceed as follows:

Create a SASL configuration file. It is recommended to use the existing libvirt file. If you have already configured SASL for libvirt and are planning to use the same settings including the same username/password database, a simple link is suitable:
```
ln -s /etc/sasl2/libvirt.conf /etc/sasl2/qemu.conf
```
In case you are setting up SASL for VNC only or planning to use a different configuration than for libvirt, copy the existing file to use as a template and edit it according to your needs:
```
cp /etc/sasl2/libvirt.conf /etc/sasl2/qemu.conf
```

By default, no SASL users are configured, so no logins are possible. Use the following commands to add, list, and delete users:

mercury:~ # saslpasswd2 -a libvirt tux                  # add user tux
Password: 
Again (for verification): 
mercury:~ # sasldblistusers2 -f /etc/libvirt/passwd.db  # list users
tux@mercury.example.com: userPassword
mercury:~ # saslpasswd2 -a libvirt -d tux               # delete user tux

Change the configuration in /etc/libvirt/qemu.conf as follows:
```
vnc_listen = "0.0.0.0"
vnc_sasl = 1
```
The first parameter enables VNC to listen on all public interfaces (rather than to the local host only), and the second parameter enables SASL authentication.
Restart libvirtd:
```
rclibvirtd restart
```
Restart all VM Guests that have been running prior to changing the configuration. VM Guests that have not been restarted will not use SASL authentication for VNC connects.

	Supported VNC Viewers
Currently only the same VNC viewers that also support TLS/SSL connections, support SASL authentication, namely Virtual Machine Manager, virt-viewer, and vinagre.

7.1.2.2. Single Password Authentication¶

Access to the VNC server may also be controlled by setting a VNC password. You can either set a global password for all VM Guests or set individual passwords for each guest. The latter requires to edit the VM Guest's config files.

	Always Set a Global Password
If you are using the single password authentication, it is good practice to set a global password even if setting passwords for each VM Guest. This will always leave your virtual machines protected with a “fallback” password if you forget to set a per-machine password. The global password will only be used if no other password is set for the machine.

Procedure 7.1. Setting a Global VNC Password

Change the configuration in /etc/libvirt/qemu.conf as follows:
```
vnc_listen = "0.0.0.0"
       vnc_password = "PASSWORD"
```
The first parameter enables VNC to listen on all public interfaces (rather than to the local host only), and the second parameter sets the password. The maximum length of the password is eight characters.
Restart libvirtd:
```
rclibvirtd restart
```
Restart all VM Guests that have been running prior to changing the configuration. VM Guests that have not been restarted will not use password authentication for VNC connects.

Procedure 7.2. Setting a VM Guest Specific VNC Password

Change the configuration in /etc/libvirt/qemu.conf as follows to enable VNC to listen on all public interfaces (rather than to the local host only).
```
vnc_listen = "0.0.0.0"
```
Open the VM Guest's XML configuration file in an editor. Replace VM NAME in the following example with the name of the VM Guest. The editor that is used defaults to $EDITOR. If that variable is not set, vi is used.
```
virsh edit VM NAME
```
Search for the element <graphics> with the attribute type='vnc', for example:
```
<graphics type='vnc' port='-1' autoport='yes'/>
```
Add the passwd=PASSWORD attribute, save the file and leave the editor. The maximum length of the password is eight characters.
```
<graphics type='vnc' port='-1' autoport='yes' passwd='PASSWORD'/>
```
Restart libvirtd:
```
rclibvirtd restart
```
Restart all VM Guests that have been running prior to changing the configuration. VM Guests that have not been restarted will not use password authentication for VNC connects.

	Security
The VNC protocol is not considered to be safe. Although the password is sent encrypted, it might be vulnerable, when an attacker is able to sniff both, the encrypted password and the encryption key. Therefore, it is recommended to use VNC with TLS/SSL or tunneled over SSH. virt-viewer, as well as the Virtual Machine Manager and vinagre from version 2.30 on, support both methods.

7.2. Configuring Remote Connections¶

A major benefit of libvirt is the ability to manage VM Guests on different remote hosts from a central location. This section gives detailed instructions on how to configure server and client to allow remote connections.

7.2.1. Remote Tunnel over SSH¶

Enabling a remote connection that is tunneled over SSH on the VM Host Server only requires the ability to accept SSH connections. Make sure the SSH daemon is started (rcsshd status) and that the ports for service SSH are opened in the firewall.

User authentication for SSH connections can be done using traditional file user/group ownership and permissions as described in Section 7.1.1.1, “Access Control for UNIX Sockets with Permissions and Group Ownership”.

7.2.2. Remote TLS/SSL Connection with x509 Certificate¶

Using TCP connections with TLS/SSL encryption and authentication via x509 certificates is much more complicated to set up than SSH, but it is a lot more scalable. Use this method if you have to manage several VM Host Servers with a varying number of administrators.

7.2.2.1. Basic concept¶

Basically, TLS (Transport Layer Security) encrypts the communication between two computers by using certificates. The computer starting the connection is always considered as the “client” using a “client certificate”, while the receiving computer is always considered as the “server”, using a “server certificate”. This scenario applies, for example, if you manage your VM Host Servers from a central desktop.

If connections are initiated from both computers, each needs to have a client and a server certificate. This is the case, for example, if you migrate a VM Guest from one host to another.

Each x509 certificate has a matching private key file. Only the combination of certificate and private key file is able to identify itself correctly. In order to assure that a certificate was issued by the assumed owner, it is signed and issued by a central certificate called certification authority (CA). Both the client and the server certificates must be issued by the same CA.

User Authentication

	User Authentication
Using a remote TLS/SSL connection basically only ensures that two computers are allowed to communicate in a certain direction. Restricting access to certain users can indirectly be achieved on the client side by restricting access to the certificates. Refer to Section 7.2.2.5, “Restricting Access (Security Considerations)” for details. `libvirt` also supports user authentication on the server with SASL. Read more in Section 7.2.2.6, “Central User Authentication with SASL for TLS Sockets”.

Using a remote TLS/SSL connection basically only ensures that two computers are allowed to communicate in a certain direction. Restricting access to certain users can indirectly be achieved on the client side by restricting access to the certificates. Refer to Section 7.2.2.5, “Restricting Access (Security Considerations)” for details. libvirt also supports user authentication on the server with SASL. Read more in Section 7.2.2.6, “Central User Authentication with SASL for TLS Sockets”.

7.2.2.2. Configuring the VM Host Server¶

The VM Host Server is the machine receiving connections. Therefore, the server certificates have to be installed. The CA certificate needs to be installed, as well. Once the certificates are in place, TLS support can be turned on for libvirt.

Create the server certificate and export it together with the CA certificate as described in Section A.2, “Generating x509 Client/Server Certificates”.
Create the following directories on the VM Host Server:
```
mkdir -p /etc/pki/CA/ /etc/pki/libvirt/private/
```
Install the certificates as follows:
```
/etc/pki/CA/cacert.pem
/etc/pki/libvirt/servercert.pem
/etc/pki/libvirt/private/serverkey.pem
```
Restrict Access to Certificates
Make sure to restrict access to certificates as explained in Section 7.2.2.5, “Restricting Access (Security Considerations)”.
Enable TLS support by editing /etc/libvirt/libvirtd.conf and setting listen_tls = 1. Restart libvirtd:
```
rclibvirtd restart
```
By default, libvirt uses the TCP port 16514 for accepting secure TLS connections. Open this port in the firewall.

	Restarting `libvirtd` with TLS enabled
If you enable TLS for `libvirt`, the server certificates need to be in place, otherwise restarting `libvirtd` will fail. You also need to restart `libvirtd` in case you change the certificates.

7.2.2.3. Configuring the Client and Testing the Setup¶

The client is the machine initiating connections. Therefore the client certificates have to be installed. The CA certificate needs to be installed, as well.

Create the client certificate and export it together with the CA certificate as described in Section A.2, “Generating x509 Client/Server Certificates”.
Create the following directories on the client:
```
mkdir -p /etc/pki/CA/ /etc/pki/libvirt/private/
```
Install the certificates as follows:
```
/etc/pki/CA/cacert.pem
/etc/pki/libvirt/clientcert.pem
/etc/pki/libvirt/private/clientkey.pem
```
Restrict Access to Certificates
Make sure to restrict access to certificates as explained in Section 7.2.2.5, “Restricting Access (Security Considerations)”.
Test the client/server setup by issuing the following command. Replace mercury.example.com with the name of your VM Host Server. Specify the same full qualified hostname as used when creating the server certificate.
```
virsh -c qemu+tls://mercury.example.com/system list --all
```
If your setup is correct, you will see a list of all VM Guests registered with libvirt on the VM Host Server.

7.2.2.4. Enabling VNC for TLS/SSL connections¶

Currently, VNC communication over TLS is only supported by few tools. The widespread tightvnc or tigervnc viewer, for example, do not support TLS. Known to work are the Virtual Machine Manager (virt-manager), virt-viewer and the GNOME VNC viewer vinagre.

7.2.2.4.1. VNC over TLS/SSL: VM Host Server Configuration¶

In order to access the graphical console via VNC over TLS/SSL, you need to configure the VM Host Server as follows:

Open ports for the service VNC in your firewall.

Create a directory /etc/pki/libvirt-vnc and link the certificates into this directory as follows:

mkdir -p /etc/pki/libvirt-vnc && cd /etc/pki/libvirt-vnc
	ln -s /etc/pki/CA/cacert.pem ca-cert.pem
	ln -s /etc/pki/libvirt/servercert.pem server-cert.pem
	ln -s /etc/pki/libvirt/private/serverkey.pem server-key.pem

Edit /etc/libvirt/qemu.conf and set the following parameters:
```
vnc_listen = "0.0.0.0"
	vnc_tls = 1
	vnc_tls_x509_verify = 1
```

Restart the libvirtd:

rclibvirtd restart

	VM Guests Need to be Restarted
The VNC TLS setting is only set when starting a VM Guest. Therefore, you need to restart all machines that have been running prior to making the configuration change.

7.2.2.4.2. VNC over TLS/SSL: Client Configuration¶

The only action needed on the client side is to place the x509 client certificates in a location recognized by the client of choice. Unfortunately, each supported client—Virtual Machine Manager, virt-viewer, and vinagre—expects the certificates in a different location. However, Virtual Machine Manager and vinagre can either read from a system wide location applying to all users, or from a per user location.

Virtual Machine Manager (virt-manager)

In order to connect to the remote host, Virtual Machine Manager requires the setup explained in Section 7.2.2.3, “Configuring the Client and Testing the Setup”. In order to be able to connect via VNC the client certificates also need to be placed in the following locations:

System wide location

/etc/pki/CA/cacert.pem

/etc/pki/libvirt-vnc/clientcert.pem

/etc/pki/libvirt-vnc/private/clientkey.pem

Per user location

/etc/pki/CA/cacert.pem

~/.pki/libvirt-vnc/clientcert.pem

~/.pki/libvirt-vnc/private/clientkey.pem

virt-viewer

virt-viewer only accepts certificates from a system wide location:

/etc/pki/CA/cacert.pem

/etc/pki/libvirt-vnc/clientcert.pem

/etc/pki/libvirt-vnc/private/clientkey.pem

vinagre

System wide location

/etc/pki/CA/cacert.pem

/etc/pki/vinagre/clientcert.pem

/etc/pki/vinagre/private/clientkey.pem

Per user location

$HOME/.pki/CA/cacert.pem

~/.pki/vinagre/clientcert.pem

~/.pki/vinagre/private/clientkey.pem

	Restrict Access to Certificates
Make sure to restrict access to certificates as explained in Section 7.2.2.5, “Restricting Access (Security Considerations)”.

7.2.2.5. Restricting Access (Security Considerations)¶

Each x509 certificate consists of two pieces: the public certificate and a private key. A client can only authenticate using both pieces. Therefore, any user that has read access to the client certificate and its private key can access your VM Host Server. On the other hand, an arbitrary machine equipped with the full server certificate can pretend to be the VM Host Server. Since this is probably not desirable, access to at least the private key files needs to be restricted as much as possible. The easiest way to control access to a key file is to use access permissions.

Server Certificates

Server certificates need to be readable for QEMU processes. On openSUSE QEMU processes started from libvirt tools are owned by root, so it is sufficient if root is able to read them certificates:

chmod 700 /etc/pki/libvirt/private/
chmod 600 /etc/pki/libvirt/private/serverkey.pem

If you change the ownership for QEMU processes in /etc/libvirt/qemu.conf, you also need to adjust the ownership of the key file.

System Wide Client Certificates

To control access to a key file that is available system wide, restrict read access a certain group, so that only members of that group can read the key file. In the following example, a group libvirt is created and the group ownership of the clientkey.pem and its parent directory is set to libvirt. Afterwards, the access permissions are restricted to owner and group. Finally the user tux is added to the group libvirt, so he will be able to access the key file.

CERTPATH="/etc/pki/libvirt/"
# create group libvirt
groupadd libvirt
# change ownership to user root and group libvirt
chown root.libvirt $CERTPATH/private $CERTPATH/clientkey.pem
# restrict permissions
chmod 750 $CERTPATH/private
chmod 640 $CERTPATH/private/clientkey.pem
# add user tux to group libvirt
usermod -A libvirt tux

Per User Certificates

User specific client certificates for accessing the graphical console of a VM Guest via VNC need to be placed in the users home directory in ~/.pki. Contrary to, for example, the VNC viewer using these certificates do not check the access permissions of the private key file. Therefore, it is solely on the user's responsibility to make sure the key file is not readable by others.

7.2.2.5.1. Restricting Access from the Server Side¶

By default, every client that is equipped with appropriate client certificates may connect to a VM Host Server accepting TLS connections. Therefore, it is possible to use additional server side authentication with SASL as described in Section 7.1.1.3, “Username and Password Authentication with SASL”.

It is also possible to restrict access with a whitelist of DNs (distinguished names), so only clients with a certificate matching a DN from the list can connect.

Add a list of allowed DNs to tls_allowed_dn_list in /etc/libvirt/libvirtd.conf. This list may contain wildcards. Do not specify an empty list, since that would result in refusing all connections.

tls_allowed_dn_list = [
   "C=US,L=Provo,O=SUSE Linux Products GmbH,OU=*,CN=venus.example.com,EMAIL=*",
   "C=DE,L=Nuremberg,O=SUSE Linux Products GmbH,OU=Documentation,CN=*"]

Get the distinguished name of a certificate with the following command:

certtool -i --infile /etc/pki/libvirt/clientcert.pem | grep "Subject:"

Restart libvirtd after having changed the configuration:

rclibvirtd restart

7.2.2.6. Central User Authentication with SASL for TLS Sockets¶

A direct user authentication via TLS is not possible - this is handled indirectly on each client via the read permissions for the certificates as explained in Section 7.2.2.5, “Restricting Access (Security Considerations)”. However, if a central, server based user authentication is needed libvirt also allows to use SASL (Simple Authentication and Security Layer) on top of TLS for direct user authentication. See Section 7.1.1.3, “Username and Password Authentication with SASL” for configuration details.

7.2.2.7. Troubleshooting¶

7.2.2.7.1. Virtual Machine Manager/virsh Cannot Connect to Server¶

Check the following in the given order:

Is it a firewall issue (TCP port 16514 needs to be open on the server)?

Is the client certificate (certificate and key) readable by the user that has started Virtual Machine Manager/virsh?

Has the same full qualified hostname as in the server certificate been specified with the connection?

Is TLS enabled on the server (

listen_tls =
	1

Has libvirtd been restarted on the server?

7.2.2.7.2. VNC Connection fails¶

Ensure that you can basically connect to the remote server using Virtual Machine Manager. If so, check whether the virtual machine on the server has been started with TLS support. The virtual machine's name in the following example is “sles11”.

ps ax | grep qemu | grep "\-name sles11" | awk -F" -vnc " '{ print FS $2 }'

If the output does not begin with a string similar to the following, the machine has not been started with TLS support and must be restarted.

 -vnc 0.0.0.0:0,tls,x509verify=/etc/pki/libvirt

7.3. Connecting to a VM Host Server¶

In order to connect to a hypervisor with libvirt, you need to specify a uniform resource identifier (URI). This URI is needed with virsh and virt-viewer (except when working as root on the VM Host Server) and is optional for the Virtual Machine Manager. Although the latter can be called with a connection parameter (for example, virt-manager -c qemu:///system), it also offers a graphical interface to create connection URIs. See Section 7.3.1, “Managing Connections with Virtual Machine Manager” for details.

HYPERVISOR+PROTOCOL://USER@REMOTE/CONNECTION_TYPE

	Specify the hypervisor. openSUSE currently supports the following hypervisors: `test` (dummy for testing), `qemu` (KVM), and `xen` (Xen). This parameter is mandatory.
	When connecting to a remote host, specify the protocol here. Can be one of: `ssh` (connection via SSH tunnel), `tcp` (TCP connection with SASL/Kerberos authentication), `tls` (TLS/SSL encrypted connection with authentication via x509 certificates).
	When connecting to a remote host, specify the user and the remote hostname. If no user is specified, the username that has called the command (`$USER`) is used. Please see below for more information. For TLS connections the hostname has to be specified exactly as in the x509 certificate.
	When connecting to `QEMU` hypervisor, two connections types are accepted: `system` for full access rights, or `session` for restricted access. Since `session` access is not supported on openSUSE, this documentation focuses on `system` access.

Example Hypervisor Connection URIs

test:///default: Connect to the local dummy hypervisor. Useful for testing.
qemu:///system: Connect to the QEMU hypervisor on the local host having full access (type system). This usually requires that the command is issued by the user root.
qemu+ssh://tux@mercury.example.com/system: Connect to the QEMU hypervisor on the remote host mercury.example.com. The connection is established via an SSH tunnel.
qemu+tls://saturn.example.com/system: Connect to the QEMU hypervisor on the remote host mercury.example.com. The connection is established TLS/SSL.

For more details and examples, refer to the libvirt documentation at http://libvirt.org/uri.html.

	Usernames in URIs
A username needs to be specified when using Unix socket authentication (regardless whether using the username/password authentication scheme or PolicyKit). This applies to all SSH and local connections. There is no need to specify a username when using SASL authentication (for TCP or TLS connections) or when doing no additional server side authentication for TLS connections. With SASL the username will not be evaluated—you will be prompted for a SASL user/password combination in any case.

Usernames in URIs

A username needs to be specified when using Unix socket authentication (regardless whether using the username/password authentication scheme or PolicyKit). This applies to all SSH and local connections.

There is no need to specify a username when using SASL authentication (for TCP or TLS connections) or when doing no additional server side authentication for TLS connections. With SASL the username will not be evaluated—you will be prompted for a SASL user/password combination in any case.

7.3.1. Managing Connections with Virtual Machine Manager¶

The Virtual Machine Manager uses a Connection for every VM Host Server it manages. Each connection contains all VM Guests on the respective host. By default, a connection to the localhost is already configured and connected.

All configured connections are displayed in the Virtual Machine Manager main window. Active connections are marked with a small triangle which you can click in order to fold or unfold the list of VM Guests for this connection.

Inactive connections are listed gray and are marked with Not Connected. Either double-click or right-click it and choose Connect from the context menu. You can also Delete an existing connection from this menu.

	Editing Existing Connections
It is not possible to edit an existing connection. In order to change a connection, create a new one with the desired parameters and delete the “old” one.

To add a new connection in the Virtual Machine Manager, proceed as follows:

Choose File+Add Connection
Choose the host's Hypervisor (Xen or QEMU/KVM)
Choose a Connection type—either Local for connecting to the host the Virtual Machine Manager was started on, or one of the remote connections (see Section 7.2, “Configuring Remote Connections” for more information).

In case of a remote connection, enter the Hostname of the remote machine as USERNAME@REMOTE_HOST. Usernames must be specified for local connections as well as for SSH

	Specifying a Username
There is no need to specify a username for TCP and TLS connections; it will not be evaluated anyway. A username must be specified for local connections as well as for SSH connections—if not, the default user `root` will be used.

If you do not want the connection to be automatically activated when starting the Virtual Machine Manager, remove the tick from Autoconnect.
Finish the configuration by clicking Connect.