GNU Pies Manual (split by chapter):   Section:   Chapter:FastBack: Pies Debugging   Up: Top   FastForward: Init Process   Contents: Table of ContentsIndex: Concept Index

5 Communicating with Running pies Instances

The piesctl tool allows you to communicate with the running pies program. The invocation syntax is:

piesctl [options] command [args...]

The command determines the operation to perform. The following sections describe available commands in detail.

5.1 piesctl id – Return Info About the Running Instance

The id subcommand returns information about the pies instance organized as key-value pairs. When invoked without arguments, the following data are returned:

package

Canonical package name.

version

Version of pies.

instance

Instance name (see instances).

binary

Full pathname of the pies executable file.

argv

Command line arguments supplied upon its startup.

PID

Process ID.

For example:

$ piesctl id
package: GNU Pies
version: 1.4
instance: pies
binary: /usr/sbin/pies
argv: /usr/sbin/pies --config-file=/etc/pies/pies.conf
PID: 15679

To request a subset of these data, give the items of interest as command line arguments:

$ piesctl id binary PID
binary: /usr/sbin/pies
PID: 15679

5.2 Instance Management

Two subcommands are provided for stopping and restarting pies.

piesctl: shutdown

Stop the running pies instance

piesctl: reboot

Restart pies instance. Upon receiving this command, pies will restart itself with the same command line arguments. Naturally, this means that all running components will be restarted as well.

These subcommands do nothing when init process is selected.

5.3 piesctl config – Configuration Management

piesctl: config file list

List currently loaded configuration files.

piesctl: config file clear

Clear configuration file list

piesctl: config file add syntax file

Add file to the list of configuration files. syntax specifies its syntax: ‘pies’, ‘inetd’, ‘meta1’, or ‘inittab’.

piesctl: config file del[ete] name [name...]

Remove listed names from the list of configuration files.

piesctl: config reload

Reload configuration.

5.4 Component Management

piesctl: list [condition]

List configured components. When used without arguments, all components are listed. Otherwise, only processes matching condition are listed.

Each output line contains at least two columns. The first column lists the tag of the component. The second one contains flags, describing the type and status of the component. The first flag describes the type:

FlagMeaning
3SysV init ‘ctrlaltdel’ component
AAccept-style component
BSysV init ‘boot’ component
CRespawn component
cSysV init ‘once’ component
DSysV init ‘ondemand’ component
ECommand being executed
FSysV init ‘powerfail’ component
fSysV init ‘powerwait’ component
IInetd-style component
iSysV init ‘sysinit’ component
kSysV init ‘kbrequest’ component
nSysV init ‘powerfailnow’ component
oSysV init ‘powerokwait’ component
PPass-style component
ROutput redirector
WSysV init ‘wait’ component
wSysV init ‘bootwait’ component

The second flag is meaningful only for components. Its values are:

FlagMeaning
-Disabled component
fA finished ‘once’ component
LInetd listener
RRunning component
SComponent is stopping
sComponent is sleeping
TComponent is stopped

The next column lists the PID (for running components) or socket address (for Internet listeners), or the string ‘N/A’ if neither of the above applies.

If the component is sleeping, the time of its scheduled wake-up is listed in the next column.

Rest of line shows the component command line.

$ piesctl list
smtps/stderr R  4697
pmult/stderr R  4677
pmult/stdout R  4676
pmult        CR 4678 /usr/local/sbin/pmult
smar         CR 4680 smar -f /etc/meta1/meta1.conf -d 100
qmgr         CR 4691 qmgr -f /etc/meta1/meta1.conf
smtpc        CR 4696 smtpc -f /etc/meta1/meta1.conf
smtps        PR 4698 smtps -d100 -f /etc/meta1/meta1.conf
finger       IL inet+tcp://0.0.0.0:finger /usr/sbin/in.fingerd -u
eklogin      IL inet+tcp://0.0.0.0:eklogin /usr/sbin/klogind -k -c -e
kshell       IL inet+tcp://0.0.0.0:kshell /usr/sbin/kshd -k -c
eklogin      IR 13836  /usr/local/sbin/klogind -k -c -e

Use condition to select the components to list. In its simplest form, condition is one of the following terms:

all

Selects all processes, including internal services, such as output redirectors.

active

Selects only active components.

component tag

Selects the component with the given tag. See tag.

type arg

Selects processes of the given type. Argument is ‘component’, to select only components, ‘command’, to select commands or ‘redirector’ to select output redirectors. When piesctl list is used without arguments, type component is assumed.

mode arg

Selects components of the given mode (see mode). E.g. to list ‘inetd’ components:

piesctl list mode inetd
status arg

Selects processes with the given status. Argument is one of:

finished

Component is finished.

listener

Component is an inet listener.

running

Component is running.

sleeping

Component is sleeping.

stopped

Component is stopped.

stopping

Component has been sent the SIGTERM signal and pies is waiting for it to terminate.

A term may be preceded by the word ‘not’ to indicate negation of the condition. For example, the following command will list inactive components:

piesctl list not active

Furthermore, terms can be combined in logical expressions using boolean ‘and’ and ‘or’ operators:

piesctl list type component and not mode inetd

Conjunction (‘and’) has higher precedence than disjunction (‘or’). In complex expressions parentheses can be used to alter the precedence:

piesctl list type component \
        and \( status running or status sleeping \)

Notice that parentheses must be escaped to prevent them from being interpreted by the shell.

The following summarizes the syntax of condition in BNF:

<condition> ::= <disjunction>
<disjunction> ::= <conjunction> | <conjunction> "or" <disjunction>
<conjunction> ::= <unary> | <unary> "and" <conjunction>
<unary> ::= <term> | "not" <condition> | "(" <condition> ")"
<term> ::= "all" | "active" | <keyword> <value>
<keyword> ::= "type" | "mode" | "status" | "component"
<value> ::= <word> | <quoted-string>
<word> ::= <printable> | <word> <printable>
<printable> ::= "A" - "Z" | "a" - "z" | "0" - "9" |
                "_" | "." | "*" | ":" | "@" | "[" | "]" | "-" | "/"
<quoted-string> ::= """ <string> """
<string> ::= <char> | <string> <char>
<char> ::= <any character except "\" and """> | "\\" | "\""
piesctl: stop condition

Stop components matching condition.

piesctl: start condition

Start components matching condition.

piesctl: restart condition

Restart components.

5.5 Init Process Management

The piesctl telinit command communicates with pies instance running as init process (PID 1). See piesctl telinit, for a detailed discussion.

5.6 Piesctl Command Line Options

-c file
--config-file=file

Read configuration from file instead of the default /etc/piesctl.conf. See piesctl.conf, for its description.

-d
--dump

Dump obtained responses verbatim. This is useful mainly for debugging purposes.

-i inst
--instance=inst

Talk to pies instance inst.

--no-netc
-N

Don’t read ~/.netrc file.

-u url
--url=url

Specifies the URL of the communication socket. See piesctl url, for a description of allowed URL forms.

-v
--verbose

Enable verbose diagnostics.

Before parsing, configuration file is preprocessed using m4. The following options control this feature:

-E

Show preprocessed configuration on stdout and exit.

--define=sym[=value]
-D symbol[=value]

Define symbol sym as having value, or empty, if the value is not given.

--include-directory=dir
-I dir

Add directory dir to the list of directories to be scanned for include files. See include search path.

--undefine=sym
-U sym

Undefine symbol sym.

Finally, the following options can be used to obtain on-line assistance:

--config-help

Show a terse reference to configuration file syntax and exit.

-h
--help

Display command line help summary.

--usage

Give a short usage message

-V
--version

Show program version.

5.7 Configuration for piesctl

The configuration file /etc/piesctl.conf helps the piesctl tool to determine the URL of the control socket. This file is not mandatory, and its absence is not considered an error. Its syntax is similar to that of /etc/pies.conf. The following statements are defined:

piesctl.conf: socket url

Sets the default socket URL.

piesctl.conf: source ip

Sets the default source IP address. This is used if the control socket is of ‘inet’ type.

piesctl.conf: instance name

Configures socket URL and (optionally) source address to use when communicating with the pies instance name (i.e., when invoked as piesctl -i name:

instance name {
    # Socket URL for that instance.
    socket url;
    # Source IP address.
    source ip;
}

Valid values for url in the above statements are:

inet://ip:port

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

local://file
file://file
unix://file

Use the UNIX socket file file.

The following algorithm is used to determine the name of the communication socket:

  1. If the --url (-u) option is given, use its argument.
  2. Determine the instance name (inst). If the --instance (-i) is given, inst is its argument. Otherwise, assume inst=‘pies’.
  3. If configuration file /etc/piesctl.conf exists, read it. On success:
    1. See if the instance inst statement is present and has socket substatement. If so, the argument to socket gives the socket URL.
    2. Otherwise, if global socket statement is present, its argument gives the URL.
  4. Otherwise, suppose that piesctl is run on the same box where the target instance of pies is running, and see if the file /etc/inst.conf exists. If so, parse it as pies configuration file and look for control block statement. If it has socket statement, take its argument as the URL. See control.
  5. If socket URL is not determined by these steps, assume /tmp/inst.ctl.

GNU Pies Manual (split by chapter):   Section:   Chapter:FastBack: piesctl   Up: piesctl   FastForward: Init Process   Contents: Table of ContentsIndex: Concept Index