path: root/doc
authorSergey Poznyakoff <>2016-03-02 19:56:54 (GMT)
committer Sergey Poznyakoff <>2016-03-02 19:56:54 (GMT)
commit8ed75ebd5d697e981a0ad6a03482d48397ec2f8d (patch) (side-by-side diff)
tree352b09ba7826482cc9596f033d4a890254ec067c /doc
parentc767932556198cb064e7552bea14cc3563a114d0 (diff)
Improve docs
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
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
@@ -78,7 +78,7 @@ documents @command{pies} Version @value{VERSION}.
* 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::
@@ -862,11 +862,20 @@ 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}
-* Access Control::
* Prerequisites::
* Component Privileges::
* Resources::
@@ -878,10 +887,6 @@ substatements.
* Component Syntax Summary::
@end menu
-@node Access Control
-@subsection Access Control
@node Prerequisites
@subsection Component Prerequisites
@cindex declaring prerequisites
@@ -1314,7 +1319,8 @@ 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
@@ -1680,11 +1686,11 @@ component @var{tag} @{
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.}
@@ -2043,7 +2049,106 @@ acl @{
@node control
@section The Control Statement
+ 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:
+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
+ 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
@@ -2366,7 +2471,7 @@ source-info yes;
This feature is designed for @command{pies} developers.
@end deffn
-@node Piesctl
+@node piesctl
@chapter Communicating with Running @command{pies} Instances

Return to:

Send suggestions and report system problems to the System administrator.