# pmdarootconnect

## 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) do‐
           main  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 facil‐
           ities  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 en‐
           gine-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 at‐
           tempts  to match up the specified name with one of the implementa‐
           tions 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-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 suitable
           for passing to pmErrStr_r(3).
    


* * *