pmdarootconnect(3) — Linux manual page

PMDAROOTCONNECT(3)      Library Functions Manual      PMDAROOTCONNECT(3)

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 collec‐
       tor 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 scenar‐
       ios needed by PCP collector services.  The channel can be deacti‐
       vated using the pmdaRootShutdown interface.

CONTAINERS

       Several interfaces are provided for access to the  container  fa‐
       cilities  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 implemen‐
       tations of containers that it is aware of.  Hence, the name argu‐
       ment is potentially interpreted differently, depending on the in‐
       stalled 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-read‐
       able name, or any unique identifier substring. This is the  algo‐
       rithm 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  (pmdaRoot‐
       ProcessStart), reaped upon completion (pmdaRootProcessWait),  and
       forcibly terminated through use of signals (pmdaRootProcessTermi‐
       nate).  At this stage, they are intended only for use by pmcd it‐
       self and as such are described here only for completeness.

DIAGNOSTICS

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

SEE ALSO

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

COLOPHON

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If  you  have  a  bug  report  for  this  manual page, send it to
       pcp@groups.io.   This  page  was  obtained  from  the   project's
       upstream                      Git                      repository
       ⟨https://github.com/performancecopilot/pcp.git⟩  on   2024-06-14.
       (At  that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version of the page, or you  believe  there
       is  a  better or more up-to-date source for the page, or you have
       corrections or improvements to the information in  this  COLOPHON
       (which  is  not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot               PCP                PMDAROOTCONNECT(3)

Pages that refer to this page: pmdaroot(1)

---