Improve docs

1 files changed, 116 insertions, 11 deletions

diff --git a/doc/pies.texi b/doc/pies.texi
index 13deec0..8e25e76 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -75,13 +75,13 @@ 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.
 * Pies Debugging::           Debugging @command{Pies}.
-* Piesctl::                  Communication with Running @command{pies} Instances.
+* piesctl::                  Communication with Running @command{pies} Instances.
 * Init Process::             @command{Pies} as Parent of All Processes.
 * Configuration Examples::   Examples of Configuration Files.
 * Command Line Usage::
 * Invocation::
 * Reporting Bugs::
 
@@ -859,32 +859,37 @@ process fails to terminate within a predefined timeout
 @samp{SIGKILL} signal to such a process.  If this flag is set,
 @command{pies} would send @samp{SIGKILL} to the process group of this
 process instead.
 @end table
 @end deffn
 
+@deffn {Config: component} user-acl @{ @dots{} @}
+ACL controlling read-only access to this component.
+@FIXME-pxref{Access to Components}.
+@end deffn
+
+@deffn {Config: component} admin-acl @{ @dots{} @}
+ACL controlling administrative (write) access to this component.
+@FIXME-pxref{Access to Components}.
+@end deffn
+
 The following subsections describe the rest of @samp{component}
 substatements.
 
 @menu
-* Access Control::
 * Prerequisites::
 * Component Privileges::
 * Resources::
 * Actions Before Startup::
 * Exit Actions::
 * Output Redirectors::
 * Inetd-Style Components::
 * Meta1-Style Components::
 * Component Syntax Summary::
 @end menu
 
-@node Access Control
-@subsection Access Control
-@WRITEME
-
 @node Prerequisites
 @subsection Component Prerequisites
 @cindex declaring prerequisites
 @cindex prerequisites, declaring
 Prerequisites (@pxref{component prerequisite}) for a component are
 declared using the following statement: 
@@ -1311,13 +1316,14 @@ single IP address.
 @deffn {Config: component} max-ip-connections-message @var{text}
 Textual message to send in reply to an incoming TCP connection from the IP
 address that has already reached @code{max-ip-connections} limit.
 @end deffn
 
 @deffn {Config: component} acl @{ @dots{} @}
-Set access control list for this component.  @xref{ACL}, for a
+Set access control list for this component.  This is valid only for
+@samp{inetd} and @samp{accept} components.  @xref{ACL}, for a
 detailed description of access control lists.
 @end deffn
 
 @deffn {Config: component} access-denied-message @var{text}
 Textual message to send in reply to an incoming TCP connection that
 has been denied by ACL settings.
@@ -1677,17 +1683,17 @@ component @var{tag} @{
   # @r{For @samp{inetd} components:}
   # @r{Text to send back if access is denied by ACL.}
   # @xref{Inetd-Style Components, access-denied-message}.
   access-denied-message @var{text};
 
   # @r{ACL for administrative access to this component.}
-  # @xref{Access Control}.
+  # @FIXME-xref{Access to Components}.
   admin-acl @{ @dots{} @}
 
   # @r{ACL for read-only access to this component.}
-  # @xref{Access Control}.
+  # @FIXME-xref{Access to Components}.
   list-acl @{ @dots{} @}
   
   # @r{ACL for this component.}
   # @xref{ACL}.
   acl @{ @dots{} @}
   
@@ -2040,13 +2046,112 @@ acl @{
 @}
 @end group
 @end example
 
 @node control
 @section The Control Statement
-@WRITEME
+
+  The @dfn{control interface} provides a method for communication with
+the running @command{pies} instance.  It is used by the
+@command{piesctl} utility to query information about the instance and
+components it is currently running and to send it commands for
+controlling its operation (@pxref{piesctl}).  By default the UNIX
+socket @file{/tmp/pies.ctl} is used for this purpose.  If
+@command{pies} was started with the @option{--instance=@var{name}}
+option, the socket is named @file{/tmp/@var{name}.ctl}.  Whatever its
+name, the socket will be owned by the user @command{pies} runs as
+(@pxref{Pies Privileges}) and will have access rights of 0500,
+allowing only that user to read and write to it.  When @command{pies}
+is used as init process, the default socket name is @file{/dev/init.ctl}.
+
+@deffn {Config} control
+  The @samp{control} statement configures the control interface and
+limits access to it:
+
+@example
+@group
+control @{
+    socket @var{url};
+    acl @{ @dots{} @}
+    admin-acl @{ @dots{} @}
+    user-acl @{ @dots{} @}
+    realm @var{name};
+@}
+@end group
+@end example
+@end deffn
+
+@deffn {Config: control} socket @var{url}
+URL of the control socket.  The @var{url} argument is a string of the
+following syntax:
+
+@table @asis
+@item inet://@var{ip}:@var{port}
+Listen on IPv4 address @var{ip} (may be given as a symbolic host name),
+on port @var{port}.
+
+@item local://@var{file}[;@var{args}]
+@itemx file://@var{file}[;@var{args}]
+@itemx unix://@var{file}[;@var{args}]
+Listen on the @acronym{UNIX} socket file @var{file}, which is either
+an absolute or relative file name.  Optional arguments @var{args}
+control ownership and file mode of @var{file}.  They are a
+semicolon-separated list of assignments to the following variables:
+
+@table @asis
+@item user
+User name of the socket owner.
+
+@item group
+Owner group of the socket, if it differs from the @code{user} group.
+
+@item mode
+Socket file mode (octal number between @samp{0} and @samp{777}).
+
+@item umask
+Umask to use when creating the socket (octal number between @samp{0}
+and @samp{777}). 
+@end table
+@end table
+@end deffn
+
+@deffn {Config: control} idle-timeout @var{n}
+  Disconnect any control session that remains inactive for @var{n}
+seconds.  This statement is reserved for use in the future.  Currently
+(as of version @value{VERSION}) it is a no-op.
+@end deffn
+
+  The control interface is protected by three access control lists
+(@xref{ACL}, for a discussion of their syntax).
+
+@deffn {Config: control} acl
+  Controls who can connect to the control interface.
+@end deffn
+
+@deffn {Config: control} user-acl
+  Control interface provides two kinds of operations: @dfn{read-only}
+(such as getting information about running components) and @dfn{write}
+operations (such as stopping or restarting components).
+
+  The @code{user-acl} controls read access to components that don't
+have per-component @code{user-acl} (@FIXME-pxref{per-component user-acl}).
+@end deffn
+
+@deffn {Config: control} admin-acl
+  Defines access control list for write access to the @command{pies}
+instance itself and to the components for which no specific
+@code{admin-acl} statements are supplied (@FIXME-pxref{per-component
+admin-acl}).
+
+  In particular, whoever passes @code{admin-acl} can issue commands
+for stopping the instance and reloading its configuration.
+@end deffn
+
+@deffn {Config: control} realm @var{name}
+  Defines the realm for basic authentication.  Default value is @samp{pies}.
+@end deffn
 
 @node inetd
 @section Using @command{inetd} Configuration Files
 @cindex inetd.conf
 @flindex /etc/inetd.conf
   In addition to its native configuration file format, GNU
@@ -2363,13 +2468,13 @@ source information.  To enable source information, use:
 source-info yes;
 @end example
 
 This feature is designed for @command{pies} developers.
 @end deffn
 
-@node Piesctl
+@node piesctl
 @chapter Communicating with Running @command{pies} Instances
 @WRITEME
 
 @node Init Process
 @chapter Init -- parent of all processes
 @cindex init