PMDAROOTCONNECT(3)

💅 pmdaRootConnect — the PCP privileged collector services, bestie edition

okay so this is PMDAROOTCONNECT(3) from the Library Functions Manual (yes we're in section 3, the library functions section, we know her) 💖

---

✨ NAME ✨

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

like. a whole squad of functions whose entire job is "let the PCP collector do privileged stuff without being privileged." it's giving main character energy fr.

---

🌸 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

link against -lpcp_pmda -lpcp or it literally will not work, no cap. those two libraries are the moment. 🫶

---

🦋 DESCRIPTION 🦋

so pmdaRootConnect initializes an IPC channel between a PCP collector process — that's either a PMDA(3) or pmcd(1) itself — and the pmdaroot(1) server. it's basically setting up a little private line between them. ✨

on success, the return value from pmdaRootConnect is a unix(7) domain socket file descriptor, and you can pass that fd to every single one of the other APIs described down here. this channel exists so the collector can do limited privilege escalation for the specific scenarios that PCP collector services need. lowkey a big deal.

and when you're done with it? you deactivate the channel using the pmdaRootShutdown interface. bye bestie 💅

---

🎀 CONTAINERS 🎀

there's a whole set of interfaces here for poking at the container facilities of modern Linux distributions — because various agents need to access kernel features related to containers and they cannot just do that themselves, you know?

• pmdaRootContainerHostName — lets an unprivileged process look up the current hostname for a named container, on its behalf, via the setns(3) system call on Linux. on success, the hostname lands in the supplied buffer (of size buflen), and the return value tells you the length of the hostname. iconic.
• pmdaRootContainerProcessID — does a name to process identifier translation. on success, the return value is the identifier of the first process started (process 1) inside the named container. yes, that process 1. 🍓
• pmdaRootContainerCGroupName — fills the supplied buffer with the engine-specific names of kernel control groups that were used to build the container identified by name. when it works, the return value indicates the length of the cgroup name resolved for that container. obsessed.

so like, the name of the container is interpreted by pmdaroot(1), which tries to match up whatever name you gave it against one of the implementations of containers it knows about. which means the name argument is potentially interpreted differently depending on which container engine is installed — pmdaroot figures that out internally. iykyk.

take 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. and that's literally the same algorithm the Docker client tools themselves use. periodt. 💀

---

🔥 PROCESSES 🔥

second set of interfaces, and these ones let the collector system start privileged child processes. specifically? pmcd(1) uses them so it can start privileged PMDAs even when it is itself running under an unprivileged account. the way that it just... escalates for you. 😭

so these interfaces let processes be:

• started — pmdaRootProcessStart
• reaped upon completion — pmdaRootProcessWait
• forcibly terminated through use of signals — pmdaRootProcessTerminate

⚠️ at this stage, they are intended only for use by pmcd itself, and they're described here only for completeness. so like, not for you, bestie. hands off. 🙈

---

⭐ DIAGNOSTICS ⭐

all pmdaRoot interfaces will return negative status codes, and those are suitable for passing straight to pmErrStr_r(3). so go ahead and translate them into actual words. 💜

---

🌈 SEE ALSO 🌈

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

---

and that's the whole page, diva. this one came out of Performance Co-Pilot, the PCP project, and it's PMDAROOTCONNECT(3) — go forth and escalate your privileges responsibly. mwah 💋✨