The very first thing a libvirt agent must do is call one of the libvirt connection functions to obtain a virConnectPtr handle. This handle will be used in subsequent operations. The libvirt library provides 3 different functions for connecting to a resource:

   virConnectPtr virConnectOpen(const char *name)
   virConnectPtr virConnectOpenReadOnly(const char *name)
   virConnectPtr virConnectOpenAuth(const char *name, virConnectAuthPtr auth, int flags)

In all three cases there is a name parameter which in fact refers to the URI of the hypervisor to connect to. The previous sections Section 2.2, “Driver model” and Section 2.3.4, “Remote URIs” provide full details on the various URI formats that are acceptable. If the URI is omitted then libvirt will apply some heuristics and probe for a suitable hypervisor driver. While this may be convenient for developers doing adhoc testing, it is strongly recommended that applications do not rely on probing logic since it may change at any time. Applications should always explicitly request which hypervisor connection they want by providing a URI.

The difference between the three methods outlined above is the way in which they authenticate and the resulting authorization level they provide. The first virConnectOpen method will attempt to open a connection for full read-write access. It does not have any scope for authentication callbacks to be provided, so it will only succeed for connections where authentication can be done based on the POSIX credentials of the application. The second virConnectOpenReadOnly will attempt to open a connection for read-only access. Such a connection has a restricted set of API calls that are allowed, and is typically useful for monitoring applications that should not be allowed to make changes. As before this API has no scope for authentication callbacks, so relies on POSIX credentials. The final virConnectOpenAuth method is the most flexible, and effectively obsoletes the previous two APIs. It takes an extra parameter providing an instance of the virConnectAuthPtr struct which contains the callbacks for collecting authentication credentials from the client app. This allows libvirt to prompt for usernames, passwords, and more. The libvirt API provides an instance of this struct via the symbol virConnectAuthPtrDefault that implements callbacks suitable for a command line based application. Graphical applications will need to provide their own callback implementations. The flags parameter allows the application to request a read-only connection if desired.

A connections must be released by calling virConnectClose when no longer required. Connections are a reference counted object, so if it is intended for a connection to be used from multiple threads at once, each additional thread should call virConnectRef to ensure the connection is not freed while still in use. Every extra call to virConnectRef must be accompanied by a corresponding call to virConnectClose to relaese the reference when no longer required. Note also, that every other object associated with a connection (virDomainPtr, virNetworkPtr, etc) will also hold a reference on the connection. So to avoid leaking a connection object, applications must ensure all associated objects are also freed.