pmlogpush(1) · carta

NAME

pmlogpush - push an archive to a remote pmproxy server

SYNOPSIS

pmlogpush [-SvV?] [-D debug] [-h host] [-p port] [-s unix] [-U user] [-P passfile] [-Z timezone] archive

DESCRIPTION

pmlogpush sends the contents of a Performance Co-Pilot (PCP) archive to a HTTP server (typically to a remote pmproxy(1) daemon) using the logger API subset within the PMWEBAPI(5). The archive must have been previously created using pmlogger(1).

This archive should be complete and finished (not actively being written to).

By default the archive is transferred using cleartext HTTP. The -S (--secure) option instead uses an encrypted TLS connection (https://); see the description of that option below.

Comparable functionality is available directly from pmlogger via the HTTP-prefixed archive name syntax, which pushes archives remotely while they are actively being written.

OPTIONS

The available command line options are:

-h hostname, --host=hostname: The hostname for the remote pmproxy server to receive the given PCP archive.

-p port, --port=port: Internet socket port number where the remote pmproxy server is listening, waiting to receive the given PCP archive. The default port is 44322.

-s path, --unix=path: Unix domain socket path where a local pmproxy server is listening (locally), waiting to receive the given PCP archive.

-S, --secure: Use a secure, encrypted TLS connection (https://) to the remote pmproxy server instead of the default cleartext HTTP. The pmproxy server must have a TLS certificate configured (see pmproxy(1)); because pmproxy auto-detects TLS on its usual port, no separate port is required. Client-side TLS parameters - the certificate authority used to verify the server, and optionally a client certificate and key for mutual authentication - are read from $PCP_TLSCONF_PATH (typically /etc/pcp/tls.conf). pmlogpush always authenticates the server before sending any archive data: the pmproxy certificate must chain to a certificate authority trusted via $PCP_TLSCONF_PATH (tls-ca-cert-file or tls-ca-cert-dir), and its subject (or a subject alternative name) must match the hostname given with -h. An encrypted but unauthenticated connection is refused, since it would still be open to an active man-in-the-middle. If TLS support is not available, or the handshake or verification fails, pmlogpush reports an error and exits; it never silently falls back to cleartext.

-U user, --username=user: Authenticate to the remote pmproxy server as user using HTTP Basic authentication. This is an alternative to client-certificate (mutual TLS) authentication: it lets each pmlogpush present its own credential without provisioning per-client certificates. The password is not accepted on the command line (which would expose it in the process table); it is read from the file named by -P or, if that is not given, from the $PCP_PUSH_PASSWORD environment variable. Because HTTP Basic credentials are only base64 encoded and not encrypted, -U requires the -S (secure) option; sending credentials over a cleartext or unauthenticated connection is refused.

-P passfile, --password-file=passfile: Read the HTTP Basic authentication password from the first line of passfile (a trailing newline is stripped). Only meaningful together with -U. Keeping the password in a file, rather than in the environment or on the command line, keeps it out of the process table and shell history.

-v, --verbose: Increase the diagnostic information reported as pmlogpush runs.

-?, --help: Display usage message and exit.

-V, --version: Display version number and exit.

FILES

$PCP_TLSCONF_PATH: Client-side TLS configuration (certificate authority, and optionally a client certificate and key), used when the -S option requests a secure connection. Typically /etc/pcp/tls.conf.

$PCP_LOG_DIR/pmproxy/<hostname>: Default directory for pushed PCP archives created (remotely) by the receving pmproxy server. The hostname is extracted from the given archive, as is the recording start time - together these properties are used to name the pushed archive on the receiving end (i.e. by the pmproxy server).

PCP ENVIRONMENT

Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

In addition, when -U is used without -P, the HTTP Basic authentication password is taken from the $PCP_PUSH_PASSWORD environment variable.

DEBUGGING OPTIONS

The -D or --debug option enables the output of additional diagnostics on stderr to help triage problems, although the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users. debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to obtain a list of the available debugging options and their meaning. The http debugging option is of particular interest for this utility.