In the absence of an explicit hostname specification, most tools
will default to the local host in live update mode. In PCP
releases since 3.8.4 onward, this results in an efficient local
protocol being selected - typically a Unix domain socket. If
this option is used (which can also be explicitly requested via
the unix: host specification described below), it is important to
note that all connections will be automatically authenticated.
In other words, the credentials of the user invoking a client
tool will automatically be made available to pmcd(1) and all of
its PMDAs, on the users behalf, such that results can be
customized to the privilege levels of individual users.
Names of remote hosts running the pmcd(1) daemon can of course
also be provided to request a remote host be used. The most
basic form of pmcd host specification is a simple host name,
possibly including the domain name if necessary. However, this
can be extended in a number of ways to further refine attributes
of the connection made to pmcd.
The pmcd port number and also optional pmproxy(1) hostname and
its port number, can be given as part of the host specification,
since PCP version 3.0. These supersede (and override) the old-
style PMCD_PORT, PMPROXY_HOST and PMPROXY_PORT environment
variables.
The following are valid hostname specifications that specify
connections to pmcd on host nas1.acme.com with/without a list of
ports, with/without a pmproxy(1) connection through a firewall,
and with IPv6 and IPv4 addresses as shown.
$ pcp --host nas1.acme.com:44321,4321@firewall.acme.com:44322
$ pcp --host nas1.acme.com:44321@firewall.acme.com:44322
$ pcp --host nas1.acme.com:44321@firewall.acme.com
$ pcp --host nas1.acme.com@firewall.acme.com
$ pcp --host nas1.acme.com:44321
$ pcp --host [fe80::2ad2:44ff:fe88:e4f1%p2p1]
$ pcp --host 192.168.0.103
In addition, ``connection attributes'' can also be specified.
These include username, password (can be given interactively and
may depend on the authentication mechanism employed), whether to
target a specific running container, whether to use secure
(encrypted) or native (naked) protocol, and so on. The previous
examples all default to native protocol, and use no
authentication. This can be altered, as in the following
examples.
$ pcp --host pcps://app2.acme.com?container=cae8e6edc0d5
$ pcp --host pcps://nas1.acme.com:44321?username=tanya&method=gssapi
$ pcp --host pcps://nas2.acme.com@firewalls.r.us?method=plain
$ pcp --host pcp://nas3.acme.com
$ pcp --host 192.168.0.103?container=cae8e6edc0d5,method=scram-sha-256
$ pcp --host unix:
$ pcp --host local:
The choice of authentication method, and other resulting
parameters like username, optionally password, etc, depends on
the SASL2 configuration used by each (remote) pmcd. Tutorials
are available specifying various aspects of configuring the
authentication module(s) used, these fine details are outside the
scope of this document.
In all situations, host names can be used interchangeably with
IPv4 or IPv6 addressing (directly), as shown above. In the case
of an IPv6 address, the full address must be enclosed by square
brackets and the scope (interface) must also be specified.
The final local: example above is now the default for most tools.
This connection is an automatically authenticated local host
connection on all platforms that support Unix domain sockets. No
password is required and authentication is automatic. This is
also the most efficient (lowest overhead) communication channel.
The difference between unix: and local: is that the former is a
strict Unix domain socket specification (connection fails if it
cannot connect that way), whereas the latter has a more forgiving
fallback to using localhost (i.e. a regular Inet socket
connection is used when Unix domain socket connections are
unavailable).
