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 unprivileged 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 potentially  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 processes.  In particular, these are used by pmcd(1) so that it can start privileged
       PMDAs even when it is running under an unprivileged account itself.

       These  interfaces  allow  processes  to  be  started  (pmdaRootProcessStart),  reaped upon
       completion  (pmdaRootProcessWait),  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).