Go to main content

man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2017
 
 

rad(1M)

Name

rad - remote administration daemon

Synopsis

/usr/lib/rad [-d] [-s] [-S fmri]
     [-M module [ -M module ]...]
     [-m moduledir [ -m moduledir ]...]
     [-t transpec [ -t transpec ]...]
     [-e timeout]

Description

rad is a facility that securely exposes programmatic system administrative and monitoring interfaces to consumers in a variety of high-level languages.

rad can be used in the following ways:

  • As a service:

    When run as a service, rad authenticates connections using getpeerucred(3C) or pam(3PAM). When used in this way, consumed APIs are run as the authenticated user. This mode of operation is provided with both local consumers looking to isolate execution of their privileged operations and remote consumers in mind.

  • As an unprivileged program:

    When run as an unprivileged program, rad serves solely as a bridge between its clients and the administrative APIs it publishes. When used in this way, any interfaces consumed will be run with the rights held by the rad process.

rad is modular. The APIs published by rad are delivered as shared objects, as are the protocols it understands and the transports it can communicate over. Multiple instances of rad can run simultaneously, each functioning independently of the others, providing different services to different consumers, and listening for different types of connections on different ports or interfaces. rad obtains its configuration from its command-line options, from smf(5), or from a combination of the two.

Options

The following options are available for use on the command line:

–d

Emit verbose debugging output.

–e timeout

Specify a connection timeout in seconds. The default value is 180 seconds.

–m moduledir

Add moduledir to the list of directories to scan and load modules from. The –m option can be used multiple times to add multiple module directories.

–M module

Add module to the list of modules to load. module should be an absolute pathname or a pathname relative to the current working directory. Modules loaded with –M take precedence over modules found using –m. The –M option can be used multiple times to add multiple modules.

–t transpec

Instantiate a transport specified by transport specification transpec. A transport specification has the following format:

transport[:option[=value][,option2[=value2]]...]
–s

Behave as an svc.startd(1M) start method. This option has the following effects:

  • If the –S option is not specified, rad will read its configuration from the service identified by scf_myname() (see scf_handle_create(3SCF)).

  • rad will use smf_method(5)-compatible exit statuses.

  • rad will daemonize, returning success only once it is ready to handle requests.

–S fmri

Read configuration from the SMF service instance specified by fmri. When the –s option is not specified, configured transports are not read from the service to avoid endpoint conflicts with a running service.

Module directories specified on the command line are searched before module directories configured in SMF, permitting command line configuration to override SMF configuration.

SMF Configuration

When rad reads its configuration from smf(5), it reads general configuration from a property group called config of type application, and reads configuration for each of an arbitrary number of transports from a series of properties groups of type xport_XYZ where XYZ is replaced with the name of the transport type. Multiple instances of a particular transport type can be configured by creating multiple property groups of the corresponding type. The names of the property groups used to configure transports are not important.

The config property group contains the following properties:

moduledir

A list of astrings. The directories to scan and load modules from.

modules

A list of astrings. The file names of specific modules to load.

debug

A boolean. If true, rad will emit verbose debugging output. Defaults to false.

timeout

An integer. The maximum time in seconds to wait for an individual response from the client while authenticating. Defaults to 180.

Service Instances

Two instances of the svc:/system/rad SMF service are configured to run /usr/lib/rad/rad:

svc:/system/rad:local

Configures rad to use the unix transport, with AF_UNIX sockets at:

  • /system/volatile/rad/radsocket, for getpeerucred(3C)-authenticated connections, and...

  • /system/volatile/rad/radsocket-unauth, for pam(3PAM)-authenticated connections.

svc:/system/rad:remote

Configures rad to use the tls transport.

Each service is configured with the following directories in its moduledir setting:

/usr/lib/rad/module

content-specific modules

/usr/lib/rad/transport

transport modules

/usr/lib/rad/protocol

protocol modules

/usr/lib/rad/site-modules

site-specific modules

Transports

Support for different transport types is delivered in module form. Modules for the following transports are supplied with the system: pipes (pipe), TCP sockets (tcp), TLS sockets (tls), and Unix-domain sockets (unix). Each transport type has a unique set of configuration properties. The options for an instance of a transport type are configured either by defining properties in an SMF property group or by supplying sub-options to a –t command-line option.

The pipe transport reads from and writes to a specific file descriptor, as is needed when a process wishes to communicate with a child rad process using a pipe. The pipe transport has the following options:

proto

An astring. The protocol to use with this transport instance. Defaults to rad.

fd

An integer. The file descriptor to read from/write to.

exit

A boolean. If true, rad will exit when communication over the pipe ends. Defaults to false.

The tcp transport listens for clear-text connections on a TCP socket. The tcp transport has the following options:

proto

An astring. The protocol to use with this transport instance. Defaults to rad.

port

An integer. The port to listen on for connections.

localonly

A boolean. If true, rad will only listen for connections from the local machine. Defaults to true.

pam_service

An astring. The pam(3PAM) service name to use when authenticating. Defaults to rad-tcp. See the “Authenticating with PAM” section below.

The tls transport listens for TLS connections on a TCP socket. The tls transport has the following options:

proto

An astring. The protocol to use with this transport instance. Defaults to rad.

port

An integer. The port to listen on for connections.

localonly

A boolean. If true, rad will only listen for connections from the local machine. Defaults to true.

certificate

An astring. The location of the PEM-formatted x509 certificate to use.

privatekey

An astring. The location of the PEM-formatted private key to use.

generate

A boolean. If true, and if the specified certificate and privatekey do not exist, rad will generate a new certificate and private key using openssl(5). Defaults to false.

pam_service

An astring. The pam(3PAM) service name to use when authenticating. Defaults to rad-tls. See the “Authenticating with PAM” section below.

The unix transport listens for connections on an AF_UNIX socket. The unix transport has the following options:

proto

An astring. The protocol to use with this transport instance. Defaults to rad.

path

An astring. The path to listen on.

peercred

A boolean. If true, rad will attempt to automatically authenticate connections using getpeerucred(3C). Defaults to true.

pam_service

n astring. The pam(3PAM) service name to use when authenticating. Defaults to rad-unix. See the “Authenticating with PAM” section below.

Authenticating with PAM

When rad is run as a service, and getpeerucred(3C) is not applicable to the transport being used, pam(3PAM) is used to authenticate connections. The PAM service name used is dependent on the transport:

rad-tls

when connecting by means of the tls transport

rad-tcp

when connecting by means of the tcp transport

rad-unix

when connecting by means of the unix transport (and peercred is false)

rad

when connecting by means of any other transport

In rare cases, administrators may need to override the PAM service name used on a per-transport basis. For example, two rad TLS transports serving a single rad instance, with one listening on a local (more trusted) network and the other on a remote (less trusted) network, could require different PAM configurations.

In such cases, administrators can specify the name of the PAM service to use as a transport configuration property (see the “Transports” section above).

As with all PAM services, PAM will for look for entries corresponding to the PAM service for rad in /etc/pam.conf first and then /etc/pam.d/service. If no entries are found PAM will look in /etc/pam.conf for entries corresponding to the “other” service. If no “other” entries are found PAM will finally look for entries in /etc/pam.d/other.

Files

/etc/rad/cert.pem

The location where the remote rad instance (svc:/system/rad:remote) stores its certificate. This file is readable by all users.

/etc/rad/key.pem

The location where the remote rad instance (svc:/system/rad:remote) stores its private key.

/system/volatile/rad/radsocket

The AF_UNIX socket where the local rad instance (svc:/system/rad:local) accepts connections that are implicitly authenticated with getpeerucred(3C).

/system/volatile/rad/radsocket-unauth

The AF_UNIX socket where the local rad instance (svc:/system/rad:local) accepts connections that must explicitly authenticate using pam(3PAM).

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/management/rad
Interface Stability
Private

See Also

radadrgen(1), svc.startd(1M), pipe(2), getpeerucred(3C), pam(3PAM), scf_handle_create(3SCF), attributes(5), openssl(5), smf(5), smf_method(5)

Notes

Two instances of rad are delivered by the system. svc:/system/rad:local listens to AF_UNIX connections at the paths /system/volatile/rad/radsocket and /system/volatile/rad/radsocket-unauth, and is enabled by default. The former AF_UNIX socket will automatically authenticate the connecting process using getpeerucred(3C), while the latter requires the connecting process to explicitly authenticate. svc:/system/rad:remote listens to TLS connections on the port 12302, requires all clients to explicitly authenticate, and is disabled by default.

Other system components, including some desktop administrative user interfaces, rely on the local instance of rad (svc:/system/rad:local).