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).