Host and Port Specifications

In several settings, Privilege Management for Unix and Linux requests hosts, ports, or both.

Port Specifications

A port can consist of a file name for Unix/Linux Domain Sockets or a number or service name with an optional interface. The port numbers for Privilege Management daemons must use the non-reserved system ports. The allowed port numbers are 1024 to 65535 (inclusive).

The optional interface specification is useful on a machine that has multiple interfaces or network cards. The interface specification enables you to specify the exact interface to use.

[port=]<number or service name>[:interface=<host name or IP address>] [port=]<absolute file name>

The optional interface may be a host name or IP address. If the optional interface is specified for an incoming port, then only connections on that interface are accepted. If the optional interface is specified for an outgoing port, then only that interface is used to form the connection.

Port Format Description Example
[port=]<absolute file name> A local (Unix/Linux Domain) socket /tmp/pbport port=/tmp/pbmasterd_port
[port=]<number> A numeric TCP/IP port 24345 port=24345
[port=]<service name> A service name from /etc/services or NIS pbmasterd port=pbmasterd
[port=]<number>: interface= <hostname> A numeric TCP/IP port on a specific interface 24345:interface= localhost port=24345: interface= host.domain
[port=]<service name>:interface=<IP address> A service name from /etc/services or NIS on a specific interface pbmasterd: interface= 127.0.0.1 port=pbmasterd: interface= 192.168.1.1

When using a symbolic name, Privilege Management services need to be defined in /etc/services. Doing so enables the superdaemon, Privilege Management for Unix and Linux programs, and system utilities (such as nslookup) to know the symbolic names of the ports (and services) that are provided by Privilege Management.

Host Specifications

Hosts may be a host name, an IP address, a DNS SRV lookup entry, the _auto DNS SRV lookup, or a path to an external program. If appropriate, they may also be followed by a port specification.

<host name or IP address>

A valid host name can contain any letter or digit. It can also contain a hyphen. The last character must be a letter or a digit.

<DNS SRV lookup>
Privilege Management for Unix and Linux validates data returned from DNS SRV lookups to exclude any data that contains the following illegal characters:

/ ` ' ~ ? ! @ # $ % ^ & * () {} < > = ; , | \\\ "

When Privilege Management for Unix and Linux components processing the submitmasters, altsubmitmasters, acceptmasters, and logservers keywords encounter an entry that begins with an underscore (_) those components perform a DNS query. That query returns a port value for the service, as well as a list of hosts providing that service. A complete DNS SRV lookup specification includes the service name, protocol (which is always _tcp), domain, and a port specification. The submitmasters, acceptmasters, and logservers keywords have the ability to specify a lookup in the format:

_<pbul service name>._tcp.<domain name>.[:port=<port>[:interface=<IP or hostname>]]

All elements are optional except the service name. If the domain name portion is missing, it is up to the resolver and its configuration to define and use a search order (for example, /etc/resolv.confsearch entry). If the ._tcp portion is missing, it is added automatically. This implementation supports the SRV hostname, port and priority values, and ignores the SRV weight value.

If the port value returned in the DNS query is non-zero, it overrides the corresponding port specified in pb.settings (for example, a DNS lookup for submitmasters, which returns a port > 0, overrides any port specified in the submitmasters keyword and in the masterport keyword.

If the port specified in DNS is zero, the port specified in the corresponding submitmasters, altsubmitmasters, or logservers keyword (if specified there) is used. If not specified, the port specified in the corresponding masterport, logport keywords is used.

If an interface is specified in pb.settings (for example, specified in the submitmasters keyword or in the masterport keyword), that interface is used even if the corresponding port is overridden by the DNS lookup.

The DNS SRV lookup can be specified in any order in the list of hosts, and is processed in that order.

submitmasters host1 _pbmasterd host2

The pbl.settings entry results in the attempt to use host1 as a policy server. Only if that fails, DNS SRV records are queried for the _ pbmasterd._tcp entry. Only if all hosts specified in the DNS SRV query results fail, host2 is contacted.

Once an SRV lookup takes place, the priority values specified in DNS is used for those entries.

DNS can be configured for round-robin or randomized results for a minimal form of load balancing, if desired.

In this case, the order of DNS results are modified by DNS and Privilege Management for Unix and Linux simply processes the SRV query results in the order received.

The randomizesubmitmasters keyword should not be used with the use of DNS SRV lookups.

submitmasters host1 _pbmasterd host2

If the pb.settings entry is as shown above, the randomizesubmitmasters may cause host2 to be contacted prior to performing the _pbmasterd service lookup, prior to host1. The randomizesubmitmasters does not affect the order of processing the SRV query results. This would conflict with the SRV priority values.

When a DNS SRV lookup is specified for the acceptmasters keyword, the SRV priority and port are irrelevant.

pbsyncd uses the logservers keyword to identify logservers, however this uses a different port than pblogd, so any DNS SRV records for host providing pbsyncd should have the port set to 0.

<_auto DNS SRV lookup>

The special service name _auto is used to build a service name from the Privilege Management installation's prefix and suffix.

When_auto is used for submitmasters and acceptmasters, the resulting service name is:

_<prefix>pbmasterd<suffix>

When_auto is used for altsubmitmasters the resulting service name is:

_<prefix>altpbmasterd<suffix>

When _auto is used for logservers the resulting service name is:

_<prefix>pblogd<suffix>

The full _auto specification is:

_auto[:port=1.2.3.4[:interface=<IP or hostname>]]

Use of _auto for submitmasters and acceptmasters results in the same SRV lookup. Use caution when using _auto for altsubmitmasters, as the runhost's acceptmasters list must include the hosts specified by the altsubmitmasters SRV lookup.

<`/path/to/external/program`>

The submitmasters, altsubmitmasters, acceptmasters, and logservers keywords support a mechanism to execute an external program that returns a single value. The external program path and filename should be contained within backticks without whitespace. Command line arguments to the external program are not supported. Redirection and backgrounding the external program are not supported.

Output of the external program should be a single valid host entry (for example, a hostname, an IP address, a file name, a netgroup, or an SRV lookup; including the optional [:port=<port>[:interface=<interface>]] specification) for the supported keywords, whitespace (other than a trailing newline) is only acceptable when specifying a program and its arguments such as: /path/to/pbmasterd -ar.

The external program must be writable only by root. The external program must execute within 2 seconds, or the value of masterprotocoltimeout converted to seconds, whichever is greater. When an external program does not complete within the specified timeframe, the program may become a "zombie" process.

The optional port/interface specification can be output by the external program, or immediately following the backticks specifying the external program but not both.

Errors that occur evaluating the external program are logged to the appropriate log file, however they will not be displayed to the submituser's display. Thus the submitting user sees a generic error message such as 3366 Invalid submitmasters setting.

myhost.mydomain
	_auto
	_pbmasters
	_pbmasters._tcp.mydomain.
	_pbmasters._tcp. mydomain.:port=12345
	`/bin/get_first_submitmaster`