Module libvirt-admin from libvirt-admin

Provides the interfaces of the libvirt library to operate with the server itself, not any hypervisors.

Macros

#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

Types

typedef struct _virAdmClient virAdmClient
typedef virAdmClient * virAdmClientPtr
typedef struct _virAdmConnect virAdmConnect
typedef virAdmConnect * virAdmConnectPtr
typedef struct _virAdmServer virAdmServer
typedef virAdmServer * virAdmServerPtr
typedef enum virClientTransport

Functions

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	virAdmConnectSetDaemonTimeout	(virAdmConnectPtr conn, 
					 unsigned int timeout, 
					 unsigned int flags)
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)

Description

`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.

Types ¶

`virAdmClient`¶

struct virAdmClient {

The content of this structure is not made public by the API

`virAdmClientPtr`¶

typedef virAdmClient * virAdmClientPtr;

a virAdmClientPtr is a pointer to a virAdmClient structure, this is the type used to reference client-side representation of a client object throughout all the APIs.

`virAdmConnect`¶

struct virAdmConnect {

The content of this structure is not made public by the API

`virAdmConnectPtr`¶

typedef virAdmConnect * virAdmConnectPtr;

a virAdmConnectPtr is pointer to a virAdmConnect private structure, this is the type used to reference a connection to the daemon in the API.

`virAdmServer`¶

struct virAdmServer {

The content of this structure is not made public by the API

`virAdmServerPtr`¶

typedef virAdmServer * virAdmServerPtr;

a virAdmServerPtr is a pointer to a virAdmServer structure, this is the type used to reference client-side representation of a remote server object throughout all the APIs.

`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)

Functions ¶

`virAdmClientClose`¶

int	virAdmClientClose		(virAdmClientPtr client,
					 unsigned int flags)

Close client's connection to daemon forcefully.

client: a valid client object reference
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 if the daemon's connection with client was closed successfully or -1 in case of an error.

`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.

client: a client object
Returns: 0 in success, -1 on failure.

`virAdmClientGetID`¶

unsigned long long	virAdmClientGetID	(virAdmClientPtr client)

Get client's unique numeric ID.

client: a client object
Returns: numeric value used for client's ID or -1 in case of an error.

`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.

client: a client object reference
params: pointer to a list of typed parameters which will be allocated to store all returned parameters
nparams: pointer which will hold the number of params returned in params
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 if the information has been successfully retrieved or -1 in case of an error.

`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.

client: a client object
Returns: client's connection timestamp (seconds from epoch in UTC) or 0 (epoch time) if libvirt doesn't have any information about client's connection time, or -1 in case of an error.

`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.

client: a client object
Returns: integer representation of the connection transport used by client (this will be one of virClientTransport) or -1 in case of an error.

`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.

conn: pointer to admin connection to close
Returns: a positive number if at least 1 reference remains on success. The returned value should not be assumed to be the total reference count. A return of 0 implies no references remain and the connection is closed and memory has been freed. A return of -1 implies a failure. It is possible for the last virAdmConnectClose to return a positive value if some other object still has a temporary reference to the connection, but the application should not try to further use a connection after the virAdmConnectClose that matches the initial open.

`virAdmConnectCloseFunc`¶

typedef void	(*virAdmConnectCloseFunc	)	(virAdmConnectPtr conn,
					 int reason,
					 void * opaque)

A callback to be registered, in case a connection was closed.

conn: virAdmConnect connection
reason: reason why the connection was closed (see virConnectCloseReason)
opaque: opaque client data

`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.

conn: pointer to an active admin connection
libVer: stores the current remote libvirt version number
Returns: 0 on success, -1 on failure and libVer follows this format:

`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.

conn: pointer to an active admin connection
filters: pointer to a variable to store a string containing all currently defined logging filters on daemon (allocated automatically) or NULL if just the number of defined outputs is required
flags: extra flags; not used yet, so callers should always pass 0
Returns: the number of filters returned in filters, or -1 in case of an error.

`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.

conn: pointer to an active admin connection
outputs: pointer to a variable to store a string containing all currently defined logging outputs on daemon (allocated automatically) or NULL if just the number of defined outputs is required
flags: extra flags; not used yet, so callers should always pass 0
Returns: the count of outputs in outputs, or -1 in case of an error.

`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.

conn: pointer to an admin connection
Returns: an URI string related to the connection or NULL in case of an error. Caller is responsible for freeing the 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.

conn: connection to admin server
Returns: 1, if the connection is alive, 0 if there isn't an existing connection at all or the channel has already been closed, or -1 on error.

`virAdmConnectListServers`¶

int	virAdmConnectListServers	(virAdmConnectPtr conn,
					 virAdmServerPtr ** servers,
					 unsigned int flags)

Collect list of all servers provided by daemon the client is connected to.

conn: daemon connection reference
servers: Pointer to a list to store an array containing objects or NULL if the list is not required (number of servers only)
flags: extra flags; not used yet, so callers should always pass 0
Returns: the number of servers available on daemon side or -1 in case of a failure, setting servers to NULL. There is a guaranteed extra element set to NULL in the servers list returned to make the iteration easier, excluding this extra element from the final count. Caller is responsible to call virAdmServerFree() on each list element, followed by freeing servers.

`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.

conn: daemon connection reference
name: name of the server too lookup
flags: extra flags; not used yet, so callers should always pass 0
Returns: the requested server or NULL in case of failure. If the server cannot be found, then VIR_ERR_NO_SERVER error is raised.

`virAdmConnectOpen`¶

virAdmConnectPtr	virAdmConnectOpen	(const char * name,
						 unsigned int flags)

Opens connection to admin interface of the daemon.

name: uri of the daemon to connect to, NULL for default
flags: bitwise-OR of virConnectFlags; so far the only supported flag is VIR_CONNECT_NO_ALIASES
Returns: @virAdmConnectPtr object or NULL on error

`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.

conn: the connection to hold a reference on
Returns: 0 in case of success, -1 in case of failure

`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.

conn: connection to admin server
cb: callback to be invoked upon connection close
opaque: user data to pass to cb
freecb: callback to free opaque
Returns: 0 on success, -1 on error

`virAdmConnectSetDaemonTimeout`¶

int	virAdmConnectSetDaemonTimeout	(virAdmConnectPtr conn,
					 unsigned int timeout,
					 unsigned int flags)

Reconfigure the existing timeout of the daemon to timeout. Setting timeout to 0 disables the daemon timeout.

conn: pointer to an active admin connection
timeout: timeout to set in seconds (0 disables timeout)
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 on success, -1 on error.

`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.

conn: pointer to an active admin connection
filters: pointer to a string containing a list of filters to be defined
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 if the new filter or the set of filters has been defined successfully, or -1 in case of an error.

`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.

conn: pointer to an active admin connection
outputs: pointer to a string containing a list of outputs to be defined
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 if the new output or the set of outputs has been defined successfully, or -1 in case of an error.

`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.

conn: pointer to connection object
cb: pointer to the current registered callback
Returns: 0 on success, -1 on error

`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.

libVer: where to store the library version
Returns: 0 on success, -1 in case of an error.

`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.

Returns: 0 in case of success, -1 in case of error

`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.

srv: server object
Returns: 0 on success, -1 on failure.

`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.

srv: a valid server object reference
params: pointer to client limits object (return value, allocated automatically)
nparams: pointer to number of parameters returned in params
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 on success, allocating params to size returned in nparams, or -1 in case of an error. Caller is responsible for deallocating params.

`virAdmServerGetName`¶

const char *	virAdmServerGetName	(virAdmServerPtr srv)

Get the public name for specified server

srv: a server object
Returns: a pointer to the name or NULL. The string doesn't need to be deallocated since its lifetime will be the same as the server object.

`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

srv: a valid server object reference
params: pointer to a list of typed parameters which will be allocated to store all returned parameters
nparams: pointer which will hold the number of params returned in params
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 on success, -1 in case of an error.

`virAdmServerListClients`¶

int	virAdmServerListClients		(virAdmServerPtr srv,
					 virAdmClientPtr ** clients,
					 unsigned int flags)

Collect list of all clients connected to daemon on server srv.

srv: a valid server object reference
clients: pointer to a list to store an array containing objects or NULL if the list is not required (number of clients only)
flags: extra flags; not used yet, so callers should always pass 0
Returns: the number of clients connected to daemon on server srv -1 in case of a failure, setting clients to NULL. There is a guaranteed extra element set to NULL in the clients list returned to make the iteration easier, excluding this extra element from the final count. Caller is responsible to call virAdmClientFree() on each list element, followed by freeing clients.

`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.

srv: a valid server object reference
id: ID of the client to lookup on server srv
flags: extra flags; not used yet, so callers should always pass 0
Returns: the requested client or NULL in case of failure. If the client could not be found, then VIR_ERR_NO_CLIENT error is raised.

`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.

srv: a valid server object reference
params: pointer to client limits object
nparams: number of parameters in params
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 if the limits have been changed successfully or -1 in case of an error.

`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.

srv: a valid server object reference
params: pointer to threadpool typed parameter objects
nparams: number of parameters in params
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 on success, -1 in case of an error.

`virAdmServerUpdateTlsFiles`¶

int	virAdmServerUpdateTlsFiles	(virAdmServerPtr srv,
					 unsigned int flags)

Notify server to update tls file, such as cacert, cacrl, server cert / key.

srv: a valid server object reference
flags: extra flags; not used yet, so callers should always pass 0
Returns: 0 if the TLS files have been updated successfully or -1 in case of an error.

Module libvirt-admin from libvirt-admin

Table of Contents

Description

Contact

Community