3.6 The Control Statement

The control interface provides a method for communication with the running pies instance. It is used by the piesctl utility to query information about the instance and components it is currently running and to send it commands for controlling its operation (see piesctl). By default the UNIX socket /tmp/pies.ctl is used for this purpose. If pies was started with the --instance=name option, the socket is named /tmp/name.ctl. Whatever its name, the socket will be owned by the user pies runs as (see Pies Privileges) and will have access rights of 0500, allowing only that user to read and write to it. When pies is used as init process, the default socket name is /dev/init.ctl.

Config: control

The ‘control’ statement configures the control interface and limits access to it:

control {
    socket url;
    acl { … }
    admin-acl { … }
    user-acl { … }
    realm name;
}

Config: control: socket url

URL of the control socket. The url argument is a string of the following syntax:

inet://ip:port

Listen on IPv4 address ip (may be given as a symbolic host name), on port port.

local://file[;args]

file://file[;args]

unix://file[;args]

Listen on the UNIX socket file file, which is either an absolute or relative file name. Optional arguments args control ownership and file mode of file. They are a semicolon-separated list of assignments to the following variables:

user

User name of the socket owner.

group

Owner group of the socket, if it differs from the user group.

mode

Socket file mode (octal number between ‘0’ and ‘777’).

umask

Umask to use when creating the socket (octal number between ‘0’ and ‘777’).

Config: control: idle-timeout n

Disconnect any control session that remains inactive for n seconds. This statement is reserved for use in the future. Currently (as of version 1.8) it is a no-op.

The control interface is protected by three access control lists (See ACL, for a discussion of their syntax).

Config: control: acl name

Config: control: acl { … }

Controls who can connect to the interface. The first form refers to a named ACL that must have been defined earlier by defacl statement (see defacl). Use the second form to define a new ACL in place.

Config: control: user-acl name

Config: control: user-acl { … }

Control interface provides two kinds of operations: read-only (such as getting information about running components) and write operations (such as stopping or restarting components).

The user-acl controls read access. Access to particular components can also be controlled individually, using the per-component list-acl statement (see list-acl).

Config: control: admin-acl name

Config: control: admin-acl { … }

Controls write access to the pies instance itself and to the components for which no specific admin-acl statements are supplied (see admin-acl).

In particular, whoever passes admin-acl can issue commands for stopping the instance and reloading its configuration.

When checking whether the user has a particular kind of access to a component, first the corresponding ACL from the control section is checked. If it allows access, then the per-component ACL is tried. If it allows access too, then the operation is permitted.

Config: control: realm name

Defines the realm for basic authentication. Default value is ‘pies’.