1PMDAROOTCONNECT(3) Library Functions Manual PMDAROOTCONNECT(3)
2
6 pmdaRootConnect, pmdaRootShutdown, pmdaRootContainerHostName, pmdaRoot‐
7 ContainerProcessID, pmdaRootContainerCGroupName, pmdaRootProcessStart,
8 pmdaRootProcessWait, pmdaRootProcessTerminate - privileged PCP collec‐
9 tor services
10
12 #include <pcp/pmapi.h>
13 #include <pcp/pmda.h>
14 int pmdaRootConnect(void);
16 void pmdaRootShutdown(int fd);
17 int pmdaRootContainerHostName(int fd, char *name, int namelen, char
18 *buffer, int buflen);
19 int pmdaRootContainerProcessID(int fd, char *name, int namelen);
20 int pmdaRootContainerCGroupName(int fd, char *name, int namelen, char
21 *buffer, int buflen);
22 int pmdaRootProcessStart(int fd, int ipctype, char *label, int
23 labellen, const char *args, int argslen, int *pid, int *infd,
24 int *outfd);
25 int pmdaRootProcessWait(int fd, int pid, int *status);
26 int pmdaRootProcessTerminate(int fd, int pid);
27 cc ... -lpcp_pmda -lpcp
29
31 pmdaRootConnect initializes an IPC channel between a PCP collector
32 process - either a PMDA(3) or pmcd(1) itself - and the pmdaroot(1)
33 server.
34 On success, the return value from pmdaRootConnect is a unix(7) domain
36 socket file descriptor, which can be subsequently passed to each of the
37 other APIs described here. This channel can be used to perform limited
38 privilege escalation for specific scenarios needed by PCP collector
39 services. The channel can be deactivated using the pmdaRootShutdown
40 interface.
41
43 Several interfaces are provided for access to the container facilities
44 of modern Linux distributions, as needed by various agents accessing
45 kernel features related to containers.
46 pmdaRootContainerHostName allows lookup of the current hostname for a
48 named container on behalf of an unprivileged process, via the setns(3)
49 system call on Linux. On success, the hostname is returned in the sup‐
50 plied buffer, of size buflen and the return value indicates the length
51 of the hostname.
52 pmdaRootContainerProcessID performs a name to process identifier trans‐
54 lation - on success, the return value is the identifier of the first
55 process started (process 1) in the named container.
56 pmdaRootContainerCGroupName fills the supplied buffer with the engine-
58 specific names of kernel control groups that have been used to build
59 the container identified by name. When successful, the return value
60 indicates the length of the cgroup name resolved for the container.
61 The name of the container is interpreted by pmdaroot(1), which attempts
63 to match up the specified name with one of the implementations of con‐
64 tainers that it is aware of. Hence, the name argument is potentially
65 interpreted differently, depending on the installed container engine,
66 as determined internally by pmdaroot).
67 In the case of the Docker container engine, for example, a valid con‐
69 tainer name can be the unique hash identifier, the human-readable name,
70 or any unique identifier substring. This is the algorithm used by the
71 Docker client tools themselves.
72
74 A second set of interfaces are provided allowing the collector system
75 to start privileged child processes. In particular, these are used by
76 pmcd(1) so that it can start privileged PMDAs even when it is running
77 under an unprivileged account itself.
78 These interfaces allow processes to be started (pmdaRootProcessStart),
80 reaped upon completion (pmdaRootProcessWait), and forcibly terminated
81 through use of signals (pmdaRootProcessTerminate). At this stage, they
82 are intended only for use by pmcd itself and as such are described here
83 only for completeness.
84
86 All pmdaRoot interfaces will return negative status codes suitable for
87 passing to pmErrStr_r(3).
88
90 pmcd(1), pmdaroot(1), pmErrStr_r(3), PMDA(3), setns(3) and unix(7).
91Performance Co-Pilot PCP PMDAROOTCONNECT(3)