1 /*
2 * libvirt-admin.c
3 *
4 * Copyright (C) 2014-2015 Red Hat, Inc.
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library. If not, see
18 * <http://www.gnu.org/licenses/>.
19 */
20
21 #include <config.h>
22
23 #include "internal.h"
24 #include "datatypes.h"
25 #include "configmake.h"
26
27 #include "viralloc.h"
28 #include "virconf.h"
29 #include "virlog.h"
30 #include "virnetclient.h"
31 #include "virobject.h"
32 #include "virstring.h"
33 #include "viruri.h"
34 #include "virutil.h"
35 #include "viruuid.h"
36
37 #define VIR_FROM_THIS VIR_FROM_ADMIN
38
39
40 VIR_LOG_INIT("libvirt-admin");
41
42 #include "admin_remote.c"
43
44 static bool virAdmGlobalError;
45 static virOnceControl virAdmGlobalOnce = VIR_ONCE_CONTROL_INITIALIZER;
46
47 static void
virAdmGlobalInit(void)48 virAdmGlobalInit(void)
49 {
50 /* It would be nice if we could trace the use of this call, to
51 * help diagnose in log files if a user calls something other than
52 * virAdmConnectOpen first. But we can't rely on VIR_DEBUG working
53 * until after initialization is complete, and since this is
54 * one-shot, we never get here again. */
55 if (virErrorInitialize() < 0)
56 goto error;
57
58 virLogSetFromEnv();
59
60 #ifdef WITH_LIBINTL_H
61 if (!bindtextdomain(PACKAGE, LOCALEDIR))
62 goto error;
63 #endif /* WITH_LIBINTL_H */
64
65 if (!VIR_CLASS_NEW(remoteAdminPriv, virClassForObjectLockable()))
66 goto error;
67
68 return;
69 error:
70 virAdmGlobalError = true;
71 }
72
73 /**
74 * virAdmInitialize:
75 *
76 * Initialize the library.
77 *
78 * This method is automatically invoked by virAdmConnectOpen() API. Therefore,
79 * in most cases it is unnecessary to call this method manually, unless an
80 * event loop should be set up by calling virEventRegisterImpl() or the error
81 * reporting of the first connection attempt with virSetErrorFunc() should be
82 * altered prior to setting up connections. If the latter is the case, it is
83 * necessary for the application to call virAdmInitialize.
84 *
85 * Returns 0 in case of success, -1 in case of error
86 */
87 int
virAdmInitialize(void)88 virAdmInitialize(void)
89 {
90 if (virOnce(&virAdmGlobalOnce, virAdmGlobalInit) < 0)
91 return -1;
92
93 if (virAdmGlobalError)
94 return -1;
95
96 return 0;
97 }
98
99 static char *
getSocketPath(virURI * uri)100 getSocketPath(virURI *uri)
101 {
102 g_autofree char *rundir = virGetUserRuntimeDirectory();
103 g_autofree char *sock_path = NULL;
104 size_t i = 0;
105
106 if (!uri)
107 return NULL;
108
109
110 for (i = 0; i < uri->paramsCount; i++) {
111 virURIParam *param = &uri->params[i];
112
113 if (STREQ(param->name, "socket")) {
114 g_free(sock_path);
115 sock_path = g_strdup(param->value);
116 } else {
117 virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
118 _("Unknown URI parameter '%s'"), param->name);
119 return NULL;
120 }
121 }
122
123 if (!sock_path) {
124 g_autofree char *sockbase = NULL;
125 bool legacy = false;
126
127 if (!uri->scheme) {
128 virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
129 "%s", _("No URI scheme specified"));
130 return NULL;
131 }
132 if (STREQ(uri->scheme, "libvirtd")) {
133 legacy = true;
134 } else if (!STRPREFIX(uri->scheme, "virt")) {
135 virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
136 _("Unsupported URI scheme '%s'"),
137 uri->scheme);
138 return NULL;
139 }
140
141 if (legacy) {
142 sockbase = g_strdup("libvirt-admin-sock");
143 } else {
144 sockbase = g_strdup_printf("%s-admin-sock", uri->scheme);
145 }
146
147 if (STREQ_NULLABLE(uri->path, "/system")) {
148 sock_path = g_strdup_printf(RUNSTATEDIR "/libvirt/%s", sockbase);
149 } else if (STREQ_NULLABLE(uri->path, "/session")) {
150 sock_path = g_strdup_printf("%s/%s", rundir, sockbase);
151 } else {
152 virReportError(VIR_ERR_CONFIG_UNSUPPORTED,
153 _("Invalid URI path '%s', try '/system'"),
154 NULLSTR_EMPTY(uri->path));
155 return NULL;
156 }
157 }
158
159 return g_steal_pointer(&sock_path);
160 }
161
162 static int
virAdmGetDefaultURI(virConf * conf,char ** uristr)163 virAdmGetDefaultURI(virConf *conf, char **uristr)
164 {
165 const char *defname = getenv("LIBVIRT_ADMIN_DEFAULT_URI");
166 if (defname && *defname) {
167 *uristr = g_strdup(defname);
168 VIR_DEBUG("Using LIBVIRT_ADMIN_DEFAULT_URI '%s'", *uristr);
169 } else {
170 if (virConfGetValueString(conf, "uri_default", uristr) < 0)
171 return -1;
172
173 if (*uristr) {
174 VIR_DEBUG("Using config file uri '%s'", *uristr);
175 } else {
176 /* Since we can't probe connecting via any hypervisor driver as libvirt
177 * does, if no explicit URI was given and neither the environment
178 * variable, nor the configuration parameter had previously been set,
179 * we set the default admin server URI to 'libvirtd:///system' or
180 * 'libvirtd:///session' depending on the process's EUID.
181 */
182 if (geteuid() == 0) {
183 *uristr = g_strdup("libvirtd:///system");
184 } else {
185 *uristr = g_strdup("libvirtd:///session");
186 }
187 }
188 }
189
190 return 0;
191 }
192
193 /**
194 * virAdmConnectOpen:
195 * @name: uri of the daemon to connect to, NULL for default
196 * @flags: bitwise-OR of virConnectFlags; so far the only supported flag is
197 * VIR_CONNECT_NO_ALIASES
198 *
199 * Opens connection to admin interface of the daemon.
200 *
201 * Returns @virAdmConnectPtr object or NULL on error
202 */
203 virAdmConnectPtr
virAdmConnectOpen(const char * name,unsigned int flags)204 virAdmConnectOpen(const char *name, unsigned int flags)
205 {
206 g_autofree char *sock_path = NULL;
207 char *alias = NULL;
208 virAdmConnectPtr conn = NULL;
209 g_autoptr(virConf) conf = NULL;
210 g_autofree char *uristr = NULL;
211
212 if (virAdmInitialize() < 0)
213 goto error;
214
215 VIR_DEBUG("name=%s flags=0x%x", NULLSTR(name), flags);
216 virResetLastError();
217
218 if (!(conn = virAdmConnectNew()))
219 goto error;
220
221 if (virConfLoadConfig(&conf, "libvirt-admin.conf") < 0)
222 goto error;
223
224 if (name) {
225 uristr = g_strdup(name);
226 } else {
227 if (virAdmGetDefaultURI(conf, &uristr) < 0)
228 goto error;
229 }
230
231 if ((!(flags & VIR_CONNECT_NO_ALIASES) &&
232 virURIResolveAlias(conf, uristr, &alias) < 0))
233 goto error;
234
235 if (alias) {
236 g_free(uristr);
237 uristr = alias;
238 }
239
240 if (!(conn->uri = virURIParse(uristr)))
241 goto error;
242
243 if (!(sock_path = getSocketPath(conn->uri)))
244 goto error;
245
246 if (!(conn->privateData = remoteAdminPrivNew(sock_path)))
247 goto error;
248
249 conn->privateDataFreeFunc = remoteAdminPrivFree;
250
251 if (remoteAdminConnectOpen(conn, flags) < 0)
252 goto error;
253
254 return conn;
255
256 error:
257 virDispatchError(NULL);
258 virObjectUnref(conn);
259 return NULL;
260 }
261
262 /**
263 * virAdmConnectClose:
264 * @conn: pointer to admin connection to close
265 *
266 * This function closes the admin connection to the Hypervisor. This should not
267 * be called if further interaction with the Hypervisor are needed especially if
268 * there is running domain which need further monitoring by the application.
269 *
270 * Connections are reference counted; the count is explicitly increased by the
271 * initial virAdmConnectOpen, as well as virAdmConnectRef; it is also temporarily
272 * increased by other API that depend on the connection remaining alive. The
273 * open and every virAdmConnectRef call should have a matching
274 * virAdmConnectClose, and all other references will be released after the
275 * corresponding operation completes.
276 *
277 * Returns a positive number if at least 1 reference remains on success. The
278 * returned value should not be assumed to be the total reference count. A
279 * return of 0 implies no references remain and the connection is closed and
280 * memory has been freed. A return of -1 implies a failure.
281 *
282 * It is possible for the last virAdmConnectClose to return a positive value if
283 * some other object still has a temporary reference to the connection, but the
284 * application should not try to further use a connection after the
285 * virAdmConnectClose that matches the initial open.
286 */
287 int
virAdmConnectClose(virAdmConnectPtr conn)288 virAdmConnectClose(virAdmConnectPtr conn)
289 {
290 VIR_DEBUG("conn=%p", conn);
291
292 virResetLastError();
293 if (!conn)
294 return 0;
295
296 virCheckAdmConnectReturn(conn, -1);
297
298 virAdmConnectWatchDispose();
299 virObjectUnref(conn);
300 if (virAdmConnectWasDisposed())
301 return 0;
302 return 1;
303 }
304
305
306 /**
307 * virAdmConnectRef:
308 * @conn: the connection to hold a reference on
309 *
310 * Increment the reference count on the connection. For each additional call to
311 * this method, there shall be a corresponding call to virAdmConnectClose to
312 * release the reference count, once the caller no longer needs the reference to
313 * this object.
314 *
315 * This method is typically useful for applications where multiple threads are
316 * using a connection, and it is required that the connection remain open until
317 * all threads have finished using it. I.e., each new thread using a connection
318 * would increment the reference count.
319 *
320 * Returns 0 in case of success, -1 in case of failure
321 */
322 int
virAdmConnectRef(virAdmConnectPtr conn)323 virAdmConnectRef(virAdmConnectPtr conn)
324 {
325 VIR_DEBUG("conn=%p", conn);
326
327 virResetLastError();
328 virCheckAdmConnectReturn(conn, -1);
329
330 virObjectRef(conn);
331
332 return 0;
333 }
334
335 /**
336 * virAdmGetVersion:
337 * @libVer: where to store the library version
338 *
339 * Provides version information. @libVer is the version of the library and will
340 * always be set unless an error occurs in which case an error code and a
341 * generic message will be returned. @libVer format is as follows:
342 * major * 1,000,000 + minor * 1,000 + release.
343 *
344 * NOTE: To get the remote side library version use virAdmConnectGetLibVersion
345 * instead.
346 *
347 * Returns 0 on success, -1 in case of an error.
348 */
349 int
virAdmGetVersion(unsigned long long * libVer)350 virAdmGetVersion(unsigned long long *libVer)
351 {
352 if (virAdmInitialize() < 0)
353 goto error;
354
355 VIR_DEBUG("libVer=%p", libVer);
356
357 virResetLastError();
358 if (!libVer)
359 goto error;
360 *libVer = LIBVIR_VERSION_NUMBER;
361
362 return 0;
363
364 error:
365 virDispatchError(NULL);
366 return -1;
367 }
368
369 /**
370 * virAdmConnectIsAlive:
371 * @conn: connection to admin server
372 *
373 * Decide whether the connection to the admin server is alive or not.
374 * Connection is considered alive if the channel it is running over is not
375 * closed.
376 *
377 * Returns 1, if the connection is alive, 0 if there isn't an existing
378 * connection at all or the channel has already been closed, or -1 on error.
379 */
380 int
virAdmConnectIsAlive(virAdmConnectPtr conn)381 virAdmConnectIsAlive(virAdmConnectPtr conn)
382 {
383 bool ret;
384 remoteAdminPriv *priv = NULL;
385
386 VIR_DEBUG("conn=%p", conn);
387
388 virResetLastError();
389
390 if (!conn)
391 return 0;
392
393 virCheckAdmConnectReturn(conn, -1);
394
395 priv = conn->privateData;
396 virObjectLock(priv);
397 ret = virNetClientIsOpen(priv->client);
398 virObjectUnlock(priv);
399
400 return ret;
401 }
402
403 /**
404 * virAdmConnectGetURI:
405 * @conn: pointer to an admin connection
406 *
407 * String returned by this method is normally the same as the string passed
408 * to the virAdmConnectOpen. Even if NULL was passed to virAdmConnectOpen,
409 * this method returns a non-null URI string.
410 *
411 * Returns an URI string related to the connection or NULL in case of an error.
412 * Caller is responsible for freeing the string.
413 */
414 char *
virAdmConnectGetURI(virAdmConnectPtr conn)415 virAdmConnectGetURI(virAdmConnectPtr conn)
416 {
417 char *uri = NULL;
418 VIR_DEBUG("conn=%p", conn);
419
420 virResetLastError();
421
422 virCheckAdmConnectReturn(conn, NULL);
423
424 if (!(uri = virURIFormat(conn->uri)))
425 virDispatchError(NULL);
426
427 return uri;
428 }
429
430 /**
431 * virAdmConnectRegisterCloseCallback:
432 * @conn: connection to admin server
433 * @cb: callback to be invoked upon connection close
434 * @opaque: user data to pass to @cb
435 * @freecb: callback to free @opaque
436 *
437 * Registers a callback to be invoked when the connection
438 * is closed. This callback is invoked when there is any
439 * condition that causes the socket connection to the
440 * hypervisor to be closed.
441 *
442 * The @freecb must not invoke any other libvirt public
443 * APIs, since it is not called from a re-entrant safe
444 * context.
445 *
446 * Returns 0 on success, -1 on error
447 */
virAdmConnectRegisterCloseCallback(virAdmConnectPtr conn,virAdmConnectCloseFunc cb,void * opaque,virFreeCallback freecb)448 int virAdmConnectRegisterCloseCallback(virAdmConnectPtr conn,
449 virAdmConnectCloseFunc cb,
450 void *opaque,
451 virFreeCallback freecb)
452 {
453 VIR_DEBUG("conn=%p", conn);
454
455 virResetLastError();
456
457 virCheckAdmConnectReturn(conn, -1);
458
459 virObjectRef(conn);
460
461 virObjectLock(conn->closeCallback);
462
463 virCheckNonNullArgGoto(cb, error);
464
465 if (conn->closeCallback->callback) {
466 virReportError(VIR_ERR_OPERATION_INVALID, "%s",
467 _("A close callback is already registered"));
468 goto error;
469 }
470
471 conn->closeCallback->conn = conn;
472 conn->closeCallback->callback = cb;
473 conn->closeCallback->opaque = opaque;
474 conn->closeCallback->freeCallback = freecb;
475
476 virObjectUnlock(conn->closeCallback);
477
478 return 0;
479
480 error:
481 virObjectUnlock(conn->closeCallback);
482 virDispatchError(NULL);
483 virObjectUnref(conn);
484 return -1;
485
486 }
487
488 /**
489 * virAdmConnectUnregisterCloseCallback:
490 * @conn: pointer to connection object
491 * @cb: pointer to the current registered callback
492 *
493 * Unregisters the callback previously set with the
494 * virAdmConnectRegisterCloseCallback method. The callback
495 * will no longer receive notifications when the connection
496 * closes. If a virFreeCallback was provided at time of
497 * registration, it will be invoked.
498 *
499 * Returns 0 on success, -1 on error
500 */
virAdmConnectUnregisterCloseCallback(virAdmConnectPtr conn,virAdmConnectCloseFunc cb)501 int virAdmConnectUnregisterCloseCallback(virAdmConnectPtr conn,
502 virAdmConnectCloseFunc cb)
503 {
504 VIR_DEBUG("conn=%p", conn);
505
506 virResetLastError();
507
508 virCheckAdmConnectReturn(conn, -1);
509 virCheckNonNullArgGoto(cb, error);
510
511 if (virAdmConnectCloseCallbackDataUnregister(conn->closeCallback, cb) < 0)
512 goto error;
513
514 return 0;
515 error:
516 virDispatchError(NULL);
517 return -1;
518 }
519
520 /**
521 * virAdmConnectGetLibVersion:
522 * @conn: pointer to an active admin connection
523 * @libVer: stores the current remote libvirt version number
524 *
525 * Retrieves the remote side libvirt version used by the daemon. Format
526 * returned in @libVer is of a following pattern:
527 * major * 1,000,000 + minor * 1,000 + release.
528 *
529 * Returns 0 on success, -1 on failure and @libVer follows this format:
530 */
virAdmConnectGetLibVersion(virAdmConnectPtr conn,unsigned long long * libVer)531 int virAdmConnectGetLibVersion(virAdmConnectPtr conn,
532 unsigned long long *libVer)
533 {
534 VIR_DEBUG("conn=%p, libVir=%p", conn, libVer);
535
536 virResetLastError();
537
538 virCheckAdmConnectReturn(conn, -1);
539 virCheckNonNullArgReturn(libVer, -1);
540
541 if (remoteAdminConnectGetLibVersion(conn, libVer) < 0)
542 goto error;
543
544 return 0;
545 error:
546 virDispatchError(NULL);
547 return -1;
548 }
549
550 /**
551 * virAdmServerGetName:
552 * @srv: a server object
553 *
554 * Get the public name for specified server
555 *
556 * Returns a pointer to the name or NULL. The string doesn't need to be
557 * deallocated since its lifetime will be the same as the server object.
558 */
559 const char *
virAdmServerGetName(virAdmServerPtr srv)560 virAdmServerGetName(virAdmServerPtr srv)
561 {
562 VIR_DEBUG("server=%p", srv);
563
564 virResetLastError();
565 virCheckAdmServerReturn(srv, NULL);
566
567 return srv->name;
568 }
569
570 /**
571 * virAdmServerFree:
572 * @srv: server object
573 *
574 * Release the server object. The running instance is kept alive.
575 * The data structure is freed and should not be used thereafter.
576 *
577 * Returns 0 on success, -1 on failure.
578 */
virAdmServerFree(virAdmServerPtr srv)579 int virAdmServerFree(virAdmServerPtr srv)
580 {
581 VIR_DEBUG("server=%p", srv);
582
583 virResetLastError();
584
585 if (!srv)
586 return 0;
587
588 virCheckAdmServerReturn(srv, -1);
589
590 virObjectUnref(srv);
591 return 0;
592 }
593
594 /**
595 * virAdmClientGetID:
596 * @client: a client object
597 *
598 * Get client's unique numeric ID.
599 *
600 * Returns numeric value used for client's ID or -1 in case of an error.
601 */
602 unsigned long long
virAdmClientGetID(virAdmClientPtr client)603 virAdmClientGetID(virAdmClientPtr client)
604 {
605 VIR_DEBUG("client=%p", client);
606
607 virResetLastError();
608 virCheckAdmClientReturn(client, -1);
609 return client->id;
610 }
611
612 /**
613 * virAdmClientGetTimestamp:
614 * @client: a client object
615 *
616 * Get client's connection time.
617 * A situation may happen, that some clients had connected prior to the update
618 * to admin API, thus, libvirt assigns these clients epoch time to express that
619 * it doesn't know when the client connected.
620 *
621 * Returns client's connection timestamp (seconds from epoch in UTC) or 0
622 * (epoch time) if libvirt doesn't have any information about client's
623 * connection time, or -1 in case of an error.
624 */
625 long long
virAdmClientGetTimestamp(virAdmClientPtr client)626 virAdmClientGetTimestamp(virAdmClientPtr client)
627 {
628 VIR_DEBUG("client=%p", client);
629
630 virResetLastError();
631 virCheckAdmClientReturn(client, -1);
632 return client->timestamp;
633 }
634
635 /**
636 * virAdmClientGetTransport:
637 * @client: a client object
638 *
639 * Get client's connection transport type. This information can be helpful to
640 * differentiate between clients connected locally or remotely. An exception to
641 * this would be SSH which is one of libvirt's supported transports.
642 * Although SSH creates a channel between two (preferably) remote endpoints,
643 * the client process libvirt spawns automatically on the remote side will
644 * still connect to a UNIX socket, thus becoming indistinguishable from any
645 * other locally connected clients.
646 *
647 * Returns integer representation of the connection transport used by @client
648 * (this will be one of virClientTransport) or -1 in case of an error.
649 */
650 int
virAdmClientGetTransport(virAdmClientPtr client)651 virAdmClientGetTransport(virAdmClientPtr client)
652 {
653 VIR_DEBUG("client=%p", client);
654
655 virResetLastError();
656 virCheckAdmClientReturn(client, -1);
657 return client->transport;
658 }
659
660 /**
661 * virAdmClientFree:
662 * @client: a client object
663 *
664 * Release the client object. The running instance is kept alive. The data
665 * structure is freed and should not be used thereafter.
666 *
667 * Returns 0 in success, -1 on failure.
668 */
virAdmClientFree(virAdmClientPtr client)669 int virAdmClientFree(virAdmClientPtr client)
670 {
671 VIR_DEBUG("client=%p", client);
672
673 virResetLastError();
674
675 if (!client)
676 return 0;
677
678 virCheckAdmClientReturn(client, -1);
679
680 virObjectUnref(client);
681 return 0;
682 }
683
684 /**
685 * virAdmConnectListServers:
686 * @conn: daemon connection reference
687 * @servers: Pointer to a list to store an array containing objects or NULL
688 * if the list is not required (number of servers only)
689 * @flags: extra flags; not used yet, so callers should always pass 0
690 *
691 * Collect list of all servers provided by daemon the client is connected to.
692 *
693 * Returns the number of servers available on daemon side or -1 in case of a
694 * failure, setting @servers to NULL. There is a guaranteed extra element set
695 * to NULL in the @servers list returned to make the iteration easier, excluding
696 * this extra element from the final count.
697 * Caller is responsible to call virAdmServerFree() on each list element,
698 * followed by freeing @servers.
699 */
700 int
virAdmConnectListServers(virAdmConnectPtr conn,virAdmServerPtr ** servers,unsigned int flags)701 virAdmConnectListServers(virAdmConnectPtr conn,
702 virAdmServerPtr **servers,
703 unsigned int flags)
704 {
705 int ret = -1;
706
707 VIR_DEBUG("conn=%p, servers=%p, flags=0x%x", conn, servers, flags);
708
709 virResetLastError();
710
711 if (servers)
712 *servers = NULL;
713
714 virCheckAdmConnectReturn(conn, -1);
715 if ((ret = remoteAdminConnectListServers(conn, servers, flags)) < 0)
716 goto error;
717
718 return ret;
719 error:
720 virDispatchError(NULL);
721 return -1;
722 }
723
724 /**
725 * virAdmConnectLookupServer:
726 * @conn: daemon connection reference
727 * @name: name of the server too lookup
728 * @flags: extra flags; not used yet, so callers should always pass 0
729 *
730 * Try to lookup a server on the given daemon based on @name.
731 *
732 * virAdmServerFree() should be used to free the resources after the
733 * server object is no longer needed.
734 *
735 * Returns the requested server or NULL in case of failure. If the
736 * server cannot be found, then VIR_ERR_NO_SERVER error is raised.
737 */
738 virAdmServerPtr
virAdmConnectLookupServer(virAdmConnectPtr conn,const char * name,unsigned int flags)739 virAdmConnectLookupServer(virAdmConnectPtr conn,
740 const char *name,
741 unsigned int flags)
742 {
743 virAdmServerPtr ret = NULL;
744
745 VIR_DEBUG("conn=%p, name=%s, flags=0x%x", conn, NULLSTR(name), flags);
746 virResetLastError();
747
748 virCheckAdmConnectGoto(conn, cleanup);
749 virCheckNonNullArgGoto(name, cleanup);
750
751 ret = remoteAdminConnectLookupServer(conn, name, flags);
752 cleanup:
753 if (!ret)
754 virDispatchError(NULL);
755 return ret;
756 }
757
758 /**
759 * virAdmServerGetThreadPoolParameters:
760 * @srv: a valid server object reference
761 * @params: pointer to a list of typed parameters which will be allocated
762 * to store all returned parameters
763 * @nparams: pointer which will hold the number of params returned in @params
764 * @flags: extra flags; not used yet, so callers should always pass 0
765 *
766 * Retrieves threadpool parameters from @srv. Upon successful completion,
767 * @params will be allocated automatically to hold all returned data, setting
768 * @nparams accordingly.
769 * When extracting parameters from @params, following search keys are
770 * supported:
771 * VIR_THREADPOOL_WORKERS_MIN
772 * VIR_THREADPOOL_WORKERS_MAX
773 * VIR_THREADPOOL_WORKERS_PRIORITY
774 * VIR_THREADPOOL_WORKERS_FREE
775 * VIR_THREADPOOL_WORKERS_CURRENT
776 *
777 * Returns 0 on success, -1 in case of an error.
778 */
779 int
virAdmServerGetThreadPoolParameters(virAdmServerPtr srv,virTypedParameterPtr * params,int * nparams,unsigned int flags)780 virAdmServerGetThreadPoolParameters(virAdmServerPtr srv,
781 virTypedParameterPtr *params,
782 int *nparams,
783 unsigned int flags)
784 {
785 int ret = -1;
786
787 VIR_DEBUG("srv=%p, params=%p, nparams=%p, flags=0x%x",
788 srv, params, nparams, flags);
789
790 virResetLastError();
791
792 virCheckAdmServerReturn(srv, -1);
793 virCheckNonNullArgGoto(params, error);
794
795 if ((ret = remoteAdminServerGetThreadPoolParameters(srv, params, nparams,
796 flags)) < 0)
797 goto error;
798
799 return ret;
800 error:
801 virDispatchError(NULL);
802 return -1;
803 }
804
805 /**
806 * virAdmServerSetThreadPoolParameters:
807 * @srv: a valid server object reference
808 * @params: pointer to threadpool typed parameter objects
809 * @nparams: number of parameters in @params
810 * @flags: extra flags; not used yet, so callers should always pass 0
811 *
812 * Change server threadpool parameters according to @params. Note that some
813 * tunables are read-only, thus any attempt to set them will result in a
814 * failure.
815 *
816 * Returns 0 on success, -1 in case of an error.
817 */
818 int
virAdmServerSetThreadPoolParameters(virAdmServerPtr srv,virTypedParameterPtr params,int nparams,unsigned int flags)819 virAdmServerSetThreadPoolParameters(virAdmServerPtr srv,
820 virTypedParameterPtr params,
821 int nparams,
822 unsigned int flags)
823 {
824 VIR_DEBUG("srv=%p, params=%p, nparams=%d, flags=0x%x",
825 srv, params, nparams, flags);
826
827 virResetLastError();
828
829 virCheckAdmServerReturn(srv, -1);
830 virCheckNonNullArgGoto(params, error);
831 virCheckNonNegativeArgGoto(nparams, error);
832
833 if (remoteAdminServerSetThreadPoolParameters(srv, params,
834 nparams, flags) < 0)
835 goto error;
836
837 return 0;
838 error:
839 virDispatchError(NULL);
840 return -1;
841 }
842
843 /**
844 * virAdmServerListClients:
845 * @srv: a valid server object reference
846 * @clients: pointer to a list to store an array containing objects or NULL
847 * if the list is not required (number of clients only)
848 * @flags: extra flags; not used yet, so callers should always pass 0
849 *
850 * Collect list of all clients connected to daemon on server @srv.
851 *
852 * Returns the number of clients connected to daemon on server @srv -1 in case
853 * of a failure, setting @clients to NULL. There is a guaranteed extra element
854 * set to NULL in the @clients list returned to make the iteration easier,
855 * excluding this extra element from the final count.
856 * Caller is responsible to call virAdmClientFree() on each list element,
857 * followed by freeing @clients.
858 */
859 int
virAdmServerListClients(virAdmServerPtr srv,virAdmClientPtr ** clients,unsigned int flags)860 virAdmServerListClients(virAdmServerPtr srv,
861 virAdmClientPtr **clients,
862 unsigned int flags)
863 {
864 int ret = -1;
865
866 VIR_DEBUG("srv=%p, clients=%p, flags=0x%x", srv, clients, flags);
867
868 virResetLastError();
869
870 if (clients)
871 *clients = NULL;
872
873 virCheckAdmServerReturn(srv, -1);
874 if ((ret = remoteAdminServerListClients(srv, clients, flags)) < 0)
875 goto error;
876
877 return ret;
878 error:
879 virDispatchError(NULL);
880 return -1;
881 }
882
883 /**
884 * virAdmServerLookupClient:
885 * @srv: a valid server object reference
886 * @id: ID of the client to lookup on server @srv
887 * @flags: extra flags; not used yet, so callers should always pass 0
888 *
889 * Try to lookup a client on the given server based on @id.
890 *
891 * virAdmClientFree() should be used to free the resources after the
892 * client object is no longer needed.
893 *
894 * Returns the requested client or NULL in case of failure. If the
895 * client could not be found, then VIR_ERR_NO_CLIENT error is raised.
896 */
897 virAdmClientPtr
virAdmServerLookupClient(virAdmServerPtr srv,unsigned long long id,unsigned int flags)898 virAdmServerLookupClient(virAdmServerPtr srv,
899 unsigned long long id,
900 unsigned int flags)
901 {
902 virAdmClientPtr ret = NULL;
903
904 VIR_DEBUG("srv=%p, id=%llu, flags=0x%x", srv, id, flags);
905 virResetLastError();
906
907 virCheckAdmServerGoto(srv, error);
908
909 if (!(ret = remoteAdminServerLookupClient(srv, id, flags)))
910 goto error;
911
912 return ret;
913 error:
914 virDispatchError(NULL);
915 return NULL;
916 }
917
918 /**
919 * virAdmClientGetInfo:
920 * @client: a client object reference
921 * @params: pointer to a list of typed parameters which will be allocated
922 * to store all returned parameters
923 * @nparams: pointer which will hold the number of params returned in @params
924 * @flags: extra flags; not used yet, so callers should always pass 0
925 *
926 * Extract identity information about a client. Attributes returned in @params
927 * are mostly transport-dependent, i.e. some attributes including client
928 * process's pid, gid, uid, or remote side's socket address are only available
929 * for a specific connection type - local vs remote.
930 * Other identity attributes like authentication method used
931 * (if authentication is enabled on the remote host), SELinux context, or
932 * an indicator whether client is connected via a read-only connection are
933 * independent of the connection transport.
934 *
935 * Note that the read-only connection indicator returns false for TCP/TLS
936 * clients because libvirt treats such connections as read-write by default,
937 * even though a TCP client is able to restrict access to certain APIs for
938 * itself.
939 *
940 * Returns 0 if the information has been successfully retrieved or -1 in case
941 * of an error.
942 */
943 int
virAdmClientGetInfo(virAdmClientPtr client,virTypedParameterPtr * params,int * nparams,unsigned int flags)944 virAdmClientGetInfo(virAdmClientPtr client,
945 virTypedParameterPtr *params,
946 int *nparams,
947 unsigned int flags)
948 {
949 int ret = -1;
950
951 VIR_DEBUG("client=%p, params=%p, nparams=%p, flags=0x%x",
952 client, params, nparams, flags);
953
954 virResetLastError();
955 virCheckAdmClientReturn(client, -1);
956 virCheckNonNullArgGoto(params, error);
957
958 if ((ret = remoteAdminClientGetInfo(client, params, nparams, flags)) < 0)
959 goto error;
960
961 return ret;
962 error:
963 virDispatchError(NULL);
964 return -1;
965 }
966
967 /**
968 * virAdmClientClose:
969 * @client: a valid client object reference
970 * @flags: extra flags; not used yet, so callers should always pass 0
971 *
972 * Close @client's connection to daemon forcefully.
973 *
974 * Returns 0 if the daemon's connection with @client was closed successfully
975 * or -1 in case of an error.
976 */
virAdmClientClose(virAdmClientPtr client,unsigned int flags)977 int virAdmClientClose(virAdmClientPtr client,
978 unsigned int flags)
979 {
980 int ret = -1;
981
982 VIR_DEBUG("client=%p, flags=0x%x", client, flags);
983 virResetLastError();
984
985 virCheckAdmClientGoto(client, error);
986
987 if ((ret = remoteAdminClientClose(client, flags)) < 0)
988 goto error;
989
990 return ret;
991 error:
992 virDispatchError(NULL);
993 return -1;
994 }
995
996 /**
997 * virAdmServerGetClientLimits:
998 * @srv: a valid server object reference
999 * @params: pointer to client limits object
1000 * (return value, allocated automatically)
1001 * @nparams: pointer to number of parameters returned in @params
1002 * @flags: extra flags; not used yet, so callers should always pass 0
1003 *
1004 * Retrieve client limits from server @srv. These include:
1005 * - current number of clients connected to @srv,
1006 * - maximum number of clients connected to @srv,
1007 * - current number of clients connected to @srv waiting for authentication,
1008 * - maximum number of clients connected to @srv that can be wainting for
1009 * authentication.
1010 *
1011 * Returns 0 on success, allocating @params to size returned in @nparams, or
1012 * -1 in case of an error. Caller is responsible for deallocating @params.
1013 */
1014 int
virAdmServerGetClientLimits(virAdmServerPtr srv,virTypedParameterPtr * params,int * nparams,unsigned int flags)1015 virAdmServerGetClientLimits(virAdmServerPtr srv,
1016 virTypedParameterPtr *params,
1017 int *nparams,
1018 unsigned int flags)
1019 {
1020 int ret = -1;
1021
1022 VIR_DEBUG("srv=%p, params=%p, nparams=%p, flags=0x%x",
1023 srv, params, nparams, flags);
1024 virResetLastError();
1025
1026 virCheckAdmServerGoto(srv, error);
1027
1028 if ((ret = remoteAdminServerGetClientLimits(srv, params,
1029 nparams, flags)) < 0)
1030 goto error;
1031
1032 return ret;
1033 error:
1034 virDispatchError(NULL);
1035 return -1;
1036 }
1037
1038 /**
1039 * virAdmServerSetClientLimits:
1040 * @srv: a valid server object reference
1041 * @params: pointer to client limits object
1042 * @nparams: number of parameters in @params
1043 * @flags: extra flags; not used yet, so callers should always pass 0
1044 *
1045 * Change client limits configuration on server @srv.
1046 *
1047 * Caller is responsible for allocating @params prior to calling this function.
1048 * See 'Manage per-server client limits' in libvirt-admin.h for
1049 * supported parameters in @params.
1050 *
1051 * Returns 0 if the limits have been changed successfully or -1 in case of an
1052 * error.
1053 */
1054 int
virAdmServerSetClientLimits(virAdmServerPtr srv,virTypedParameterPtr params,int nparams,unsigned int flags)1055 virAdmServerSetClientLimits(virAdmServerPtr srv,
1056 virTypedParameterPtr params,
1057 int nparams,
1058 unsigned int flags)
1059 {
1060 int ret = -1;
1061
1062 VIR_DEBUG("srv=%p, params=%p, nparams=%d, flags=0x%x", srv, params, nparams,
1063 flags);
1064 VIR_TYPED_PARAMS_DEBUG(params, nparams);
1065
1066 virResetLastError();
1067
1068 virCheckAdmServerGoto(srv, error);
1069 virCheckNonNullArgGoto(params, error);
1070 virCheckNonNegativeArgGoto(nparams, error);
1071
1072 if ((ret = remoteAdminServerSetClientLimits(srv, params, nparams,
1073 flags)) < 0)
1074 goto error;
1075
1076 return ret;
1077 error:
1078 virDispatchError(NULL);
1079 return ret;
1080 }
1081
1082 /**
1083 * virAdmServerUpdateTlsFiles:
1084 * @srv: a valid server object reference
1085 * @flags: extra flags; not used yet, so callers should always pass 0
1086 *
1087 * Notify server to update tls file, such as cacert, cacrl, server cert / key.
1088 *
1089 * Returns 0 if the TLS files have been updated successfully or -1 in case of an
1090 * error.
1091 */
1092 int
virAdmServerUpdateTlsFiles(virAdmServerPtr srv,unsigned int flags)1093 virAdmServerUpdateTlsFiles(virAdmServerPtr srv,
1094 unsigned int flags)
1095 {
1096 int ret = -1;
1097
1098 VIR_DEBUG("srv=%p, flags=0x%x", srv, flags);
1099 virResetLastError();
1100
1101 virCheckAdmServerGoto(srv, error);
1102
1103 if ((ret = remoteAdminServerUpdateTlsFiles(srv, flags)) < 0)
1104 goto error;
1105
1106 return ret;
1107 error:
1108 virDispatchError(NULL);
1109 return ret;
1110 }
1111
1112 /**
1113 * virAdmConnectGetLoggingOutputs:
1114 * @conn: pointer to an active admin connection
1115 * @outputs: pointer to a variable to store a string containing all currently
1116 * defined logging outputs on daemon (allocated automatically) or
1117 * NULL if just the number of defined outputs is required
1118 * @flags: extra flags; not used yet, so callers should always pass 0
1119 *
1120 * Retrieves a list of currently installed logging outputs. Outputs returned
1121 * are contained within an automatically allocated string and delimited by
1122 * spaces. The format of each output conforms to the format described in
1123 * daemon's configuration file (e.g. libvirtd.conf).
1124 *
1125 * To retrieve individual outputs, additional parsing needs to be done by the
1126 * caller. Caller is also responsible for freeing @outputs correctly.
1127 *
1128 * Returns the count of outputs in @outputs, or -1 in case of an error.
1129 */
1130 int
virAdmConnectGetLoggingOutputs(virAdmConnectPtr conn,char ** outputs,unsigned int flags)1131 virAdmConnectGetLoggingOutputs(virAdmConnectPtr conn,
1132 char **outputs,
1133 unsigned int flags)
1134 {
1135 int ret = -1;
1136
1137 VIR_DEBUG("conn=%p, flags=0x%x", conn, flags);
1138
1139 virResetLastError();
1140 virCheckAdmConnectReturn(conn, -1);
1141
1142 if ((ret = remoteAdminConnectGetLoggingOutputs(conn, outputs,
1143 flags)) < 0)
1144 goto error;
1145
1146 return ret;
1147 error:
1148 virDispatchError(NULL);
1149 return -1;
1150 }
1151
1152 /**
1153 * virAdmConnectGetLoggingFilters:
1154 * @conn: pointer to an active admin connection
1155 * @filters: pointer to a variable to store a string containing all currently
1156 * defined logging filters on daemon (allocated automatically) or
1157 * NULL if just the number of defined outputs is required
1158 * @flags: extra flags; not used yet, so callers should always pass 0
1159 *
1160 * Retrieves a list of currently installed logging filters. Filters returned
1161 * are contained within an automatically allocated string and delimited by
1162 * spaces. The format of each filter conforms to the format described in
1163 * daemon's configuration file (e.g. libvirtd.conf).
1164 *
1165 * To retrieve individual filters, additional parsing needs to be done by the
1166 * caller. Caller is also responsible for freeing @filters correctly.
1167 *
1168 * Returns the number of filters returned in @filters, or -1 in case of
1169 * an error.
1170 */
1171 int
virAdmConnectGetLoggingFilters(virAdmConnectPtr conn,char ** filters,unsigned int flags)1172 virAdmConnectGetLoggingFilters(virAdmConnectPtr conn,
1173 char **filters,
1174 unsigned int flags)
1175 {
1176 int ret = -1;
1177
1178 VIR_DEBUG("conn=%p, filters=%p, flags=0x%x",
1179 conn, filters, flags);
1180
1181 virResetLastError();
1182 virCheckAdmConnectReturn(conn, -1);
1183
1184 if ((ret = remoteAdminConnectGetLoggingFilters(conn, filters,
1185 flags)) < 0)
1186 goto error;
1187
1188 return ret;
1189 error:
1190 virDispatchError(NULL);
1191 return -1;
1192 }
1193
1194 /**
1195 * virAdmConnectSetLoggingOutputs:
1196 * @conn: pointer to an active admin connection
1197 * @outputs: pointer to a string containing a list of outputs to be defined
1198 * @flags: extra flags; not used yet, so callers should always pass 0
1199 *
1200 * Redefine the existing (set of) outputs(s) with a new one specified in
1201 * @outputs. If multiple outputs are specified, they need to be delimited by
1202 * spaces. The format of each output must conform to the format described in
1203 * daemon's configuration file (e.g. libvirtd.conf).
1204 *
1205 * To reset the existing (set of) output(s) to libvirt's defaults, an empty
1206 * string ("") or NULL should be passed in @outputs.
1207 *
1208 * Returns 0 if the new output or the set of outputs has been defined
1209 * successfully, or -1 in case of an error.
1210 */
1211 int
virAdmConnectSetLoggingOutputs(virAdmConnectPtr conn,const char * outputs,unsigned int flags)1212 virAdmConnectSetLoggingOutputs(virAdmConnectPtr conn,
1213 const char *outputs,
1214 unsigned int flags)
1215 {
1216 int ret = -1;
1217
1218 VIR_DEBUG("conn=%p, outputs=%s, flags=0x%x", conn, outputs, flags);
1219
1220 virResetLastError();
1221 virCheckAdmConnectReturn(conn, -1);
1222
1223 if ((ret = remoteAdminConnectSetLoggingOutputs(conn, outputs, flags)) < 0)
1224 goto error;
1225
1226 return ret;
1227 error:
1228 virDispatchError(NULL);
1229 return -1;
1230 }
1231
1232 /**
1233 * virAdmConnectSetLoggingFilters:
1234 * @conn: pointer to an active admin connection
1235 * @filters: pointer to a string containing a list of filters to be defined
1236 * @flags: extra flags; not used yet, so callers should always pass 0
1237 *
1238 * Redefine the existing (set of) filter(s) with a new one specified in
1239 * @filters. If multiple filters are specified, they need to be delimited by
1240 * spaces. The format of each filter must conform to the format described in
1241 * daemon's configuration file (e.g. libvirtd.conf).
1242 *
1243 * To clear the currently defined (set of) filter(s), pass either an empty
1244 * string ("") or NULL in @filters.
1245 *
1246 * Returns 0 if the new filter or the set of filters has been defined
1247 * successfully, or -1 in case of an error.
1248 */
1249 int
virAdmConnectSetLoggingFilters(virAdmConnectPtr conn,const char * filters,unsigned int flags)1250 virAdmConnectSetLoggingFilters(virAdmConnectPtr conn,
1251 const char *filters,
1252 unsigned int flags)
1253 {
1254 int ret = -1;
1255
1256 VIR_DEBUG("conn=%p, filters=%s, flags=0x%x", conn, filters, flags);
1257
1258 virResetLastError();
1259 virCheckAdmConnectReturn(conn, -1);
1260
1261 if ((ret = remoteAdminConnectSetLoggingFilters(conn, filters, flags)) < 0)
1262 goto error;
1263
1264 return ret;
1265 error:
1266 virDispatchError(NULL);
1267 return -1;
1268 }
1269