NAME

       pmdaRootConnect,       pmdaRootShutdown,      pmdaRootContainerHostName,      pmdaRootContainerProcessID,
       pmdaRootContainerCGroupName,  pmdaRootProcessStart,   pmdaRootProcessWait,   pmdaRootProcessTerminate   -
       privileged PCP collector services

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/pmda.h>

       int pmdaRootConnect(void);
       void pmdaRootShutdown(int fd);
       int pmdaRootContainerHostName(int fd, char *name, int namelen, char *buffer, int buflen);
       int pmdaRootContainerProcessID(int fd, char *name, int namelen);
       int pmdaRootContainerCGroupName(int fd, char *name, int namelen, char *buffer, int buflen);
       int pmdaRootProcessStart(int fd, int ipctype, char *label, int labellen, const char *args, int argslen,
               int *pid, int *infd, int *outfd);
       int pmdaRootProcessWait(int fd, int pid, int *status);
       int pmdaRootProcessTerminate(int fd, int pid);

       cc ... -lpcp_pmda -lpcp

DESCRIPTION

       pmdaRootConnect  initializes an IPC channel between a PCP collector process - either a PMDA(3) or pmcd(1)
       itself - and the pmdaroot(1) server.

       On success, the return value from pmdaRootConnect is a unix(7) domain socket file descriptor,  which  can
       be  subsequently  passed  to  each of the other APIs described here.  This channel can be used to perform
       limited privilege escalation for specific scenarios needed by PCP collector services.  The channel can be
       deactivated using the pmdaRootShutdown interface.

CONTAINERS

       Several interfaces are provided for access to the container facilities of modern Linux distributions,  as
       needed by various agents accessing kernel features related to containers.

       pmdaRootContainerHostName allows lookup of the current hostname for a named container on behalf of an un‐
       privileged  process,  via the setns(3) system call on Linux.  On success, the hostname is returned in the
       supplied buffer, of size buflen and the return value indicates the length of the hostname.

       pmdaRootContainerProcessID performs a name to process identifier translation -  on  success,  the  return
       value is the identifier of the first process started (process 1) in the named container.

       pmdaRootContainerCGroupName  fills  the  supplied buffer with the engine-specific names of kernel control
       groups that have been used to build the container identified by name.  When successful, the return  value
       indicates the length of the cgroup name resolved for the container.

       The  name  of  the container is interpreted by pmdaroot(1), which attempts to match up the specified name
       with one of the implementations of containers that it is aware of.  Hence, the name  argument  is  poten‐
       tially  interpreted differently, depending on the installed container engine, as determined internally by
       pmdaroot).

       In the case of the Docker container engine, for example, a valid container name can be  the  unique  hash
       identifier,  the  human-readable  name, or any unique identifier substring. This is the algorithm used by
       the Docker client tools themselves.

PROCESSES

       A second set of interfaces are provided allowing the collector system to start privileged child  process‐
       es.   In particular, these are used by pmcd(1) so that it can start privileged PMDAs even when it is run‐
       ning under an unprivileged account itself.

       These interfaces allow processes to be started (pmdaRootProcessStart), reaped upon completion  (pmdaRoot‐
       ProcessWait),  and forcibly terminated through use of signals (pmdaRootProcessTerminate).  At this stage,
       they are intended only for use by pmcd itself and as such are described here only for completeness.

DIAGNOSTICS

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

SEE ALSO

       pmcd(1), pmdaroot(1), pmErrStr_r(3), PMDA(3), setns(3) and unix(7).

Performance Co-Pilot                                   PCP                                    PMDAROOTCONNECT(3)