'\"macro stdmacro
.\"
.\" Copyright (C) 2021 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\"
.TH PMDABCC 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmdabpf\f1 \- eBPF PMDA
.SH DESCRIPTION
\fBpmdabpf\fP is a Performance Co-Pilot (PCP) Performance Metrics Domain
Agent (PMDA) which extracts live performance data from eBPF programs utilizing
BPF CO-RE (libbpf and BTF).
.PP
\fBpmdabpf\fP loads and acts as a bridge for any number of configured,
separate bpf PMDA modules. Existing libbpf tools should be possible to be
utilized with the bpf PMDA modules with reasonable effort.
.PP
See the eBPF, libbpf and BPF CO-RE documentation for detailed descriptions.
.SH CONFIGURATION
\fBpmdabpf\fP reads a mandatory ini-style configuration file:
.IP
.PD 0
.IP
.I \f(CR$PCP_PMDAS_DIR\fP/bpf/bpf.conf
.PD
.PP
Each section of the file corresponds to one bpf PMDA module.
The following global options are available for every module
(their default values are shown in parenthesis):
.TP 15
.B enabled \fR(unset)\fP
A boolean value to specify whether this bpf PMDA module should be started or not.
.PP
Modules may also support additional module-specific configuration options,
refer to the default configuration file for their supported options.
.SH INSTALLATION
To install, the following must be done as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/bpf
# ./Install
.fi
.ft P
.RE
.sp 1
To uninstall, the following must be done as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/bpf
# ./Remove
.fi
.ft P
.RE
.sp 1
\fBpmdabpf\fP is launched by \fBpmcd\fP(1) and should never be
executed directly.
The \fBInstall\fP and \fBRemove\fP scripts notify \fBpmcd\fP(1) when
the agent is installed or removed.
.PP
Some modules will start providing values only after having collected data
from related system activity.
.SH FILES
.TP 5
.I \f(CR$PCP_PMDAS_DIR\fP/bpf/bpf.conf
configuration file for the \fBpmdabpf\fP agent
.TP
.I \f(CR$PCP_PMDAS_DIR\fP/bpf/modules/*.{o,so}
bpf PMDA modules available for the \fBpmdabpf\fP agent
.TP
.I \f(CR$PCP_PMDAS_DIR\fP/bpf/Install
installation script for the \fBpmdabpf\fP agent
.TP
.I \f(CR$PCP_PMDAS_DIR\fP/bpf/Remove\fP
undo installation script for the \fBpmdabpf\fP agent
.TP
.I \f(CR$PCP_LOG_DIR\fP/pmcd/bpf.log
default log file for messages from the \fBpmdabpf\fP agent
.PP
Note that the usual/default value for \fB$PCP_PMDAS_DIR\fP is
.B /var/lib/pcp/pmdas
and the default for \fB$PCP_LOG_DIR\fP is
.B /var/log/pcp
but these settings are platform dependent.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR PCPIntro (1),
.BR bpf (1)
and
.BR pmcd (1).