1PMDAROOTCONNECT(3)         Library Functions Manual         PMDAROOTCONNECT(3)
2
3
4

NAME

6       pmdaRootConnect, pmdaRootShutdown, pmdaRootContainerHostName, pmdaRoot‐
7       ContainerProcessID, pmdaRootContainerCGroupName,  pmdaRootProcessStart,
8       pmdaRootProcessWait,  pmdaRootProcessTerminate - privileged PCP collec‐
9       tor services
10

C SYNOPSIS

12       #include <pcp/pmapi.h>
13       #include <pcp/pmda.h>
14
15       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
28       cc ... -lpcp_pmda -lpcp
29

DESCRIPTION

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
35       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

CONTAINERS

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
47       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
53       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
57       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
62       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
68       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

PROCESSES

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
79       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

DIAGNOSTICS

86       All pmdaRoot interfaces will return negative status codes suitable  for
87       passing to pmErrStr_r(3).
88

SEE ALSO

90       pmcd(1), pmdaroot(1), pmErrStr_r(3), PMDA(3), setns(3) and unix(7).
91
92
93
94Performance Co-Pilot                  PCP                   PMDAROOTCONNECT(3)
Impressum