1PMDAROOTCONNECT(3) Library Functions Manual PMDAROOTCONNECT(3)
2
6 pmdaRootConnect, pmdaRootShutdown, pmdaRootContainerHostName, pmdaRoot‐
7 ContainerProcessID, pmdaRootContainerCGroupName - privileged PCP col‐
8 lector services
9
11 #include <pcp/pmapi.h>
12 #include <pcp/pmda.h>
13 int pmdaRootConnect(void);
15 void pmdaRootShutdown(int fd);
16 int pmdaRootContainerHostName(int fd, char *name, int namelen, char
17 *buffer, int buflen);
18 int pmdaRootContainerProcessID(int fd, char *name, int namelen);
19 int pmdaRootContainerCGroupName(int fd, char *name, int namelen, char
20 *buffer, int buflen);
21 cc ... -lpcp_pmda -lpcp
23
25 pmdaRootConnect initializes an IPC channel between a PCP collector
26 process - either a PMDA(3) or pmcd(1) itself - and the pmdaroot(1)
27 server.
28 On success, the return value from pmdaRootConnect is a unix(7) domain
30 socket file descriptor, which can be subsequently passed to each of the
31 other APIs described here. This channel can be used to perform limited
32 privilege escalation for specific scenarios needed by PCP collector
33 services. The channel can be deactivated using the pmdaRootShutdown
34 interface.
35 Currently, these services provide access to the container facilities of
37 modern Linux distributions, as needed by various agents accessing ker‐
38 nel features related to containers.
39 pmdaRootContainerHostName allows lookup of the current hostname for a
41 named container on behalf of an unprivileged process, via the setns(3)
42 system call on Linux. On success, the hostname is returned in the sup‐
43 plied buffer, of size buflen and the return value indicates the length
44 of the hostname.
45 pmdaRootContainerProcessID performs a name to process identifier trans‐
47 lation - on success, the return value is the identifier of the first
48 process started (process 1) in the named container.
49 pmdaRootContainerCGroupName fills the supplied buffer with the engine-
51 specific names of kernel control groups that have been used to build
52 the container identified by name. When successful, the return value
53 indicates the length of the cgroup name resolved for the container.
54 The name of the container is interpreted by pmdaroot(1), which attempts
56 to match up the specified name with one of the implementations of con‐
57 tainers that it is aware of. Hence, the name argument is potentially
58 interpreted differently, depending on the installed container engine,
59 as determined internally by pmdaroot(1)).
60 In the case of the Docker container engine, for example, a valid con‐
62 tainer name can be the unique hash identifier, the human-readable name,
63 or any unique identifier substring. This is the algorithm used by the
64 Docker client tools themselves.
65
67 All pmdaRoot interfaces will return negative status codes suitable for
68 passing to pmErrStr_r(3).
69
71 pmcd(1), pmdaroot(1), pmErrStr_r(3), PMDA(3), setns(3) and unix(7).
72Performance Co-Pilot PCP PMDAROOTCONNECT(3)