aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2016-03-07 16:55:20 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2016-03-07 16:55:20 +0200
commitaecf895a2fc514a0e652cf225de5bc3b85b03d10 (patch)
treeff4e8d25cc12a50c27ac83e1819e1612778a7714
parenta8b7efe8b9433416be7513170d768bc4d9b6e58d (diff)
downloadpies-aecf895a2fc514a0e652cf225de5bc3b85b03d10.tar.gz
pies-aecf895a2fc514a0e652cf225de5bc3b85b03d10.tar.bz2
Improve docs
* doc/pies.texi: Document piesctl and identity providers. * src/piesctl.c: Fix reference to the docs.
-rw-r--r--doc/pies.texi666
-rw-r--r--src/piesctl.c2
2 files changed, 595 insertions, 73 deletions
diff --git a/doc/pies.texi b/doc/pies.texi
index 1f162a2..c72ac3e 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -32,6 +32,9 @@
@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
@@ -76,10 +79,10 @@ documents @command{pies} Version @value{VERSION}.
@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::
@@ -99,10 +102,11 @@ 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::
@@ -123,6 +127,7 @@ Component Statement
* Output Redirectors::
* Inetd-Style Components::
* Meta1-Style Components::
+* Visibility::
* Component Syntax Summary::
Inetd-Style Components
@@ -132,6 +137,24 @@ Inetd-Style Components
* 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::
@@ -233,7 +256,7 @@ 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
@@ -323,6 +346,7 @@ line option.
* 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::
@@ -1050,7 +1074,7 @@ to become available (@pxref{Meta1-Style Components}). Default is
@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
@@ -1550,7 +1574,7 @@ for @acronym{TCP} connections.
@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.
@@ -1604,7 +1628,7 @@ 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}).
@@ -1616,7 +1640,7 @@ detail in @ref{ACL}.
@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.
@@ -2192,6 +2216,86 @@ If it allows access too, then the operation is permitted.
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
@@ -2524,7 +2628,460 @@ This feature is designed for @command{pies} developers.
@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
@@ -2898,25 +3455,25 @@ 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
@@ -3144,7 +3701,7 @@ 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
@@ -3164,54 +3721,7 @@ 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}
@@ -3230,6 +3740,15 @@ $ pies -R pmult smtps
$ 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}
@@ -3325,11 +3844,11 @@ This section summarizes @command{pies} command line options.
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}]
@@ -3406,7 +3925,8 @@ 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
@@ -3415,7 +3935,8 @@ 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}
@@ -3425,7 +3946,7 @@ 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}.
@@ -3453,7 +3974,8 @@ components. @xref{max-rate,, inetd component rate}.
@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
diff --git a/src/piesctl.c b/src/piesctl.c
index 43a6b49..d10bd0e 100644
--- a/src/piesctl.c
+++ b/src/piesctl.c
@@ -229,7 +229,7 @@ config_help (void)
/* TRANSLATORS: do not translate words in quotes */
static char docstring[] =
N_("Configuration file structure for piesctl.\n"
- "For more information, use command \"info piesctl configuration\".");
+ "For more information, use command \"info piesctl.conf\".");
grecs_print_docstring (docstring, 0, stdout);
grecs_print_statement_array (piesctl_keywords, 1, 0, stdout);
}

Return to:

Send suggestions and report system problems to the System administrator.