Next: , Previous: , Up: Configuration   [Contents][Index]

3.2 Component Statement

Config: component

The component statement defines a new component:

component tag {
  …
}

The component is identified by its tag, which is given as argument to the component keyword. Component declarations with the same tags are merged into a single declaration.

The following are the basic statements which are allowed within the component block:

Config: component: mode mode

Declare the type (style) of the component. Following are the basic values for mode:

exec
respawn

Define a ‘respawn’ component (see respawn). This is the default.

inetd
nostartaccept

Define an ‘inetd-style’ component (see inetd-style).

pass
pass-fd

Define a ‘meta1-style’ component (see meta1-style).

accept

Define a ‘accept-style’ component (see accept-style).

When run as init process (see Init Process), the following modes are also allowed:

boot

The process will be executed during system boot. The ‘runlevel’ settings are ignored.

bootwait

The process will be executed during system boot. No other components will be started until it has terminated. The ‘runlevel’ settings are ignored.

ctrlaltdel

The process will be executed when pies receives the SIGINT signal. Normally this means that the CTRL-ALT-DEL combination has been pressed on the keyboard.

kbrequest

The process will be executed when a signal from the keyboard handler is received that indicates that a special key combination was pressed on the console keyboard.

once

The process will be executed once when the specified runlevel is entered.

ondemand

The process will be executed when the specified ondemand runlevel is called (‘a’, ‘b’ and ‘c’). No real runlevel change will occur (see Ondemand runlevels). The process will remain running across any eventual runlevel changes and will be restarted whenever it terminates, similarly to respawn components.

powerfail

The process will be executed when the power goes down. Pies will not wait for the process to finish.

powerfailnow

The process will be executed when the power is failing and the battery of the external UPS is almost empty.

powerokwait

The process will be executed as soon as pies is informed that the power has been restored.

powerwait

The process will be executed when the power goes down. Pies will wait for the process to finish before continuing.

sysinit

The process will be executed during system boot, before any boot or bootwait entries. The ‘runlevel’ settings are ignored.

wait

The process will be started once when the specified runlevel is entered. Pies will wait for its termination before starting any other processes.

Config: component: program name

Full file name of the component binary. This binary will be executed (via /bin/sh -c) each time pies decides it needs to start the component.

To supply command line arguments, use command statement.

Config: component: command string

Command line for the program. The argument should be just as arguments normally are, starting with the name of the program. The latter may be different from the one specified to program statement. Its value will be available to the program as argv[0].

Config: component: flags (flag-list)

Define flags for this component. The flag-list is a comma-separated list of flags. Valid flags are:

disable

This component is disabled, i.e. pies will parse and remember its settings, but will not start it.

nullinput

Do not close standard input. Redirect it from /dev/null instead. Use this option with commands that require their standard input to be open (e.g. pppd nodetach).

precious

Mark this component as precious. Precious components are never disabled by pies, even if they respawn too fast.

wait

This flag is valid only for ‘inetd’ components. It has the same meaning as ‘wait’ in inetd.conf file, i.e. it tells pies to wait for the server program to return. See wait.

tcpmux

This is a TCPMUX component. See TCPMUX.

tcpmuxplus

This is a TCPMUX+ component. See TCPMUX.

internal

This is an internal inetd component. See builtin.

sockenv

This inetd component wants socket description variables in its environment. See sockenv.

resolve

When used with ‘sockenv’, the LOCALHOST and REMOTEHOST environment variables will contain resolved host names, instead of IP addresses.

siggroup

This flag affects the behavior of pies when a stopped process fails to terminate within a predefined timeout (see shutdown-timeout. Normally pies would send the ‘SIGKILL’ signal to such a process. If this flag is set, pies would send ‘SIGKILL’ to the process group of this process instead.

The following subsections describe the rest of ‘component’ substatements.


Next: , Up: Component Statement   [Contents][Index]

3.2.1 Component Prerequisites

Prerequisites (see component prerequisite) for a component are declared using the following statement:

Config: component: prerequisites tag-list

The argument is either a list of component tags, defined before this component, or one of the following words:

all

Declare all components defined so far as prerequisites for this one.

none

No prerequisites. This is the default.

If you wish, you can define dependents, instead of prerequisites:

Config: component: dependents tag-list

Declare dependents for this component. var-list is a list of component tags.


Next: , Previous: , Up: Component Statement   [Contents][Index]

3.2.2 Component Privileges

The following statements control privileges the component is executed with.

Config: component: user user-name

Start component with the UID and GID of this user.

Config: component: group group-list

Retain supplementary groups, specified in group-list.

Config: component: allgroups bool

Retain all supplementary groups of which the user (as given with user statement) is a member. This is the default for components specified in meta1.conf file (see include-meta1).


Next: , Previous: , Up: Component Statement   [Contents][Index]

3.2.3 Resources

Config: component: limits string

Impose limits on system resources, as defined by string. The argument consists of commands, optionally separated by any amount of whitespace. A command is a single command letter followed by a number, that specifies the limit. The command letters are case-insensitive and coincide with those used by the shell ulimit utility:

CommandThe limit it sets
Amax address space (KB)
Cmax core file size (KB)
Dmax data size (KB)
Fmaximum file size (KB)
Mmax locked-in-memory address space (KB)
Nmax number of open files
Rmax resident set size (KB)
Smax stack size (KB)
Tmax CPU time (MIN)
Umax number of processes
Pprocess priority -20..20 (negative = high priority)

Table 3.2: Limit Command Letters

For example:

limits T10 R20 U16 P20

Additionally, the command letter ‘L’ is recognized. It is reserved for future use (‘number of logins’ limit) and is ignored in version 1.3.

Config: component: umask number

Set the umask. The number must be an octal value not greater than ‘777’. The default umask is inherited at startup.

Config: component: env args

Set program environment.

Arguments are a whitespace-delimited list of specifiers. The following specifiers are understood:

- (a dash)

Clear the environment. This is understood only when used as a first word in args.

-name

Unset the environment variable name.

-name=val

Unset the environment variable name only if its value is val.

name

Retain the environment variable name.

name=value

Define environment variable name to have given value.

name+=value

Retain variable name and append value to its existing value. If no such variable is present in the environment, it is created and value is assigned to it. However, if value begins with a punctuation character, this character is removed from it before the assignment. This is convenient for using this construct with environment variables like PATH, e.g.:

PATH+=:/sbin

In this example, if PATH exists, ‘:/sbin’ will be appended to it. Otherwise, it will be created and ‘/sbin’ will be assigned to it.

name=+value

Retain variable name and prepend value to its existing value. If no such variable is present in the environment, it is created and value is assigned to it. However, if value ends with a punctuation character, this character is removed from it before assignment.

Config: component: max-instances n

Sets the maximum number of simultaneously running instances of this component.


Next: , Previous: , Up: Component Statement   [Contents][Index]

3.2.4 Actions Before Startup

The statements described in this subsection specify actions to perform immediately before starting the component:

Config: component: chdir dir

Change to the directory dir.

Config: component: remove-file file-name

Remove file-name. This is useful, for example, to remove stale UNIX sockets or pid-files, which may otherwise prevent the component from starting normally.

As of version 1.3 only one remove-file may be given.

Config: component: pass-fd-timeout number

Wait number of seconds for the ‘pass-fd’ socket to become available (see Meta1-Style Components). Default is 5 seconds.


Next: , Previous: , Up: Component Statement   [Contents][Index]

3.2.5 Exit Actions

The default behavior of pies when a ‘respawn’ component terminates is to restart it. Unless the component terminates with 0 exit code, a corresponding error message is issued to the log file. This behavior can be modified using return-code statement:

Config: component: return-code
return-code codes {
  …
}

The codes argument is a list of exit codes or signal names. Exit codes can be specified either as decimal numbers or as symbolic code names from the table below:

NameNumeric value
EX_OK0
EX_USAGE64
EX_DATAERR65
EX_NOINPUT66
EX_NOUSER67
EX_NOHOST68
EX_UNAVAILABLE69
EX_SOFTWARE70
EX_OSERR71
EX_OSFILE72
EX_CANTCREAT73
EX_IOERR74
EX_TEMPFAIL75
EX_PROTOCOL76
EX_NOPERM77
EX_CONFIG78

Table 3.3: Standard Exit Codes

Signal numbers can be given either as ‘SIG+n’, where n is the signal number, or as signal names from the following list: ‘SIGHUP’, ‘SIGINT’, ‘SIGQUIT’, ‘SIGILL’, ‘SIGTRAP’, ‘SIGABRT’, ‘SIGIOT’, ‘SIGBUS’, ‘SIGFPE’, ‘SIGKILL’, ‘SIGUSR1’, ‘SIGSEGV’, ‘SIGUSR2’, ‘SIGPIPE’, ‘SIGALRM’, ‘SIGTERM’, ‘SIGSTKFLT’, ‘SIGCHLD’, ‘SIGCONT’, ‘SIGSTOP’, ‘SIGTSTP’, ‘SIGTTIN’, ‘SIGTTOU’, ‘SIGURG’, ‘SIGXCPU’, ‘SIGXFSZ’, ‘SIGVTALRM’, ‘SIGPROF’, ‘SIGWINCH’, ‘SIGPOLL’, ‘SIGIO’, ‘SIGPWR’, ‘SIGSYS’.

If the component exits with an exit code listed in codes or is terminated on a signal listed in codes, pies executes actions specified in that ‘return-code’ block. The actions are executed in the order of their appearance below:

Config: return-code: exec command

Execute the supplied external command. Prior to execution, all file descriptors are closed. The command inherits the environment from the main pies process with the following additional variables:

PIES_VERSION

The pies version number (1.3).

PIES_COMPONENT

Tag of the terminated component (see tag).

PIES_PID

PID of the terminated component.

PIES_SIGNAL

If the component terminated on signal, the number of that signal.

PIES_STATUS

Program exit code.

Config: return-code: action disable | restart

If ‘restart’ is given, restart the component. This is the default. Otherwise, mark the component as disabled. Component dependents are stopped and marked as disabled as well. Once disabled, the components are never restarted, unless their restart is requested by the administrator.

Config: return-code: notify email-string

Send an email notification to addresses in email-string. See Notification, for a detailed discussion of this feature.

Config: return-code: message string

Supply notification message text to use by notify statement. See Notification, for a detailed discussion of this feature.

Any number of return-code statements are allowed, provided that their codes do not intersect.

The return-code statements can also be used outside of component block. In this case, they supply global actions, i.e. actions applicable to all components. Any return-code statements appearing within a component block override the global ones.


Next: , Previous: , Up: Component Statement   [Contents][Index]

3.2.6 Output Redirectors

Output redirectors allow to redirect the standard error and/or standard output of a component to a file or syslog facility.

Config: component: stderr type channel
Config: component: stdout type channel

Redirect standard error (if stderr) or standard output (if stdout) to the given channel.

The type of redirection is specified by type argument:

file

Redirect to a file. In this case channel gives the full name of the file. For example:

stderr file /var/log/component/name.err;
syslog

Redirect to a syslog channel. The syslog priority is given by the channel argument. Allowed values are: ‘emerg’, ‘alert’, ‘crit’, ‘err’, ‘warning’, ‘notice’, ‘info’, ‘debug’. The facility is inherited from the syslog statement (see syslog), or from the facility statement (see below), if given.

Example:

stderr syslog err;
Config: component: facility syslog-facility

Specify the syslog facility to use in syslog redirectors. Allowed syslog-facility values are: ‘user’, ‘daemon’, ‘auth’, ‘authpriv’, ‘mail’, ‘cron’, ‘local0’ through ‘local7’ (all names case-insensitive), or a facility number.


Next: , Previous: , Up: Component Statement   [Contents][Index]

3.2.7 Inetd-Style Components

Inetd-style components are declared using mode inetd statement. The ‘component’ declaration must contain a ‘socket’ statement:

Config: component: socket url

Define a socket to listen on. Allowed values for url are:

inet[+proto]://ip:port

Listen on IPv42 address ip (may be given as a symbolic host name), on port port. Optional proto defines the protocol to use. It must be a valid protocol name as given in /etc/protocols. Default is ‘tcp’.

local[+proto]://file[;args]
file[+proto]://file[;args]
unix[+proto]://file[;args]

Listen on the UNIX socket file file, which is either an absolute or relative file name, as described above. The proto part is as described above. Optional arguments, args, control ownership and file mode of file. They are a list of assignments, separated by semicolons. The following values are allowed:

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’).

For example:

socket
 "unix:///var/run/socket;user=nobody;group=mail;mode=770";

The file part may be a relative file name, provided that the chdir statement is used for this component (see chdir).

Config: component: socket-type type

Sets the socket type. Allowed values for type are: ‘stream’, ‘dgram’, ‘raw’, ‘rdm’, ‘seqpacket’. Default is ‘stream’. Notice that some socket types may not be implemented by all protocol families, e.g. ‘seqpacket’ is not implemented for ‘inet’.

Config: component: max-rate n

Specifies the maximum number of times the component can be invoked in one minute; the default is unlimited. A rate of ‘0’ stands for ‘unlimited’.

Config: component: max-instances n

Sets the maximum number of simultaneously running instances of this component. It is equivalent to the maximum number of simultaneously opened connections.

Config: component: max-instances-message text

Text to send back if max-instances is reached. This is valid only for TCP sockets.

Config: component: max-ip-connections number

Maximum number of connections that can be opened simultaneously from a single IP address.

Config: component: max-ip-connections-message text

Textual message to send in reply to an incoming TCP connection from the IP address that has already reached max-ip-connections limit.

Config: component: acl { … }

Set access control list for this component. This is valid only for ‘inetd’ and ‘accept’ components. See ACL, for a detailed description of access control lists.

Config: component: access-denied-message text

Textual message to send in reply to an incoming TCP connection that has been denied by ACL settings.


Next: , Up: Inetd-Style Components   [Contents][Index]

3.2.7.1 Built-in Inetd Services

Built-in or internal services are such inetd-style components that are supported internally by pies and do not require external programs. In pies version 1.3 those are:

echo

Send back any received data. Defined in RFC 862.

discard

Read the data and discard them. Defined in RFC 863.

time

Return a machine readable date and time as seconds since the Epoch. Defined in RFC 868.

daytime

Return current date and time in human-readable format. Defined in RFC 867.

chargen

Send a continuous stream of ASCII printable characters without regard to the input. Defined in RFC 864

qotd

Send a ‘quotation of the day’ text without regard to the input. Defined in RFC 865.

tcpmux

TCP Port Service Multiplexer. Defined in RFC 1078.

A definition of a built-in service component must have the internal flag (see flags) set. It may not contain command or program statements, as built-in services do not need external programs. Instead, a service declaration must be present:

Config: component: service name

Set the built-in service name. Its argument is one of the keywords listed in the above table.

For example, the following component declaration defines a standard TCP-based echo service:

component echo {
        socket "inet://0.0.0.0:echo";
        service echo;
        flags internal;
}

It corresponds to the following inetd.conf line:

echo stream  tcp     nowait  root    internal

Another built-in services are defined in the same manner, replacing ‘echo’ in the service field with the corresponding service name.

The ‘qotd’ service reads the contents of the qotd file and sends it back to the client. By default the ‘qotd’ file is located in the local state directory and named instance.qotd (where instance is the name of the pies instance; see instances). This default location can be changed using the following statement:

Config: qotd-file file-name

Set the name of the ‘quotation-of-the-day’ file.

The text read from the ‘qotd’ file is preprocessed, by replacing each LF character (ASCII 10) with two characters: CR (ASCII 13) followed by LF. The resulting text is truncated to 512 characters.

The use of ‘tcpmux’ services is covered below.


Next: , Previous: , Up: Inetd-Style Components   [Contents][Index]

3.2.7.2 TCPMUX Services

TCPMUX allows to use multiple services on a single well-known TCP port using a service name instead of a well-known number. It is defined in RFC 1078. The protocol operation is as follows. The master TCPMUX component listens on a certain TCP port (usually on port 1) for incoming requests. After connecting to the master, the client sends the name of the service it wants, followed by a carriage-return line-feed (CRLF). Pies looks up this name in the list of services handled by the master (subordinate services) and reports with ‘+’ or ‘-’ followed by optional text and terminated with the CRLF, depending on whether such service name is found or not. If the reply was ‘+’, pies then starts the requested component. Otherwise, it closes the connection.

TCPMUX service names are case-insensitive. The special service ‘help’ is always defined; it outputs a list of all the subordinate services, one name per line, and closes the connection.

The master TCPMUX service is declared as a usual built-in service, e.g.:

component tcpmux-master {
        socket "inet://0.0.0.0:1";
        service tcpmux;
        flags internal;
}

Any number of subordinate services may be defined for each master. A subordinate server component definition must contain at least the following statements:

Config: component: service name

Sets the name of the subordinate service. The name will be compared with the first input line from the client.

Config: component: tcpmux-master name

Sets the name of the master TCPMUX service.

Config: component: flags list

The flags statement (see flags) must contain at least one of the following flags:

tcpmux

A “dedicated” TCPMUX subordinate service. When invoked, it must output the ‘+ CRLF’ response itself.

tcpmuxplus

Simple service. Before starting it, pies will send the ‘+ CRLF’ reply.

Config: component: command command-line

The command line for handling this service.

For example:

component scp-to {
        service scp-to;
        flags (tcpmuxplus, sockenv);
        tcpmux-master tcpmux;
        command "/usr/sbin/in.wydawca";
}

For TCPMUX services, access control lists are handled in the following order. First, the global ACL is checked. If it rejects the connection, no further checks are done. Then, if the master TCPMUX service has an ACL, that ACL is consulted. If it allows the connection, the subordinate is looked up. If found, its ACL (if any) is consulted. Only if all three ACLs allow the connection, is the service started.

A similar procedure applies for other resources, such as limits, umask, env, user, group, etc.


Next: , Previous: , Up: Inetd-Style Components   [Contents][Index]

3.2.7.3 Socket Environment Variables

If the ‘sockenv’ flag is set (see sockenv), the following environment variables are set prior to executing the command:

PROTO

Protocol name.

SOCKTYPE

Socket type. See socket-type, for a list of possible values.

LOCALIP

IP address of the server which is handling the connection.

LOCALPORT

Local port number.

LOCALHOST

Host name of the server. This variable is defined only if the ‘resolve’ flag is set (see resolve).

REMOTEIP

IP address of the remote party (client).

REMOTEPORT

Port number on the remote side.

REMOTEHOST

Host name of the client. This variable is defined only if the ‘resolve’ flag is set (see resolve).

The variables whose names begin with REMOTE are defined only for TCP connections.


Previous: , Up: Inetd-Style Components   [Contents][Index]

3.2.7.4 Exit Actions in Inetd Components

Exit actions (see Exit Actions) work for ‘inet-style’ components. The only difference from ‘respawn’ components is that the ‘restart’ action is essentially ignored, as it makes no sense to start an ‘inet-style’ component without a communication socket.

A common use of return-code statement is to invoke an external program upon the termination of a component. For example, the following configuration snippet configures an FTP server and ensures that a special program is invoked after closing each FTP connection:

component ftp {
    return-code EX_OK {
        exec "/sbin/sweeper --log";
    }
    mode inetd;
    socket "inet://0.0.0.0:21";
    umask 027;
    program /usr/sbin/in.ftpd
    command "ftpd -ll -C -t180";
}

This approach may be used to process FTP uploads in real time.


Next: , Previous: , Up: Component Statement   [Contents][Index]

3.2.8 Meta1-Style Components

Meta1-style components are declared using mode pass statement. For such components, you must declare both a socket to listen on (see inetd-socket and a UNIX socket name to pass the file descriptor to the component. The latter is defined using pass-fd-socket statement:

Config: component: pass-fd-socket file-name

The argument is an absolute or relative file name of the socket file. In the latter case, the chdir dir statement must be used for this component (see chdir), and the socket will be looked under dir.

This socket file is supposed to be created by the component binary upon its startup.


Next: , Previous: , Up: Component Statement   [Contents][Index]

3.2.9 Component Visibility ACLs

Pies control interface allows certain users to list and modify components of a running pies instance. Two access control lists define who can list and modify the particular component.

Config: component: list-acl name
Config: component: list-acl { … }

This list controls who can get listing of this component (see piesctl list).

In the first form, name refers to the name of an already defined global ACL (see defacl).

The second form defines new unnamed ACL. The syntax is described in detail in ACL.

Config: component: admin-acl name
Config: component: admin-acl { … }

This list controls who can stop, restart or otherwise modify this component (see components).

As above, two forms are available: the first one for using an already defined named ACL, and the second one, for defining a new ACL in place.


Previous: , Up: Component Statement   [Contents][Index]

3.2.10 Component Syntax Summary

This subsection summarizes the component statements. For each statement, a reference to its detailed description is provided.

component tag {
  # Component execution mode.
  # See mode.
  mode ‘exec | wait | accept | inetd | nostartaccept | pass-fd | pass’;
  
  # Full name of the program.
  # See program.
  program name;
  # Command line.
  # See command.
  command string;
  
  # List of prerequisites.
  # See Prerequisites.
  prerequisites (compnames);
  # List of components for which this one is a prerequisite.
  # See dependents.
  dependents (compnames);

  # List of flags.
  # See flags.
  flags (flags);

  # For init components: runlevels in which to start this
  # component.
  # See Runlevels.
  runlevels string;
  
  # Listen on the given url.
  # See Inetd-Style Components.
  socket url;

  # Set socket type.
  # See Inetd-Style Components.
  socket-type ‘stream | dgram | raw | rdm | seqpacket’;

  # Service name for built-in inetd component.
  # See builtin.
  service string;

  # Tag of master TCPMUX component, for subordinate components.
  # See TCPMUX.
  tcpmux-master string;
  
  # Pass fd through this socket.
  # See Meta1-Style Components.
  pass-fd-socket soket-name;
  # Wait number of seconds for pass-fd socket to become available.
  # See pass-fd-timeout.
  pass-fd-timeout number;

  # Maximum number of running instances.
  # See max-instances.
  # See max-instances.
  max-instances number;

  # For ‘inetd’ components:
  # Text to send back if max-instances is reached.
  # See max-instances-message.
  max-instances-message text;
  
  # Maximum number of times an inetd component can be invoked in
  # one minute.
  # See max-rate.
  max-rate number;

  # For ‘inetd’ components:
  # Max. number of simultaneous connections from a single IP address.
  # See max-ip-connections.
  max-ip-connections number;
  
  # For ‘inetd’ components:
  # Text to send back if max-ip-connections is reached.
  # See max-ip-connections-message.
  max-ip-connections-message text;

  # For ‘inetd’ components:
  # Text to send back if access is denied by ACL.
  # See access-denied-message.
  access-denied-message text;

  # ACL for administrative (read-write) access to this component.
  # See Visibility.
  admin-acl name;
  # or:
  admin-acl { … }

  # ACL for read-only access to this component.
  # See Visibility.
  list-acl name;
  # or:
  list-acl { … }
  
  # ACL for this component.
  # See ACL.
  acl name;
  # or:
  acl { … }
  
  # Override default syslog facility for this component.
  facility facility;
  # Redirect program’s standard output to the given
  # file or syslog priority.
  # See Output Redirectors.
  stdout ‘file | syslogchannel;
  # Redirect program’s standard error to the given
  # file or syslog priority.
  # See Output Redirectors.
  stderr ‘file | syslogchannel;
  
  # Run with this user privileges.
  # See Component Privileges.
  user user-name;
  # Retain supplementary group.
  # See group.
  group group-name;
  # Retain all supplementary groups of which user is a member.
  # See allgroups.
  allgroups bool;
  
  # Set system limits.
  # See Resources.
  limits string;
  
  # Force this umask.
  # See umask.
  umask number;
  
  # Set program environment.
  # See env.
  env assignments;
  
  # Change to this directory before executing the component.
  # See chdir.
  chdir dir;
  # Remove file-name before starting the component.
  # See remove-file.
  remove-file file-name;
  
  # Actions:
  # See Exit Actions.
  return-code exit-code-list {
    # Action to take when a component finishes with this return code.
    action ‘disable | restart’;
    # Notify these addresses when then component terminates.
    notify email-string;
    # Notification message text (with headers).
    message string;
    # Execute this command.
    exec command
  }
}

Footnotes

(2)

Support for IPv6 will be added in future versions.


Previous: , Up: Component Statement   [Contents][Index]