Provides the interfaces of the libvirt library to operate with the server itself, not any hypervisors. Copyright (C) 2014-2015 Red Hat, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see http://www.gnu.org/licenses/.
#define VIR_CLIENT_INFO_READONLY #define VIR_CLIENT_INFO_SASL_USER_NAME #define VIR_CLIENT_INFO_SELINUX_CONTEXT #define VIR_CLIENT_INFO_SOCKET_ADDR #define VIR_CLIENT_INFO_UNIX_GROUP_ID #define VIR_CLIENT_INFO_UNIX_GROUP_NAME #define VIR_CLIENT_INFO_UNIX_PROCESS_ID #define VIR_CLIENT_INFO_UNIX_USER_ID #define VIR_CLIENT_INFO_UNIX_USER_NAME #define VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME #define VIR_SERVER_CLIENTS_CURRENT #define VIR_SERVER_CLIENTS_MAX #define VIR_SERVER_CLIENTS_UNAUTH_CURRENT #define VIR_SERVER_CLIENTS_UNAUTH_MAX #define VIR_THREADPOOL_JOB_QUEUE_DEPTH #define VIR_THREADPOOL_WORKERS_CURRENT #define VIR_THREADPOOL_WORKERS_FREE #define VIR_THREADPOOL_WORKERS_MAX #define VIR_THREADPOOL_WORKERS_MIN #define VIR_THREADPOOL_WORKERS_PRIORITY
typedef struct _virAdmClient virAdmClient typedef virAdmClient * virAdmClientPtr typedef struct _virAdmConnect virAdmConnect typedef virAdmConnect * virAdmConnectPtr typedef struct _virAdmServer virAdmServer typedef virAdmServer * virAdmServerPtr typedef enum virClientTransport
int virAdmClientClose (virAdmClientPtr client,
unsigned int flags) int virAdmClientFree (virAdmClientPtr client) unsigned long long virAdmClientGetID (virAdmClientPtr client) int virAdmClientGetInfo (virAdmClientPtr client,
virTypedParameterPtr * params,
int * nparams,
unsigned int flags) long long virAdmClientGetTimestamp (virAdmClientPtr client) int virAdmClientGetTransport (virAdmClientPtr client) int virAdmConnectClose (virAdmConnectPtr conn) typedef virAdmConnectCloseFunc void virAdmConnectCloseFunc (virAdmConnectPtr conn,
int reason,
void * opaque) int virAdmConnectGetLibVersion (virAdmConnectPtr conn,
unsigned long long * libVer) int virAdmConnectGetLoggingFilters (virAdmConnectPtr conn,
char ** filters,
unsigned int flags) int virAdmConnectGetLoggingOutputs (virAdmConnectPtr conn,
char ** outputs,
unsigned int flags) char * virAdmConnectGetURI (virAdmConnectPtr conn) int virAdmConnectIsAlive (virAdmConnectPtr conn) int virAdmConnectListServers (virAdmConnectPtr conn,
virAdmServerPtr ** servers,
unsigned int flags) virAdmServerPtr virAdmConnectLookupServer (virAdmConnectPtr conn,
const char * name,
unsigned int flags) virAdmConnectPtr virAdmConnectOpen (const char * name,
unsigned int flags) int virAdmConnectRef (virAdmConnectPtr conn) int virAdmConnectRegisterCloseCallback (virAdmConnectPtr conn,
virAdmConnectCloseFunc cb,
void * opaque,
virFreeCallback freecb) int virAdmConnectSetLoggingFilters (virAdmConnectPtr conn,
const char * filters,
unsigned int flags) int virAdmConnectSetLoggingOutputs (virAdmConnectPtr conn,
const char * outputs,
unsigned int flags) int virAdmConnectUnregisterCloseCallback (virAdmConnectPtr conn,
virAdmConnectCloseFunc cb) int virAdmGetVersion (unsigned long long * libVer) int virAdmInitialize (void) int virAdmServerFree (virAdmServerPtr srv) int virAdmServerGetClientLimits (virAdmServerPtr srv,
virTypedParameterPtr * params,
int * nparams,
unsigned int flags) const char * virAdmServerGetName (virAdmServerPtr srv) int virAdmServerGetThreadPoolParameters (virAdmServerPtr srv,
virTypedParameterPtr * params,
int * nparams,
unsigned int flags) int virAdmServerListClients (virAdmServerPtr srv,
virAdmClientPtr ** clients,
unsigned int flags) virAdmClientPtr virAdmServerLookupClient (virAdmServerPtr srv,
unsigned long long id,
unsigned int flags) int virAdmServerSetClientLimits (virAdmServerPtr srv,
virTypedParameterPtr params,
int nparams,
unsigned int flags) int virAdmServerSetThreadPoolParameters (virAdmServerPtr srv,
virTypedParameterPtr params,
int nparams,
unsigned int flags) int virAdmServerUpdateTlsFiles (virAdmServerPtr srv,
unsigned int flags)
VIR_CLIENT_INFO_READONLY
¶
#define VIR_CLIENT_INFO_READONLY
Macro represents client's connection permission, whether the client is connected in read-only mode or just the opposite - read-write, as VIR_TYPED_PARAM_BOOLEAN. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_CLIENT_INFO_SASL_USER_NAME
¶
#define VIR_CLIENT_INFO_SASL_USER_NAME
Macro represents client's SASL user name, if SASL authentication is enabled on the remote host, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_CLIENT_INFO_SELINUX_CONTEXT
¶
#define VIR_CLIENT_INFO_SELINUX_CONTEXT
Macro represents the client's (peer's) SELinux context and this can either be at socket layer or at transport layer, depending on the connection type, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_CLIENT_INFO_SOCKET_ADDR
¶
#define VIR_CLIENT_INFO_SOCKET_ADDR
Macro represents clients network socket address in a standard URI format: (IPv4|[IPv6]):port, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_CLIENT_INFO_UNIX_GROUP_ID
¶
#define VIR_CLIENT_INFO_UNIX_GROUP_ID
Macro represents UNIX GID the client process is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_INT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_CLIENT_INFO_UNIX_GROUP_NAME
¶
#define VIR_CLIENT_INFO_UNIX_GROUP_NAME
Macro represents the group name that is bound to the client process's GID it is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_CLIENT_INFO_UNIX_PROCESS_ID
¶
#define VIR_CLIENT_INFO_UNIX_PROCESS_ID
Macro represents the client process's pid it is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_INT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_CLIENT_INFO_UNIX_USER_ID
¶
#define VIR_CLIENT_INFO_UNIX_USER_ID
Macro represents UNIX UID the client process is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_INT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_CLIENT_INFO_UNIX_USER_NAME
¶
#define VIR_CLIENT_INFO_UNIX_USER_NAME
Macro represents the user name that is bound to the client process's UID it is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME
¶
#define VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME
Macro represents the 'distinguished name' field in X509 certificate the client used to establish a TLS session with remote host, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_SERVER_CLIENTS_CURRENT
¶
#define VIR_SERVER_CLIENTS_CURRENT
Macro for per-server nclients attribute: represents the current number of clients connected to the server, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_SERVER_CLIENTS_MAX
¶
#define VIR_SERVER_CLIENTS_MAX
Macro for per-server nclients_max limit: represents the upper limit to number of clients connected to the server, as uint.
VIR_SERVER_CLIENTS_UNAUTH_CURRENT
¶
#define VIR_SERVER_CLIENTS_UNAUTH_CURRENT
Macro for per-server nclients_unauth attribute: represents the current number of clients connected to the server, but not authenticated yet, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_SERVER_CLIENTS_UNAUTH_MAX
¶
#define VIR_SERVER_CLIENTS_UNAUTH_MAX
Macro for per-server nclients_unauth_max limit: represents the upper limit to number of clients connected to the server, but not authenticated yet, as VIR_TYPED_PARAM_UINT.
VIR_THREADPOOL_JOB_QUEUE_DEPTH
¶
#define VIR_THREADPOOL_JOB_QUEUE_DEPTH
Macro for the threadpool jobQueueDepth attribute: represents the current number of jobs waiting in a queue to be processed, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_THREADPOOL_WORKERS_CURRENT
¶
#define VIR_THREADPOOL_WORKERS_CURRENT
Macro for the threadpool nWorkers attribute: represents the current number of active ordinary workers in threadpool, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_THREADPOOL_WORKERS_FREE
¶
#define VIR_THREADPOOL_WORKERS_FREE
Macro for the threadpool freeWorkers attribute: represents the current number of free workers available to accomplish a job, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon
VIR_THREADPOOL_WORKERS_MAX
¶
#define VIR_THREADPOOL_WORKERS_MAX
Macro for the threadpool maxWorkers limit: represents the upper limit to number of active workers in threadpool, as VIR_TYPED_PARAM_UINT. The value of this limit has to be greater than VIR_THREADPOOL_WORKERS_MIN at all times.
VIR_THREADPOOL_WORKERS_MIN
¶
#define VIR_THREADPOOL_WORKERS_MIN
Macro for the threadpool minWorkers limit: represents the bottom limit to number of active workers in threadpool, as VIR_TYPED_PARAM_UINT.
VIR_THREADPOOL_WORKERS_PRIORITY
¶
#define VIR_THREADPOOL_WORKERS_PRIORITY
Macro for the threadpool nPrioWorkers attribute: represents the current number of active priority workers in threadpool, as VIR_TYPED_PARAM_UINT.
virAdmClient
¶
struct virAdmClient {
}
virAdmConnect
¶
struct virAdmConnect {
}
virAdmServer
¶
struct virAdmServer {
}
virClientTransport
¶
enum virClientTransport {
VIR_CLIENT_TRANS_UNIX | = | 0 (0x0) |
connection via UNIX socket
|
VIR_CLIENT_TRANS_TCP | = | 1 (0x1) |
connection via unencrypted TCP socket
|
VIR_CLIENT_TRANS_TLS | = | 2 (0x2) |
connection via encrypted TCP socket
|
VIR_CLIENT_TRANS_LAST | = | 3 (0x3) |
}
virAdmClientClose
¶
int virAdmClientClose (virAdmClientPtr client, unsigned int flags)
Close @client's connection to daemon forcefully.
virAdmClientFree
¶
int virAdmClientFree (virAdmClientPtr client)
Release the client object. The running instance is kept alive. The data structure is freed and should not be used thereafter.
virAdmClientGetID
¶
unsigned long long virAdmClientGetID (virAdmClientPtr client)
Get client's unique numeric ID.
virAdmClientGetInfo
¶
int virAdmClientGetInfo (virAdmClientPtr client, virTypedParameterPtr * params, int * nparams, unsigned int flags)
Extract identity information about a client. Attributes returned in @params are mostly transport-dependent, i.e. some attributes including client process's pid, gid, uid, or remote side's socket address are only available for a specific connection type - local vs remote. Other identity attributes like authentication method used (if authentication is enabled on the remote host), SELinux context, or an indicator whether client is connected via a read-only connection are independent of the connection transport.
Note that the read-only connection indicator returns false for TCP/TLS clients because libvirt treats such connections as read-write by default, even though a TCP client is able to restrict access to certain APIs for itself.
virAdmClientGetTimestamp
¶
long long virAdmClientGetTimestamp (virAdmClientPtr client)
Get client's connection time. A situation may happen, that some clients had connected prior to the update to admin API, thus, libvirt assigns these clients epoch time to express that it doesn't know when the client connected.
virAdmClientGetTransport
¶
int virAdmClientGetTransport (virAdmClientPtr client)
Get client's connection transport type. This information can be helpful to differentiate between clients connected locally or remotely. An exception to this would be SSH which is one of libvirt's supported transports. Although SSH creates a channel between two (preferably) remote endpoints, the client process libvirt spawns automatically on the remote side will still connect to a UNIX socket, thus becoming indistinguishable from any other locally connected clients.
virAdmConnectClose
¶
int virAdmConnectClose (virAdmConnectPtr conn)
This function closes the admin connection to the Hypervisor. This should not be called if further interaction with the Hypervisor are needed especially if there is running domain which need further monitoring by the application.
Connections are reference counted; the count is explicitly increased by the initial virAdmConnectOpen, as well as virAdmConnectRef; it is also temporarily increased by other API that depend on the connection remaining alive. The open and every virAdmConnectRef call should have a matching virAdmConnectClose, and all other references will be released after the corresponding operation completes.
virAdmConnectCloseFunc
¶
typedef void (*virAdmConnectCloseFunc ) (virAdmConnectPtr conn, int reason, void * opaque)
A callback to be registered, in case a connection was closed.
virAdmConnectGetLibVersion
¶
int virAdmConnectGetLibVersion (virAdmConnectPtr conn, unsigned long long * libVer)
Retrieves the remote side libvirt version used by the daemon. Format returned in @libVer is of a following pattern: major * 1,000,000 + minor * 1,000 + release.
virAdmConnectGetLoggingFilters
¶
int virAdmConnectGetLoggingFilters (virAdmConnectPtr conn, char ** filters, unsigned int flags)
Retrieves a list of currently installed logging filters. Filters returned are contained within an automatically allocated string and delimited by spaces. The format of each filter conforms to the format described in daemon's configuration file (e.g. libvirtd.conf).
To retrieve individual filters, additional parsing needs to be done by the caller. Caller is also responsible for freeing @filters correctly.
virAdmConnectGetLoggingOutputs
¶
int virAdmConnectGetLoggingOutputs (virAdmConnectPtr conn, char ** outputs, unsigned int flags)
Retrieves a list of currently installed logging outputs. Outputs returned are contained within an automatically allocated string and delimited by spaces. The format of each output conforms to the format described in daemon's configuration file (e.g. libvirtd.conf).
To retrieve individual outputs, additional parsing needs to be done by the caller. Caller is also responsible for freeing @outputs correctly.
virAdmConnectGetURI
¶
char * virAdmConnectGetURI (virAdmConnectPtr conn)
String returned by this method is normally the same as the string passed to the virAdmConnectOpen. Even if NULL was passed to virAdmConnectOpen, this method returns a non-null URI string.
virAdmConnectIsAlive
¶
int virAdmConnectIsAlive (virAdmConnectPtr conn)
Decide whether the connection to the admin server is alive or not. Connection is considered alive if the channel it is running over is not closed.
virAdmConnectListServers
¶
int virAdmConnectListServers (virAdmConnectPtr conn, virAdmServerPtr ** servers, unsigned int flags)
Collect list of all servers provided by daemon the client is connected to.
virAdmConnectLookupServer
¶
virAdmServerPtr virAdmConnectLookupServer (virAdmConnectPtr conn, const char * name, unsigned int flags)
Try to lookup a server on the given daemon based on @name.
virAdmServerFree() should be used to free the resources after the server object is no longer needed.
virAdmConnectOpen
¶
virAdmConnectPtr virAdmConnectOpen (const char * name, unsigned int flags)
Opens connection to admin interface of the daemon.
virAdmConnectRef
¶
int virAdmConnectRef (virAdmConnectPtr conn)
Increment the reference count on the connection. For each additional call to this method, there shall be a corresponding call to virAdmConnectClose to release the reference count, once the caller no longer needs the reference to this object.
This method is typically useful for applications where multiple threads are using a connection, and it is required that the connection remain open until all threads have finished using it. I.e., each new thread using a connection would increment the reference count.
virAdmConnectRegisterCloseCallback
¶
int virAdmConnectRegisterCloseCallback (virAdmConnectPtr conn, virAdmConnectCloseFunc cb, void * opaque, virFreeCallback freecb)
Registers a callback to be invoked when the connection is closed. This callback is invoked when there is any condition that causes the socket connection to the hypervisor to be closed.
The @freecb must not invoke any other libvirt public APIs, since it is not called from a re-entrant safe context.
virAdmConnectSetLoggingFilters
¶
int virAdmConnectSetLoggingFilters (virAdmConnectPtr conn, const char * filters, unsigned int flags)
Redefine the existing (set of) filter(s) with a new one specified in @filters. If multiple filters are specified, they need to be delimited by spaces. The format of each filter must conform to the format described in daemon's configuration file (e.g. libvirtd.conf).
To clear the currently defined (set of) filter(s), pass either an empty string ("") or NULL in @filters.
virAdmConnectSetLoggingOutputs
¶
int virAdmConnectSetLoggingOutputs (virAdmConnectPtr conn, const char * outputs, unsigned int flags)
Redefine the existing (set of) outputs(s) with a new one specified in @outputs. If multiple outputs are specified, they need to be delimited by spaces. The format of each output must conform to the format described in daemon's configuration file (e.g. libvirtd.conf).
To reset the existing (set of) output(s) to libvirt's defaults, an empty string ("") or NULL should be passed in @outputs.
virAdmConnectUnregisterCloseCallback
¶
int virAdmConnectUnregisterCloseCallback (virAdmConnectPtr conn, virAdmConnectCloseFunc cb)
Unregisters the callback previously set with the virAdmConnectRegisterCloseCallback method. The callback will no longer receive notifications when the connection closes. If a virFreeCallback was provided at time of registration, it will be invoked.
virAdmGetVersion
¶
int virAdmGetVersion (unsigned long long * libVer)
Provides version information. @libVer is the version of the library and will always be set unless an error occurs in which case an error code and a generic message will be returned. @libVer format is as follows: major * 1,000,000 + minor * 1,000 + release.
NOTE: To get the remote side library version use virAdmConnectGetLibVersion instead.
virAdmInitialize
¶
int virAdmInitialize (void)
Initialize the library.
This method is automatically invoked by virAdmConnectOpen() API. Therefore, in most cases it is unnecessary to call this method manually, unless an event loop should be set up by calling virEventRegisterImpl() or the error reporting of the first connection attempt with virSetErrorFunc() should be altered prior to setting up connections. If the latter is the case, it is necessary for the application to call virAdmInitialize.
virAdmServerFree
¶
int virAdmServerFree (virAdmServerPtr srv)
Release the server object. The running instance is kept alive. The data structure is freed and should not be used thereafter.
virAdmServerGetClientLimits
¶
int virAdmServerGetClientLimits (virAdmServerPtr srv, virTypedParameterPtr * params, int * nparams, unsigned int flags)
Retrieve client limits from server @srv. These include: - current number of clients connected to @srv, - maximum number of clients connected to @srv, - current number of clients connected to @srv waiting for authentication, - maximum number of clients connected to @srv that can be wainting for authentication.
virAdmServerGetName
¶
const char * virAdmServerGetName (virAdmServerPtr srv)
Get the public name for specified server
virAdmServerGetThreadPoolParameters
¶
int virAdmServerGetThreadPoolParameters (virAdmServerPtr srv, virTypedParameterPtr * params, int * nparams, unsigned int flags)
Retrieves threadpool parameters from @srv. Upon successful completion, @params will be allocated automatically to hold all returned data, setting @nparams accordingly. When extracting parameters from @params, following search keys are supported: VIR_THREADPOOL_WORKERS_MIN VIR_THREADPOOL_WORKERS_MAX VIR_THREADPOOL_WORKERS_PRIORITY VIR_THREADPOOL_WORKERS_FREE VIR_THREADPOOL_WORKERS_CURRENT
virAdmServerListClients
¶
int virAdmServerListClients (virAdmServerPtr srv, virAdmClientPtr ** clients, unsigned int flags)
Collect list of all clients connected to daemon on server @srv.
virAdmServerLookupClient
¶
virAdmClientPtr virAdmServerLookupClient (virAdmServerPtr srv, unsigned long long id, unsigned int flags)
Try to lookup a client on the given server based on @id.
virAdmClientFree() should be used to free the resources after the client object is no longer needed.
virAdmServerSetClientLimits
¶
int virAdmServerSetClientLimits (virAdmServerPtr srv, virTypedParameterPtr params, int nparams, unsigned int flags)
Change client limits configuration on server @srv.
Caller is responsible for allocating @params prior to calling this function. See 'Manage per-server client limits' in libvirt-admin.h for supported parameters in @params.
virAdmServerSetThreadPoolParameters
¶
int virAdmServerSetThreadPoolParameters (virAdmServerPtr srv, virTypedParameterPtr params, int nparams, unsigned int flags)
Change server threadpool parameters according to @params. Note that some tunables are read-only, thus any attempt to set them will result in a failure.
virAdmServerUpdateTlsFiles
¶
int virAdmServerUpdateTlsFiles (virAdmServerPtr srv, unsigned int flags)
Notify server to update tls file, such as cacert, cacrl, server cert / key.