Improve docs

* doc/pies.texi: Document piesctl and identity providers.
* src/piesctl.c: Fix reference to the docs.

1 files changed, 594 insertions, 72 deletions

diff --git a/doc/pies.texi b/doc/pies.texi
index 1f162a2..c72ac3e 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -29,12 +29,15 @@
 
 @ifinfo
 @dircategory System Administration
 @direntry
 * GNU Pies: (pies).             Program Invocation and Execution Supervisor.
 * pies: (pies) Invocation.      GNU Pies Command Line Options.
+* pies.conf: (pies) Configuration.    GNU Pies Configuration File.
+* piesctl: (pies) piesctl.            GNU Pies Control Tool.
+* piesctl.conf: (pies) piesctl.conf.  Configuration File for the @command{piesctl} tool.
 @end direntry
 @end ifinfo
 
 @copying
 Published by the Free Software Foundation,
 51 Franklin Street, Fifth Floor,
@@ -73,16 +76,16 @@ This edition of the @cite{GNU Pies Manual}, last updated @value{UPDATED},
 documents @command{pies} Version @value{VERSION}.
 @end ifnottex
 
 @menu
 * Intro::                    Introduction to Process Management with @command{Pies}.
 * Dependencies::             Inter-process dependencies.
-* Pies Configuration File::  Configuration Files of Various Syntaxes.
+* Configuration::            Configuration Files of Various Syntaxes.
 * Pies Debugging::           Debugging @command{Pies}.
 * piesctl::                  Communication with Running @command{pies} Instances.
-* Init Process::             @command{Pies} as Parent of All Processes.
+* Init Process::             Using @command{Pies} as Parent of All Processes.
 * Configuration Examples::   Examples of Configuration Files.
 * Command Line Usage::
 * Invocation::
 * Reporting Bugs::
 
 Appendices
@@ -96,16 +99,17 @@ Appendices
  --- The Detailed Node Listing ---
 
 Pies Configuration File
 
 * Syntax::               Configuration File Syntax
 * Component Statement::
-* Notification::         Mail Notification
-* ACL::                  Access Control Lists
-* inetd::                Using @command{inetd} Configuration Files
-* include-meta1::        Using @command{meta1} Configuration Files
+* Notification::         Mail Notification.
+* ACL::                  Access Control Lists.
+* control::              The @samp{control} statement.
+* inetd::                Using @command{inetd} Configuration Files.
+* include-meta1::        Using @command{meta1} Configuration Files.
 * Global Configuration::
 * Pies Privileges::
 * State Files::
 
 Configuration File Syntax
 
@@ -120,21 +124,40 @@ Component Statement
 * Resources::
 * Actions Before Startup::
 * Exit Actions::
 * Output Redirectors::
 * Inetd-Style Components::
 * Meta1-Style Components::
+* Visibility::
 * Component Syntax Summary::
 
 Inetd-Style Components
 
 * builtin::    Built-in Inetd Services
 * TCPMUX::     TCPMUX Services
 * sockenv::    Socket Environment Variables
 * inetd exit:: Exit Actions in Inetd Components
 
+Communicating with Running @command{pies} Instances
+
+* id::          Get Info About the Running Instance.
+* stop and reboot:: Instance Management.
+* config::      Configuration Management.
+* components::  Component Management.
+@c * telinit::
+* piesctl.conf:: Configuration file for @command{piesctl}.
+
+Init -- parent of all processes
+
+* Runlevels::
+* Init Process Configuration::
+* Init Command Line::
+* Init Environment::
+* piesctl telinit::
+* telinit command::
+
 Configuration Examples
 
 * Simple Pies::
 * Hairy Pies::
 * Inetd Pies::
 
@@ -230,13 +253,13 @@ startup.  Components @samp{B} and @samp{C} are called
   Before restarting any component, @command{pies} verifies if it is a
 prerequisite for any other components.  If so, it first terminates its
 dependencies, restarts the component, and then starts its
 dependencies again, in the order of their appearance in the
 configuration file.
 
-@node Pies Configuration File
+@node Configuration
 @chapter Pies Configuration File
 @cindex configuration file
 @flindex pies.conf
 @xopindex{config-file, introduced}
   @command{Pies} reads its settings and component definitions from one
 or more @dfn{configuration files}.  The default configuration file
@@ -320,12 +343,13 @@ line option.
 @menu
 * Syntax::               Configuration File Syntax
 * Component Statement::
 * Notification::         Mail Notification.
 * ACL::                  Access Control Lists.
 * control::              The @samp{control} statement.
+* Identities::           User Identities for Accessing Control Interface.
 * inetd::                Using @command{inetd} Configuration Files.
 * include-meta1::        Using @command{meta1} Configuration Files.
 * Global Configuration::
 * Pies Privileges::
 * State Files::
 @end menu
@@ -1047,13 +1071,13 @@ to become available (@pxref{Meta1-Style Components}).  Default is
 5 seconds.
 @end deffn
 
 @node Exit Actions
 @subsection Exit Actions
 @kwindex return-code
-  The default behavior of @command{pies} when an @samp{init-style}
+  The default behavior of @command{pies} when a @samp{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
 @code{return-code} statement:
 
 @deffn {Config: component} return-code
@@ -1547,13 +1571,13 @@ the @samp{resolve} flag is set (@pxref{flags,resolve}).
 for @acronym{TCP} connections.
 
 @node inetd exit
 @subsubsection Exit Actions in Inetd Components
 
   Exit actions (@pxref{Exit Actions}) work for @samp{inet-style} components.
-The only difference from @samp{init-style} components is that the
+The only difference from @samp{respawn} components is that the
 @samp{restart} action is essentially ignored, as it makes no sense to
 start an @samp{inet-style} component without a communication socket.
 
   A common use of @code{return-code} statement is to invoke an
 external program upon the termination of a component.  For example,
 the following configuration snippet configures an @acronym{FTP} server
@@ -1601,25 +1625,25 @@ upon its startup.
 components of a running @command{pies} instance.  Two access control
 lists define who can list and modify the particular component.
 
 @deffn {Config: component} list-acl @var{name}
 @deffnx {Config: component} list-acl @{ @dots{} @}
 This list controls who can get listing of this component
-(@FIXME-pxref{component listing}).
+(@pxref{piesctl list}).
 
 In the first form, @var{name} refers to the name of an already defined
 global ACL (@pxref{defacl}).
 
 The second form defines new unnamed ACL.  The syntax is described in
 detail in @ref{ACL}.
 @end deffn
 
 @deffn {Config: component} admin-acl @var{name}
 @deffnx {Config: component} admin-acl @{ @dots{} @}
 This list controls who can stop, restart or otherwise modify this
-component (@FIXME-pxref{component management}).
+component (@pxref{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.
 @end deffn
 
 @node Component Syntax Summary
@@ -2189,12 +2213,92 @@ is checked.  If it allows access, then the per-component ACL is tried.
 If it allows access too, then the operation is permitted.
 
 @deffn {Config: control} realm @var{name}
   Defines the realm for basic authentication.  Default value is @samp{pies}.
 @end deffn
 
+@node Identities
+@section User Identities for Accessing Control Interface
+
+  Privileges for using and performing various commands over the
+control interface can be distributed among several users.  For
+example, it is possible to grant some users the rights to only view
+the component listing, or even to further limit their rights to only
+see the components they are authorized to know about.  Another user
+may be able to stop or restart components and so on.  This privilege
+separation requires @command{pies} to have a notion of user and be
+able to authenticate it.
+
+  @dfn{Identity provider} is an abstract mechanism that @command{pies}
+uses to obtain information about the user trying to authenticate
+himself for accessing a particular control function.  As of version
+@value{VERSION}, this mechanism is considered experimental.  That
+means, that although being fully functional, it can change
+considerably in future releases.
+
+  Identity provider supports two operations: authenticating a user,
+and checking if he is a member of particular @dfn{group}.  It is
+defined in the configuration file using the @code{identity provider}
+statement.  
+
+@deffn {Config} identity-provider @var{name}
+Defines an identity provider.  It is a block statement:
+
+@example
+identity-provider @var{name} @{
+  type @var{type};
+  @dots{}
+@}
+
+The provider @var{name} is used in diagnostic messages.
+@end example
+
+The only required substatement is @code{type}, which defines the type
+of the provider.  Rest of statements (represented by @dots{} above)
+depends on the type.
+@end deffn
+
+Pies version @value{VERSION} supports identity providers of two types:
+@samp{system} and @samp{pam}.
+
+The @samp{system} identity provider uses system user database for
+authentication and system group database for checking group membership.
+It is declared using the following statement:
+
+@example
+@group
+identity-provider @var{name} @{
+    type system;
+@}
+@end group
+@end example
+
+Obviously, to use the system identity provider for authentication,
+@command{pies} must be run as root.
+
+The @samp{pam} identity provider uses the Pluggable Authentication
+Modules (@acronym{PAM}) for authentication, and system group database
+for checking group membership.
+
+@example
+@group
+identity-provider @var{name} @{
+    type pam;
+    service @var{srv};
+@}
+@end group
+@end example
+
+The @samp{service} statement defines the name of PAM service to use
+for authentication.  If absent, the name @samp{pies} is used.
+
+Any number of different identity providers can be declared in the
+configuration file.  When authenticating the user, they will be tried
+in turn until the one is found where authentication succeeds.
+Subsequent group membership checks will then use this identity provider.
+
 @node inetd
 @section Using @command{inetd} Configuration Files
 @cindex inetd.conf
 @flindex /etc/inetd.conf
   In addition to its native configuration file format, GNU
 @command{pies} is able to read configuration files of several other
@@ -2521,13 +2625,466 @@ source-info yes;
 
 This feature is designed for @command{pies} developers.
 @end deffn
 
 @node piesctl
 @chapter Communicating with Running @command{pies} Instances
-@WRITEME
+  The @command{piesctl} tool allows you to communicate with the
+running @command{pies} program.  The invocation syntax is:
+
+@example
+piesctl [@var{options}] @var{command} [@var{args}...]
+@end example
+
+The @var{command} determines the operation to perform.  The following
+sections describe available commands in detail.
+
+@menu
+* id::          Get Info About the Running Instance.
+* stop and reboot:: Instance Management.
+* config::      Configuration Management.
+* components::  Component Management.
+* telinit::     Init Process Management.
+* options::      @command{piesctl} options.  
+* piesctl.conf:: Configuration file for @command{piesctl}.
+@end menu
+
+@node id
+@section piesctl id -- Return Info About the Running Instance
+@cindex id, piesctl
+@cindex piesctl id
+  The @option{id} subcommand returns information about the
+@command{pies} instance organized as key-value pairs.  When invoked
+without arguments, the following data are returned:
+
+@table @asis
+@item package
+Canonical package name.
+@item version
+Version of @command{pies}.
+@item instance
+Instance name (@pxref{instances}).
+@item binary
+Full pathname of the @command{pies} executable file.
+@item argv
+Command line arguments supplied upon its startup.
+@item PID
+Process ID.
+@end table
+
+For example:
+
+@example
+@group
+$ piesctl id
+package: GNU Pies
+version: @value{VERSION}
+instance: pies
+binary: /usr/sbin/pies
+argv: /usr/sbin/pies --config-file=/etc/pies/pies.conf
+PID: 15679
+@end group
+@end example
+
+To request a subset of these data, give the items of interest as
+command line arguments:
+
+@example
+@group
+$ piesctl id binary PID
+binary: /usr/sbin/pies
+PID: 15679
+@end group
+@end example
+
+@node stop and reboot
+@section Instance Management
+
+Two subcommands are provided for stopping and restarting @command{pies}.
+
+@deffn {piesctl} shutdown
+Stop the running @command{pies} instance
+@end deffn
+
+@deffn {piesctl} reboot
+Restart @command{pies} instance.  Upon receiving this command,
+@command{pies} will restart itself with the same command line
+arguments.  Naturally, this means that all running components will
+be restarted as well. 
+@end deffn
+
+These subcommands do nothing when init process is selected.
+
+@node config
+@section piesctl config -- Configuration Management
+
+@deffn {piesctl} config file list
+List currently loaded configuration files.
+@end deffn
+
+@deffn {piesctl} config file clear
+Clear configuration file list
+@end deffn
+
+@deffn {piesctl} config file add @var{syntax} @var{file}
+Add @var{file} to the list of configuration files.  @var{syntax}
+specifies its syntax: @samp{pies}, @samp{inetd}, @samp{meta1}, or
+@samp{inittab}.
+@end deffn
+
+@deffn {piesctl} config file del[ete] @var{name} [@var{name}...]
+Remove listed names from the list of configuration files.
+@end deffn
+
+@anchor{config reload}
+@deffn {piesctl} config reload
+Reload configuration.
+@end deffn
+
+@node components
+@section Component Management
+
+@anchor{piesctl list}
+@deffn {piesctl} list [@var{condition}]
+List configured components.  When used without arguments, all
+components are listed.  Otherwise, only processes matching
+@var{condition} are listed.
+
+  Each output line contains at least two columns.  The first column
+lists the tag of the component.  The second one contains @dfn{flags},
+describing the type and status of the component.  The first flag
+describes the type:
+
+@multitable @columnfractions 0.2 0.7
+@headitem Flag @tab Meaning
+@item 3        @tab SysV init @samp{ctrlaltdel} component
+@item A        @tab Accept-style component
+@item B        @tab SysV init @samp{boot} component
+@item C        @tab Respawn component
+@item c        @tab SysV init @samp{once} component
+@item D        @tab SysV init @samp{ondemand} component
+@item E        @tab Command being executed
+@item F        @tab SysV init @samp{powerfail} component
+@item f        @tab SysV init @samp{powerwait} component
+@item I        @tab Inetd-style component
+@item i        @tab SysV init @samp{sysinit} component
+@item k        @tab SysV init @samp{kbrequest} component
+@item n        @tab SysV init @samp{powerfailnow} component
+@item o        @tab SysV init @samp{powerokwait} component
+@item P        @tab Pass-style component
+@item R        @tab Output redirector
+@item W        @tab SysV init @samp{wait} component
+@item w        @tab SysV init @samp{bootwait} component
+@end multitable
+
+  The second flag is meaningful only for components.  Its values are:
+
+@multitable @columnfractions 0.2 0.7
+@headitem Flag @tab Meaning
+@item -        @tab Disabled component
+@item f        @tab A finished @samp{once} component 
+@item L        @tab Inetd listener
+@item R        @tab Running component
+@item S        @tab Component is stopping
+@item s        @tab Component is sleeping
+@item T        @tab Component is stopped
+@end multitable
+
+  The next column lists the PID (for running components) or socket address
+(for Internet listeners), or the string @samp{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.
+
+@example
+@group
+$ 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
+@end group
+@end example
+@end deffn
+
+Use @var{condition} to select the components to list.  In its simplest
+form, @var{condition} is one of the following @dfn{terms}:
+
+@table @asis
+@item all
+Selects all processes, including internal services, such as output
+redirectors.
+
+@item active
+Selects only active components.
+
+@item component @var{tag}
+Selects the component with the given tag.  @xref{Component Statement, tag}.
+
+@item type @var{arg}
+Selects processes of the given type.  Argument is @samp{component}, to
+select only components, @samp{command}, to select commands or
+@samp{redirector} to select output redirectors.  When @command{piesctl
+list} is used without arguments, @option{type component} is assumed.
+
+@item mode @var{arg}
+Selects components of the given mode (@pxref{Component Statement,
+mode}).  E.g. to list @samp{inetd} components:
+
+@example
+piesctl list mode inetd
+@end example
+
+@item status @var{arg}
+Selects processes with the given status.  Argument is one of:
+
+@table @asis
+@item finished
+Component is finished.
+
+@item listener
+Component is an inet listener.
+
+@item running
+Component is running.
+
+@item sleeping
+Component is sleeping.
+
+@item stopped
+Component is stopped.
+
+@item stopping
+Component has been sent the SIGTERM signal and @command{pies} is
+waiting for it to terminate.
+@end table
+@end table
+
+A term may be preceded by the word @samp{not} to indicate negation of
+the condition.  For example, the following command will list inactive
+components:
+
+@example
+piesctl list not active
+@end example
+
+Furthermore, terms can be combined in logical expressions using
+boolean @samp{and} and @samp{or} operators:
+
+@example
+piesctl list type component and not mode inetd
+@end example
+
+Conjunction (@samp{and}) has higher precedence than disjunction
+(@samp{or}).  In complex expressions parentheses can be used to
+alter the precedence:
+
+@example
+piesctl list type component \
+        and \( status running or status sleeping \)
+@end example
+
+Notice that parentheses must be escaped to prevent them from being
+interpreted by the shell.
+
+The following summarizes the syntax of @var{condition} in BNF:
+
+@example
+<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 """> | "\\" | "\""
+@end example
+
+@deffn {piesctl} stop @var{condition}
+Stop components matching @var{condition}.
+@end deffn
+
+@deffn {piesctl} start @var{condition}
+Start components matching @var{condition}.
+@end deffn
+
+@deffn {piesctl} restart @var{condition}
+Restart components.
+@end deffn
+
+@node telinit
+@section Init Process Management
+
+The @command{piesctl telinit} command communicates with @command{pies}
+instance running as @dfn{init} process (PID 1).  @xref{piesctl
+telinit}, for a detailed discussion.
+
+@node options
+@section @command{Piesctl} Command Line Options
+
+@table @option
+@item -c @var{file}
+@itemx --config-file=@var{file}
+Read configuration from @var{file} instead of the default
+@file{/etc/piesctl.conf}.  @xref{piesctl.conf}, for its description.
+
+@item -d
+@itemx --dump
+Dump obained responses verbatim.  This is useful mainly for debugging
+purposes.
+
+@item -i @var{inst}
+@itemx --instance=@var{inst}
+Talk to @command{pies} instance @var{inst}.
+
+@item -u @var{url}
+@itemx --url=@var{url}
+Specifies the URL of the communication socket.  @xref{piesctl url},
+for a description of allowed URL forms.
+
+@item -v
+@itemx --verbose
+Enable verbose diagnostics.
+@end table
+
+Before parsing, configuration file is preprocessed using
+@command{m4}.  The following options control this feature:
+
+@table @option
+@item -E
+Show preprocessed configuration on stdout and exit.
+
+@item --define=@var{sym}[=@var{value}]
+@itemx -D @var{symbol}[=@var{value}]
+Define symbol @var{sym} as having @var{value}, or empty, if
+the @var{value} is not given.
+
+@item --include-directory=@var{dir}
+@itemx -I @var{dir}
+Add directory @var{dir} to the list of directories to be scanned for
+include files.  @xref{include search path}.
+
+@item --undefine=@var{sym}
+@itemx -U @var{sym}
+Undefine symbol @var{sym}.
+@end table
+
+Finally, the following options can be used to obtain on-line assistance:
+
+@table @option
+@item --config-help
+Show a terse reference to configuration file syntax and exit.
+
+@item -h
+@itemx --help
+Display command line help summary.
+
+@item --usage
+Give a short usage message
+
+@item -V
+@itemx --version
+Show program version.
+@end table
+
+@node piesctl.conf
+@section Configuration for @command{piesctl} 
+
+  The configuration file @file{/etc/piesctl.conf} helps the
+@command{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 @file{/etc/pies.conf}.  The
+following statements are defined:
+
+@deffn {piesctl.conf} socket @var{url}
+Sets the default socket URL.
+@end deffn
+
+@deffn {piesctl.conf} source @var{ip}
+Sets the default source IP address.  This is used if the control
+socket is of @samp{inet} type.
+@end deffn
+
+@deffn {piesctl.conf} instance @var{name}
+Configures socket URL and (optionally) source address to use when
+communicating with the @command{pies} instance @var{name} (i.e., when
+invoked as @command{piesctl -i @var{name}}:
+
+@example
+instance @var{name} @{
+    # @r{Socket URL for that instance.}
+    socket @var{url};
+    # Source IP address.
+    source @var{ip};
+@}
+@end example
+@end deffn
+
+@anchor{piesctl url}
+Valid values for @var{url} in the above statements are:
+
+@table @asis
+@item inet://@var{ip}:@var{port}
+Use the IPv4 address @var{ip} (may be given as a symbolic host name),
+on port @var{port}.
+
+@item local://@var{file}
+@itemx file://@var{file}
+@itemx unix://@var{file}
+Use the @acronym{UNIX} socket file @var{file}.
+@end table
+
+The following algorithm is used to determine the name of the
+communication socket:
+
+@enumerate 1
+@item
+If the @option{--url} (@option{-u}) option is given, use its argument.
+@item
+Determine the instance name (@var{inst}).  If the @option{--instance}
+(@option{-i}) is given, @var{inst} is its argument.  Otherwise, assume
+@var{inst}=@samp{pies}.
+@item
+If configuration file @file{/etc/piesctl.conf} exists, read it.  On 
+success:
+@enumerate a
+@item
+See if the @code{instance @var{inst}} statement is present
+and has @code{socket} substatement.  If so, the argument to
+@code{socket} gives the socket URL.
+@item
+Otherwise, if global @code{socket} statement is present, its argument
+gives the URL.
+@end enumerate
+@item
+Otherwise, suppose that @command{piesctl} is run on the same box where
+the target instance of @command{pies} is running, and see if the file
+@file{/etc/@var{inst}.conf} exists.   If so, parse it as
+@command{pies} configuration file and look for @command{control} block
+statement.  If it has @code{socket} statement, take its argument as
+the URL.  @xref{control}.
+@item
+If socket URL is not determined by these steps, assume
+@file{/tmp/@var{inst}.ctl}.
+@end enumerate
 
 @node Init Process
 @chapter Init -- parent of all processes
 @cindex init
   @command{Pies} can be executed directly by the kernel as a program
 responsible for starting all other processes (a process with PID 1).
@@ -2895,31 +3452,31 @@ Version of @command{pies}.
 Once the system is booted up, the environment can be controlled using
 the @command{piesctl telinit environ} (or @command{pies -T -e}) command.
 
 @node piesctl telinit
 @section piesctl telinit
 
-@deffn {Telnit Runlevel} piesctl telinit runlevel
+@deffn {piesctl} piesctl telinit runlevel
 Report the runlevel and state of the process 1.
 @end deffn
 
-@deffn {Telnit Runlevel} piesctl telinit runlevel @var{n}
+@deffn {piesctl} piesctl telinit runlevel @var{n}
 Switch to runlevel @var{n}.
 @end deffn
 
-@deffn {Telnit Env} piesctl telinit environ list [@var{NAME}]
+@deffn {piesctl} piesctl telinit environ list [@var{NAME}]
 List the environment.  If @var{NAME} is given, list only the value of
 that variable.
 @end deffn
 
-@deffn {Telinit Env} piesctl telinit environ set @var{NAME}=@var{VALUE}
+@deffn {piesctl} piesctl telinit environ set @var{NAME}=@var{VALUE}
 Set variable @var{NAME} to @var{VALUE}.  The environment is capable to
 hold at most 32 variables.
 @end deffn
 
-@deffn {Telinit Env} piesctl telinit environ unset @var{NAME}
+@deffn {piesctl} piesctl telinit environ unset @var{NAME}
 Unset variable @var{NAME}.
 @end deffn
 
 @node telinit command
 @section The Telinit Command
 
@@ -3141,13 +3698,13 @@ pies --instance=mta
   The first instance uses the default configuration and state files.
 The second one reads configuration from @file{/etc/inetd.conf}, and
 the third one reads it from @file{/etc/mta.conf}.
 
 @anchor{pies-status}
   After startup, you can verify the status of the running process
-using the @option{--status} command line option:
+using the @option{--status} option.
 
 @example
 @group
 $ pies --status
 smtps/stderr R  4697
 pmult/stderr R  4677
@@ -3161,60 +3718,13 @@ 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
 @end group
 @end example
 
-  Each output line contains at least two columns.  The first column
-lists the tag of the component.  The second one contains @dfn{flags},
-describing the type and status of the component.  The first flag
-describes the type:
-
-@multitable @columnfractions 0.2 0.7
-@headitem Flag @tab Meaning
-@item 3        @tab SysV init @samp{ctrlaltdel} component
-@item A        @tab Accept-style component
-@item B        @tab SysV init @samp{boot} component
-@item C        @tab Init-style component
-@item c        @tab SysV init @samp{once} component
-@item D        @tab SysV init @samp{ondemand} component
-@item E        @tab Command being executed
-@item F        @tab SysV init @samp{powerfail} component
-@item f        @tab SysV init @samp{powerwait} component
-@item I        @tab Inetd-style component
-@item i        @tab SysV init @samp{sysinit} component
-@item k        @tab SysV init @samp{kbrequest} component
-@item n        @tab SysV init @samp{powerfailnow} component
-@item o        @tab SysV init @samp{powerokwait} component
-@item P        @tab Pass-style component
-@item R        @tab Output redirector
-@item W        @tab SysV init @samp{wait} component
-@item w        @tab SysV init @samp{bootwait} component
-@end multitable
-
-  The second flag is meaningful only for components.  Its values are:
-
-@multitable @columnfractions 0.2 0.7
-@headitem Flag @tab Meaning
-@item -        @tab Disabled component
-@item f        @tab A finished @samp{once} component 
-@item L        @tab Inetd listener
-@item R        @tab Running component
-@item S        @tab Component is stopping
-@item s        @tab Component is sleeping
-@item T        @tab Component is stopped
-@end multitable
-
-  The next column lists the PID (for running components) or socket address
-(for Internet listeners), or the string @samp{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.
-
-  The rest of line contains the component command line.
+@xref{piesctl list}, for a description of the output format.
 
 @anchor{pies-restart}
 @xopindex{restart-component, described}
   You can restart any component by using the
 @option{--restart-component} (@option{-R}) option, e.g.:
 
@@ -3227,12 +3737,21 @@ $ pies -R pmult smtps
 @option{--stop} (@option{-S}) command line option:
 
 @example
 $ pies --stop
 @end example
 
+If you modified the configuration file, you can instruct
+@command{pies} to read it again using the @option{--reload}
+(@option{-r}) command line option.  
+
+The @option{--status}, @option{--restart-component},
+@option{--stop}, and @option{--reload} options actually run the
+@command{piesctl} command, which provides a powerful tool for managing
+@command{pies}.  @xref{piesctl}, for a detailed description.
+
 @cindex dependencies
 @anchor{dump-depmap}
 @xopindex{dump-depmap option, introduced}
   Two options are provided for verifying inter-component
 dependencies.  The @option{--dump-depmap} option prints on the
 standard output the @dfn{dependency map}.  This map is a square matrix
@@ -3322,17 +3841,17 @@ This section summarizes @command{pies} command line options.
 @opsummary{config-file}
 @item --config-file=@var{file}
 @item -c @var{file}
 Read configuration from @var{file}, instead of the default
 @file{/etc/pies.conf}.
 
-@xref{Pies Configuration File}.
+@xref{Configuration}.
 
 @opsummary{config-help}
 @item --config-help
-Show configuration file summary.  @xref{Pies Configuration File}.
+Show configuration file summary.  @xref{Configuration}.
 
 @opsummary{define}
 @item --define=@var{sym}[=@var{value}]
 @itemx -D @var{symbol}[=@var{value}]
 Define symbol @var{sym} as having @var{value}, or empty, if
 the @var{value} is not given.  @xref{Preprocessor}.
@@ -3403,32 +3922,34 @@ Define the name of the @command{pies} instance.  @xref{instances}.
 @item --source-info
 Show source info with debugging messages.  @xref{source-info}.
 
 @opsummary{status}
 @item --status
 @itemx -s
-Display info about the running instance.  @xref{pies-status}.
+Start @command{piesctl list} to obtain information about the running
+processes.  @xref{piesctl list}.
 
 @opsummary{stderr}
 @item --stderr
 Log to standard error.
 
 @opsummary{stop}
 @item --stop
 @itemx -S
-Stop the running instance.  
+Stop the running instance.  This is equivalent to running
+@command{piesctl shutdown}. 
 
 @opsummary{syntax}
 @item --syntax=@var{type}
 Define the syntax for parsing the configuration files specified by any
 @option{--config-file} options that follow this one.  Possible values
 for @var{type} are:
 
 @table @asis
 @item pies
-Native @command{pies} configuration.  @xref{Pies Configuration File}.
+Native @command{pies} configuration.  @xref{Configuration}.
 
 @item inetd
 @samp{Inetd}-style configuration files.  @xref{inetd.conf}.
 
 @item meta1
 @samp{meta1}-style configuration files.  @xref{include-meta1}.
@@ -3450,13 +3971,14 @@ components.  @xref{max-rate,, inetd component rate}.
 
 @opsummary{reload}
 @opsummary{hup}
 @item -r
 @itemx --reload
 @itemx --hup
-Reload the running instance of pies.
+Reread the configuration files.  This is equivalent to running
+@command{piesctl config reload} (@pxref{config reload}).
 
 @opsummary{restart-component}
 @item -R
 @itemx --restart-component
 Restart components named in the command line.  @xref{pies-restart}.