1 /* 2 * libvirt-admin.h: Admin interface for libvirt 3 * Summary: Interfaces for handling server-related tasks 4 * Description: Provides the interfaces of the libvirt library to operate 5 * with the server itself, not any hypervisors. 6 * 7 * Copyright (C) 2014-2015 Red Hat, Inc. 8 * 9 * This library is free software; you can redistribute it and/or 10 * modify it under the terms of the GNU Lesser General Public 11 * License as published by the Free Software Foundation; either 12 * version 2.1 of the License, or (at your option) any later version. 13 * 14 * This library is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * Lesser General Public License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public 20 * License along with this library. If not, see 21 * <http://www.gnu.org/licenses/>. 22 */ 23 24 #ifndef LIBVIRT_ADMIN_H 25 # define LIBVIRT_ADMIN_H 26 27 # ifdef __cplusplus 28 extern "C" { 29 # endif 30 31 # define __VIR_ADMIN_H_INCLUDES__ 32 # include <libvirt/libvirt-common.h> 33 # undef __VIR_ADMIN_H_INCLUDES__ 34 35 /** 36 * virAdmConnect: 37 * 38 * a virAdmConnect is a private structure representing a connection to 39 * libvirt daemon. 40 */ 41 typedef struct _virAdmConnect virAdmConnect; 42 43 /** 44 * virAdmServer: 45 * 46 * a virAdmServer is a private structure and client-side representation of 47 * a remote server object 48 */ 49 typedef struct _virAdmServer virAdmServer; 50 51 /** 52 * virAdmClient: 53 * 54 * a virAdmClient is a private structure and client-side representation of 55 * a remote server's client object (as server sees clients connected to it) 56 */ 57 typedef struct _virAdmClient virAdmClient; 58 59 /** 60 * virAdmConnectPtr: 61 * 62 * a virAdmConnectPtr is pointer to a virAdmConnect private structure, 63 * this is the type used to reference a connection to the daemon 64 * in the API. 65 */ 66 typedef virAdmConnect *virAdmConnectPtr; 67 68 /** 69 * virAdmServerPtr: 70 * 71 * a virAdmServerPtr is a pointer to a virAdmServer structure, 72 * this is the type used to reference client-side representation of a 73 * remote server object throughout all the APIs. 74 */ 75 typedef virAdmServer *virAdmServerPtr; 76 77 /** 78 * virAdmClientPtr: 79 * 80 * a virAdmClientPtr is a pointer to a virAdmClient structure, 81 * this is the type used to reference client-side representation of a 82 * client object throughout all the APIs. 83 */ 84 typedef virAdmClient *virAdmClientPtr; 85 86 int virAdmInitialize(void); 87 virAdmConnectPtr virAdmConnectOpen(const char *name, unsigned int flags); 88 int virAdmConnectClose(virAdmConnectPtr conn); 89 int virAdmConnectRef(virAdmConnectPtr conn); 90 int virAdmConnectIsAlive(virAdmConnectPtr conn); 91 int virAdmServerFree(virAdmServerPtr srv); 92 93 int virAdmConnectListServers(virAdmConnectPtr conn, 94 virAdmServerPtr **servers, 95 unsigned int flags); 96 97 int virAdmGetVersion(unsigned long long *libVer); 98 99 char *virAdmConnectGetURI(virAdmConnectPtr conn); 100 101 int virAdmConnectGetLibVersion(virAdmConnectPtr conn, 102 unsigned long long *libVer); 103 104 /** 105 * virAdmConnectCloseFunc: 106 * @conn: virAdmConnect connection 107 * @reason: reason why the connection was closed (see virConnectCloseReason) 108 * @opaque: opaque client data 109 * 110 * A callback to be registered, in case a connection was closed. 111 */ 112 typedef void (*virAdmConnectCloseFunc)(virAdmConnectPtr conn, 113 int reason, 114 void *opaque); 115 116 int virAdmConnectRegisterCloseCallback(virAdmConnectPtr conn, 117 virAdmConnectCloseFunc cb, 118 void *opaque, 119 virFreeCallback freecb); 120 int virAdmConnectUnregisterCloseCallback(virAdmConnectPtr conn, 121 virAdmConnectCloseFunc cb); 122 123 const char *virAdmServerGetName(virAdmServerPtr srv); 124 125 virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, 126 const char *name, 127 unsigned int flags); 128 129 /* Manage threadpool attributes */ 130 131 /** 132 * VIR_THREADPOOL_WORKERS_MIN: 133 * Macro for the threadpool minWorkers limit: represents the bottom limit to 134 * number of active workers in threadpool, as VIR_TYPED_PARAM_UINT. 135 */ 136 137 # define VIR_THREADPOOL_WORKERS_MIN "minWorkers" 138 139 /** 140 * VIR_THREADPOOL_WORKERS_MAX: 141 * Macro for the threadpool maxWorkers limit: represents the upper limit to 142 * number of active workers in threadpool, as VIR_TYPED_PARAM_UINT. 143 * The value of this limit has to be greater than VIR_THREADPOOL_WORKERS_MIN 144 * at all times. 145 */ 146 147 # define VIR_THREADPOOL_WORKERS_MAX "maxWorkers" 148 149 /** 150 * VIR_THREADPOOL_WORKERS_PRIORITY: 151 * Macro for the threadpool nPrioWorkers attribute: represents the current number 152 * of active priority workers in threadpool, as VIR_TYPED_PARAM_UINT. 153 */ 154 155 # define VIR_THREADPOOL_WORKERS_PRIORITY "prioWorkers" 156 157 /** 158 * VIR_THREADPOOL_WORKERS_FREE: 159 * Macro for the threadpool freeWorkers attribute: represents the current number 160 * of free workers available to accomplish a job, as VIR_TYPED_PARAM_UINT. 161 * 162 * NOTE: This attribute is read-only and any attempt to set it will be denied 163 * by daemon 164 */ 165 166 # define VIR_THREADPOOL_WORKERS_FREE "freeWorkers" 167 168 /** 169 * VIR_THREADPOOL_WORKERS_CURRENT: 170 * Macro for the threadpool nWorkers attribute: represents the current number 171 * of active ordinary workers in threadpool, as VIR_TYPED_PARAM_UINT. 172 * 173 * NOTE: This attribute is read-only and any attempt to set it will be denied 174 * by daemon 175 */ 176 177 # define VIR_THREADPOOL_WORKERS_CURRENT "nWorkers" 178 179 /** 180 * VIR_THREADPOOL_JOB_QUEUE_DEPTH: 181 * Macro for the threadpool jobQueueDepth attribute: represents the current 182 * number of jobs waiting in a queue to be processed, as VIR_TYPED_PARAM_UINT. 183 * 184 * NOTE: This attribute is read-only and any attempt to set it will be denied 185 * by daemon 186 */ 187 188 # define VIR_THREADPOOL_JOB_QUEUE_DEPTH "jobQueueDepth" 189 190 /* Tunables for a server workerpool */ 191 int virAdmServerGetThreadPoolParameters(virAdmServerPtr srv, 192 virTypedParameterPtr *params, 193 int *nparams, 194 unsigned int flags); 195 196 int virAdmServerSetThreadPoolParameters(virAdmServerPtr srv, 197 virTypedParameterPtr params, 198 int nparams, 199 unsigned int flags); 200 201 /* virAdmClient object accessors */ 202 unsigned long long virAdmClientGetID(virAdmClientPtr client); 203 long long virAdmClientGetTimestamp(virAdmClientPtr client); 204 int virAdmClientGetTransport(virAdmClientPtr client); 205 int virAdmClientFree(virAdmClientPtr client); 206 207 typedef enum { 208 VIR_CLIENT_TRANS_UNIX = 0, /* connection via UNIX socket */ 209 VIR_CLIENT_TRANS_TCP, /* connection via unencrypted TCP socket */ 210 VIR_CLIENT_TRANS_TLS, /* connection via encrypted TCP socket */ 211 212 # ifdef VIR_ENUM_SENTINELS 213 VIR_CLIENT_TRANS_LAST 214 # endif 215 } virClientTransport; 216 217 int virAdmServerListClients(virAdmServerPtr srv, 218 virAdmClientPtr **clients, 219 unsigned int flags); 220 221 virAdmClientPtr 222 virAdmServerLookupClient(virAdmServerPtr srv, 223 unsigned long long id, 224 unsigned int flags); 225 226 /* Client identity info */ 227 228 /** 229 * VIR_CLIENT_INFO_READONLY: 230 * Macro represents client's connection permission, whether the client is 231 * connected in read-only mode or just the opposite - read-write, 232 * as VIR_TYPED_PARAM_BOOLEAN. 233 * 234 * NOTE: This attribute is read-only and any attempt to set it will be denied 235 * by daemon 236 */ 237 238 # define VIR_CLIENT_INFO_READONLY "readonly" 239 240 /** 241 * VIR_CLIENT_INFO_SOCKET_ADDR: 242 * Macro represents clients network socket address in a standard URI format: 243 * (IPv4|[IPv6]):port, as VIR_TYPED_PARAM_STRING. 244 * 245 * NOTE: This attribute is read-only and any attempt to set it will be denied 246 * by daemon 247 */ 248 249 # define VIR_CLIENT_INFO_SOCKET_ADDR "sock_addr" 250 251 /** 252 * VIR_CLIENT_INFO_SASL_USER_NAME: 253 * Macro represents client's SASL user name, if SASL authentication is enabled 254 * on the remote host, as VIR_TYPED_PARAM_STRING. 255 * 256 * NOTE: This attribute is read-only and any attempt to set it will be denied 257 * by daemon 258 */ 259 260 # define VIR_CLIENT_INFO_SASL_USER_NAME "sasl_user_name" 261 262 /** 263 * VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME: 264 * Macro represents the 'distinguished name' field in X509 certificate the 265 * client used to establish a TLS session with remote host, as 266 * VIR_TYPED_PARAM_STRING. 267 * 268 * NOTE: This attribute is read-only and any attempt to set it will be denied 269 * by daemon 270 */ 271 272 # define VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME "tls_x509_dname" 273 274 /** 275 * VIR_CLIENT_INFO_UNIX_USER_ID: 276 * Macro represents UNIX UID the client process is running with. Only relevant 277 * for clients connected locally, i.e. via a UNIX socket, 278 * as VIR_TYPED_PARAM_INT. 279 * 280 * NOTE: This attribute is read-only and any attempt to set it will be denied 281 * by daemon 282 */ 283 284 # define VIR_CLIENT_INFO_UNIX_USER_ID "unix_user_id" 285 286 /** 287 * VIR_CLIENT_INFO_UNIX_USER_NAME: 288 * Macro represents the user name that is bound to the client process's UID it 289 * is running with. Only relevant for clients connected locally, i.e. via a 290 * UNIX socket, as VIR_TYPED_PARAM_STRING. 291 * 292 * NOTE: This attribute is read-only and any attempt to set it will be denied 293 * by daemon 294 */ 295 296 # define VIR_CLIENT_INFO_UNIX_USER_NAME "unix_user_name" 297 298 /** 299 * VIR_CLIENT_INFO_UNIX_GROUP_ID: 300 * Macro represents UNIX GID the client process is running with. Only relevant 301 * for clients connected locally, i.e. via a UNIX socket, 302 * as VIR_TYPED_PARAM_INT. 303 * 304 * NOTE: This attribute is read-only and any attempt to set it will be denied 305 * by daemon 306 */ 307 308 # define VIR_CLIENT_INFO_UNIX_GROUP_ID "unix_group_id" 309 310 /** 311 * VIR_CLIENT_INFO_UNIX_GROUP_NAME: 312 * Macro represents the group name that is bound to the client process's GID it 313 * is running with. Only relevant for clients connected locally, i.e. via a 314 * UNIX socket, as VIR_TYPED_PARAM_STRING. 315 * 316 * NOTE: This attribute is read-only and any attempt to set it will be denied 317 * by daemon 318 */ 319 320 # define VIR_CLIENT_INFO_UNIX_GROUP_NAME "unix_group_name" 321 322 /** 323 * VIR_CLIENT_INFO_UNIX_PROCESS_ID: 324 * Macro represents the client process's pid it is running with. Only relevant 325 * for clients connected locally, i.e. via a UNIX socket, 326 * as VIR_TYPED_PARAM_INT. 327 * 328 * NOTE: This attribute is read-only and any attempt to set it will be denied 329 * by daemon 330 */ 331 332 # define VIR_CLIENT_INFO_UNIX_PROCESS_ID "unix_process_id" 333 334 /** 335 * VIR_CLIENT_INFO_SELINUX_CONTEXT: 336 * Macro represents the client's (peer's) SELinux context and this can either 337 * be at socket layer or at transport layer, depending on the connection type, 338 * as VIR_TYPED_PARAM_STRING. 339 * 340 * NOTE: This attribute is read-only and any attempt to set it will be denied 341 * by daemon 342 */ 343 344 # define VIR_CLIENT_INFO_SELINUX_CONTEXT "selinux_context" 345 346 int virAdmClientGetInfo(virAdmClientPtr client, 347 virTypedParameterPtr *params, 348 int *nparams, 349 unsigned int flags); 350 351 int virAdmClientClose(virAdmClientPtr client, unsigned int flags); 352 353 /* Manage per-server client limits */ 354 355 /** 356 * VIR_SERVER_CLIENTS_MAX: 357 * Macro for per-server nclients_max limit: represents the upper limit to 358 * number of clients connected to the server, as uint. 359 */ 360 361 # define VIR_SERVER_CLIENTS_MAX "nclients_max" 362 363 /** 364 * VIR_SERVER_CLIENTS_CURRENT: 365 * Macro for per-server nclients attribute: represents the current number of 366 * clients connected to the server, as VIR_TYPED_PARAM_UINT. 367 * 368 * NOTE: This attribute is read-only and any attempt to set it will be denied 369 * by daemon 370 */ 371 372 # define VIR_SERVER_CLIENTS_CURRENT "nclients" 373 374 /** 375 * VIR_SERVER_CLIENTS_UNAUTH_MAX: 376 * Macro for per-server nclients_unauth_max limit: represents the upper limit 377 * to number of clients connected to the server, but not authenticated yet, 378 * as VIR_TYPED_PARAM_UINT. 379 */ 380 381 # define VIR_SERVER_CLIENTS_UNAUTH_MAX "nclients_unauth_max" 382 383 /** 384 * VIR_SERVER_CLIENTS_UNAUTH_CURRENT: 385 * Macro for per-server nclients_unauth attribute: represents the current 386 * number of clients connected to the server, but not authenticated yet, 387 * as VIR_TYPED_PARAM_UINT. 388 * 389 * NOTE: This attribute is read-only and any attempt to set it will be denied 390 * by daemon 391 */ 392 393 # define VIR_SERVER_CLIENTS_UNAUTH_CURRENT "nclients_unauth" 394 395 int virAdmServerGetClientLimits(virAdmServerPtr srv, 396 virTypedParameterPtr *params, 397 int *nparams, 398 unsigned int flags); 399 400 int virAdmServerSetClientLimits(virAdmServerPtr srv, 401 virTypedParameterPtr params, 402 int nparams, 403 unsigned int flags); 404 405 int virAdmServerUpdateTlsFiles(virAdmServerPtr srv, 406 unsigned int flags); 407 408 int virAdmConnectGetLoggingOutputs(virAdmConnectPtr conn, 409 char **outputs, 410 unsigned int flags); 411 412 int virAdmConnectGetLoggingFilters(virAdmConnectPtr conn, 413 char **filters, 414 unsigned int flags); 415 416 int virAdmConnectSetLoggingOutputs(virAdmConnectPtr conn, 417 const char *outputs, 418 unsigned int flags); 419 420 int virAdmConnectSetLoggingFilters(virAdmConnectPtr conn, 421 const char *filters, 422 unsigned int flags); 423 424 # ifdef __cplusplus 425 } 426 # endif 427 428 #endif /* LIBVIRT_ADMIN_H */ 429