The access control section of the configuration file is optional,
but if present it must follow the agent configuration data. The
case of reserved words is ignored, but elsewhere case is
preserved. Lexical elements in the access control section are
separated by whitespace or the special delimiter characters:
square brackets (``['' and ``]''), braces (``{'' and ``}''),
colon (``:''), semicolon (``;'') and comma (``,''). The special
characters are not treated as special in the agent configuration
section. Lexical elements may be quoted (double quotes) as
necessary.
The access control section of the file must start with a line of
the form:
[access]
In addition to (or instead of) the access section in the pmcd
configuration file, access control specifications are also read
from a file having the same name as the pmcd configuration file,
but with '.access' appended to the name. This optional file must
not contain the [access] keyword.
Leading and trailing whitespace may appear around and within the
brackets and the case of the access keyword is ignored. No other
text may appear on the line except a trailing comment.
Following this line, the remainder of the configuration file
should contain lines that allow or disallow operations from
particular hosts or groups of hosts.
There are two kinds of operations that occur via pmcd:
fetch allows retrieval of information from pmcd. This may be
information about a metric (e.g. its description, instance
domain, labels or help text) or a value for a metric. See
pminfo(1) for further information.
store allows pmcd to be used to store metric values in agents
that permit store operations. This may be the actual
value of the metric (e.g. resetting a counter to zero).
Alternatively, it may be a value used by the PMDA to
introduce a change to some aspect of monitoring of that
metric (e.g. server side event filtering) - possibly even
only for the active client tool performing the store
operation, and not others. See pmstore(1) for further
information.
Access to pmcd can be granted in three ways - by user, group of
users, or at a host level. In the latter, all users on a host
are granted the same level of access, unless the user or group
access control mechanism is also in use.
User names and group names will be verified using the local
/etc/passwd and /etc/groups files (or an alternative directory
service), using the getpwent(3) and getgrent(3) routines.
Hosts may be identified by name, IP address, IPv6 address or by
the special host specifications ``"unix:"'' or ``"local:"''.
``"unix:"'' refers to pmcd's unix domain socket, on supported
platforms. ``"local:"'' is equivalent to specifying ``"unix:"''
and ``localhost``.
Wildcards may also be specified by ending the host identifier
with the single wildcard character ``*'' as the last-given
component of an address. The wildcard ``".*"'' refers to all
inet (IPv4) addresses. The wildcard ``":*"'' refers to all IPv6
addresses. If an IPv6 wildcard contains a ``::'' component, then
the final ``*'' refers to the final 16 bits of the address only,
otherwise it refers to the remaining unspecified bits of the
address.
The wildcard ``*'' refers to all users, groups or host addresses,
including ``"unix:"''. Names of users, groups or hosts may not
be wildcarded.
The following are all valid host identifiers:
boing
localhost
giggle.melbourne.sgi.com
129.127.112.2
129.127.114.*
129.*
.*
fe80::223:14ff:feaf:b62c
fe80::223:14ff:feaf:*
fe80:*
:*
"unix:"
"local:"
*
The following are not valid host identifiers:
*.melbourne
129.127.*.*
129.*.114.9
129.127*
fe80::223:14ff:*:*
fe80::223:14ff:*:b62c
fe80*
The first example is not allowed because only (numeric) IP
addresses may contain a wildcard. The second and fifth examples
are not valid because there is more than one wildcard character.
The third and sixth contain an embedded wildcard, the fourth and
seventh have a wildcard character that is not the last component
of the address (the last components are 127* and fe80*
respectively).
The name localhost is given special treatment to make the
behavior of host wildcarding consistent. Rather than being
127.0.0.1 and ::1, it is mapped to the primary inet and IPv6
addresses associated with the name of the host on which pmcd is
running. Beware of this when running pmcd on multi-homed hosts.
Access for users, groups or hosts are allowed or disallowed by
specifying statements of the form:
allow users userlist : operations ;
disallow users userlist : operations ;
allow groups grouplist : operations ;
disallow groups grouplist : operations ;
allow hosts hostlist : operations ;
disallow hosts hostlist : operations ;
list userlist, grouplist and hostlist are comma separated lists
of one or more users, groups or host identifiers.
operations
is a comma separated list of the operation types described
above, all (which allows/disallows all operations), or all
except operations (which allows/disallows all operations
except those listed).
Either plural or singular forms of users, groups, and hosts
keywords are allowed. If this keyword is omitted, a default of
hosts will be used. This behaviour is for backward-compatibility
only, it is preferable to be explicit.
Where no specific allow or disallow statement applies to an
operation, the default is to allow the operation from all users,
groups and hosts. In the trivial case when there is no access
control section in the configuration file, all operations from
all users, groups, and hosts are permitted.
If a new connection to pmcd is attempted by a user, group or host
that is not permitted to perform any operations, the connection
will be closed immediately after an error response
PM_ERR_PERMISSION has been sent to the client attempting the
connection.
Statements with the same level of wildcarding specifying
identical hosts may not contradict each other. For example if a
host named clank had an IP address of 129.127.112.2, specifying
the following two rules would be erroneous:
allow host clank : fetch, store;
disallow host 129.127.112.2 : all except fetch;
because they both refer to the same host, but disagree as to
whether the fetch operation is permitted from that host.
Statements containing more specific host specifications override
less specific ones according to the level of wildcarding. For
example a rule of the form
allow host clank : all;
overrides
disallow host 129.127.112.* : all except fetch;
because the former contains a specific host name (equivalent to a
fully specified IP address), whereas the latter has a wildcard.
In turn, the latter would override
disallow host * : all;
It is possible to limit the number of connections from a user,
group or host to pmcd. This may be done by adding a clause of
the form
maximum n connections
to the operations list of an allow statement. Such a clause may
not be used in a disallow statement. Here, n is the maximum
number of connections that will be accepted from the user, group
or host matching the identifier(s) used in the statement.
An access control statement with a list of user, group or host
identifiers is equivalent to a set of access control statements,
with each specifying one of the identifiers in the list and all
with the same access controls (both permissions and connection
limits). A group should be used if you want users to contribute
to a shared connection limit. A wildcard should be used if you
want hosts to contribute to a shared connection limit.
When a new client requests a connection, and pmcd has determined
that the client has permission to connect, it searches the
matching list of access control statements for the most specific
match containing a connection limit. For brevity, this will be
called the limiting statement. If there is no limiting
statement, the client is granted a connection. If there is a
limiting statement and the number of pmcd clients with user ID,
group ID, or IP addresses that match the identifier in the
limiting statement is less than the connection limit in the
statement, the connection is allowed. Otherwise the connection
limit has been reached and the client is refused a connection.
Group access controls and the wildcarding in host identifiers
means that once pmcd actually accepts a connection from a client,
the connection may contribute to the current connection count of
more than one access control statement - the client's host may
match more than one access control statement, and similarly the
user ID may be in more than one group. This may be significant
for subsequent connection requests.
Note that pmcd enters a mode where it runs effectively with a
higher-level of security as soon as a user or group access
control section is added to the configuration. In this mode only
authenticated connections are allowed - either from a SASL
authenticated connection, or a Unix domain socket (which
implicitly passes client credentials). This is the same mode
that is entered explicitly using the -S option. Assuming
permission is allowed, one can determine whether pmcd is running
in this mode by querying the value of the
pmcd.feature.creds_required metric.
Note also that because most specific match semantics are used
when checking the connection limit, for the host-based access
control case, priority is given to clients with more specific
host identifiers. It is also possible to exceed connection
limits in some situations. Consider the following:
allow host clank : all, maximum 5 connections;
allow host * : all except store, maximum 2 connections;
This says that only 2 client connections at a time are permitted
for all hosts other than "clank", which is permitted 5. If a
client from host "boing" is the first to connect to pmcd, its
connection is checked against the second statement (that is the
most specific match with a connection limit). As there are no
other clients, the connection is accepted and contributes towards
the limit for only the second statement above. If the next
client connects from "clank", its connection is checked against
the limit for the first statement. There are no other
connections from "clank", so the connection is accepted. Once
this connection is accepted, it counts towards both statements'
limits because "clank" matches the host identifier in both
statements. Remember that the decision to accept a new
connection is made using only the most specific matching access
control statement with a connection limit. Now, the connection
limit for the second statement has been reached. Any connections
from hosts other than "clank" will be refused.
If instead, pmcd with no clients saw three successive connections
arrived from "boing", the first two would be accepted and the
third refused. After that, if a connection was requested from
"clank" it would be accepted. It matches the first statement,
which is more specific than the second, so the connection limit
in the first is used to determine that the client has the right
to connect. Now there are 3 connections contributing to the
second statement's connection limit. Even though the connection
limit for the second statement has been exceeded, the earlier
connections from "boing" are maintained. The connection limit is
only checked at the time a client attempts a connection rather
than being re-evaluated every time a new client connects to pmcd.
This gentle scheme is designed to allow reasonable limits to be
imposed on a first come first served basis, with specific
exceptions.
As illustrated by the example above, a client's connection is
honored once it has been accepted. However, pmcd reconfiguration
(see the next section) re-evaluates all the connection counts and
will cause client connections to be dropped where connection
limits have been exceeded.
