aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2016-03-02 21:56:54 +0200
committerSergey Poznyakoff <gray@gnu.org>2016-03-02 21:56:54 +0200
commit8ed75ebd5d697e981a0ad6a03482d48397ec2f8d (patch)
tree352b09ba7826482cc9596f033d4a890254ec067c /doc
parentc767932556198cb064e7552bea14cc3563a114d0 (diff)
downloadpies-8ed75ebd5d697e981a0ad6a03482d48397ec2f8d.tar.gz
pies-8ed75ebd5d697e981a0ad6a03482d48397ec2f8d.tar.bz2
Improve docs
Diffstat (limited to 'doc')
-rw-r--r--doc/pies.texi127
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}.
78* Dependencies:: Inter-process dependencies. 78* Dependencies:: Inter-process dependencies.
79* Pies Configuration File:: Configuration Files of Various Syntaxes. 79* Pies Configuration File:: Configuration Files of Various Syntaxes.
80* Pies Debugging:: Debugging @command{Pies}. 80* Pies Debugging:: Debugging @command{Pies}.
81* Piesctl:: Communication with Running @command{pies} Instances. 81* piesctl:: Communication with Running @command{pies} Instances.
82* Init Process:: @command{Pies} as Parent of All Processes. 82* Init Process:: @command{Pies} as Parent of All Processes.
83* Configuration Examples:: Examples of Configuration Files. 83* Configuration Examples:: Examples of Configuration Files.
84* Command Line Usage:: 84* Command Line Usage::
@@ -862,11 +862,20 @@ process instead.
862@end table 862@end table
863@end deffn 863@end deffn
864 864
865@deffn {Config: component} user-acl @{ @dots{} @}
866ACL controlling read-only access to this component.
867@FIXME-pxref{Access to Components}.
868@end deffn
869
870@deffn {Config: component} admin-acl @{ @dots{} @}
871ACL controlling administrative (write) access to this component.
872@FIXME-pxref{Access to Components}.
873@end deffn
874
865The following subsections describe the rest of @samp{component} 875The following subsections describe the rest of @samp{component}
866substatements. 876substatements.
867 877
868@menu 878@menu
869* Access Control::
870* Prerequisites:: 879* Prerequisites::
871* Component Privileges:: 880* Component Privileges::
872* Resources:: 881* Resources::
@@ -878,10 +887,6 @@ substatements.
878* Component Syntax Summary:: 887* Component Syntax Summary::
879@end menu 888@end menu
880 889
881@node Access Control
882@subsection Access Control
883@WRITEME
884
885@node Prerequisites 890@node Prerequisites
886@subsection Component Prerequisites 891@subsection Component Prerequisites
887@cindex declaring prerequisites 892@cindex declaring prerequisites
@@ -1314,7 +1319,8 @@ address that has already reached @code{max-ip-connections} limit.
1314@end deffn 1319@end deffn
1315 1320
1316@deffn {Config: component} acl @{ @dots{} @} 1321@deffn {Config: component} acl @{ @dots{} @}
1317Set access control list for this component. @xref{ACL}, for a 1322Set access control list for this component. This is valid only for
1323@samp{inetd} and @samp{accept} components. @xref{ACL}, for a
1318detailed description of access control lists. 1324detailed description of access control lists.
1319@end deffn 1325@end deffn
1320 1326
@@ -1680,11 +1686,11 @@ component @var{tag} @{
1680 access-denied-message @var{text}; 1686 access-denied-message @var{text};
1681 1687
1682 # @r{ACL for administrative access to this component.} 1688 # @r{ACL for administrative access to this component.}
1683 # @xref{Access Control}. 1689 # @FIXME-xref{Access to Components}.
1684 admin-acl @{ @dots{} @} 1690 admin-acl @{ @dots{} @}
1685 1691
1686 # @r{ACL for read-only access to this component.} 1692 # @r{ACL for read-only access to this component.}
1687 # @xref{Access Control}. 1693 # @FIXME-xref{Access to Components}.
1688 list-acl @{ @dots{} @} 1694 list-acl @{ @dots{} @}
1689 1695
1690 # @r{ACL for this component.} 1696 # @r{ACL for this component.}
@@ -2043,7 +2049,106 @@ acl @{
2043 2049
2044@node control 2050@node control
2045@section The Control Statement 2051@section The Control Statement
2046@WRITEME 2052
2053 The @dfn{control interface} provides a method for communication with
2054the running @command{pies} instance. It is used by the
2055@command{piesctl} utility to query information about the instance and
2056components it is currently running and to send it commands for
2057controlling its operation (@pxref{piesctl}). By default the UNIX
2058socket @file{/tmp/pies.ctl} is used for this purpose. If
2059@command{pies} was started with the @option{--instance=@var{name}}
2060option, the socket is named @file{/tmp/@var{name}.ctl}. Whatever its
2061name, the socket will be owned by the user @command{pies} runs as
2062(@pxref{Pies Privileges}) and will have access rights of 0500,
2063allowing only that user to read and write to it. When @command{pies}
2064is used as init process, the default socket name is @file{/dev/init.ctl}.
2065
2066@deffn {Config} control
2067 The @samp{control} statement configures the control interface and
2068limits access to it:
2069
2070@example
2071@group
2072control @{
2073 socket @var{url};
2074 acl @{ @dots{} @}
2075 admin-acl @{ @dots{} @}
2076 user-acl @{ @dots{} @}
2077 realm @var{name};
2078@}
2079@end group
2080@end example
2081@end deffn
2082
2083@deffn {Config: control} socket @var{url}
2084URL of the control socket. The @var{url} argument is a string of the
2085following syntax:
2086
2087@table @asis
2088@item inet://@var{ip}:@var{port}
2089Listen on IPv4 address @var{ip} (may be given as a symbolic host name),
2090on port @var{port}.
2091
2092@item local://@var{file}[;@var{args}]
2093@itemx file://@var{file}[;@var{args}]
2094@itemx unix://@var{file}[;@var{args}]
2095Listen on the @acronym{UNIX} socket file @var{file}, which is either
2096an absolute or relative file name. Optional arguments @var{args}
2097control ownership and file mode of @var{file}. They are a
2098semicolon-separated list of assignments to the following variables:
2099
2100@table @asis
2101@item user
2102User name of the socket owner.
2103
2104@item group
2105Owner group of the socket, if it differs from the @code{user} group.
2106
2107@item mode
2108Socket file mode (octal number between @samp{0} and @samp{777}).
2109
2110@item umask
2111Umask to use when creating the socket (octal number between @samp{0}
2112and @samp{777}).
2113@end table
2114@end table
2115@end deffn
2116
2117@deffn {Config: control} idle-timeout @var{n}
2118 Disconnect any control session that remains inactive for @var{n}
2119seconds. This statement is reserved for use in the future. Currently
2120(as of version @value{VERSION}) it is a no-op.
2121@end deffn
2122
2123 The control interface is protected by three access control lists
2124(@xref{ACL}, for a discussion of their syntax).
2125
2126@deffn {Config: control} acl
2127 Controls who can connect to the control interface.
2128@end deffn
2129
2130@deffn {Config: control} user-acl
2131 Control interface provides two kinds of operations: @dfn{read-only}
2132(such as getting information about running components) and @dfn{write}
2133operations (such as stopping or restarting components).
2134
2135 The @code{user-acl} controls read access to components that don't
2136have per-component @code{user-acl} (@FIXME-pxref{per-component user-acl}).
2137@end deffn
2138
2139@deffn {Config: control} admin-acl
2140 Defines access control list for write access to the @command{pies}
2141instance itself and to the components for which no specific
2142@code{admin-acl} statements are supplied (@FIXME-pxref{per-component
2143admin-acl}).
2144
2145 In particular, whoever passes @code{admin-acl} can issue commands
2146for stopping the instance and reloading its configuration.
2147@end deffn
2148
2149@deffn {Config: control} realm @var{name}
2150 Defines the realm for basic authentication. Default value is @samp{pies}.
2151@end deffn
2047 2152
2048@node inetd 2153@node inetd
2049@section Using @command{inetd} Configuration Files 2154@section Using @command{inetd} Configuration Files
@@ -2366,7 +2471,7 @@ source-info yes;
2366This feature is designed for @command{pies} developers. 2471This feature is designed for @command{pies} developers.
2367@end deffn 2472@end deffn
2368 2473
2369@node Piesctl 2474@node piesctl
2370@chapter Communicating with Running @command{pies} Instances 2475@chapter Communicating with Running @command{pies} Instances
2371@WRITEME 2476@WRITEME
2372 2477

Return to:

Send suggestions and report system problems to the System administrator.