diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2016-03-02 21:56:54 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2016-03-02 21:56:54 +0200 |
commit | 8ed75ebd5d697e981a0ad6a03482d48397ec2f8d (patch) | |
tree | 352b09ba7826482cc9596f033d4a890254ec067c /doc | |
parent | c767932556198cb064e7552bea14cc3563a114d0 (diff) | |
download | pies-8ed75ebd5d697e981a0ad6a03482d48397ec2f8d.tar.gz pies-8ed75ebd5d697e981a0ad6a03482d48397ec2f8d.tar.bz2 |
Improve docs
Diffstat (limited to 'doc')
-rw-r--r-- | doc/pies.texi | 127 |
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{} @} | ||
866 | ACL controlling read-only access to this component. | ||
867 | @FIXME-pxref{Access to Components}. | ||
868 | @end deffn | ||
869 | |||
870 | @deffn {Config: component} admin-acl @{ @dots{} @} | ||
871 | ACL controlling administrative (write) access to this component. | ||
872 | @FIXME-pxref{Access to Components}. | ||
873 | @end deffn | ||
874 | |||
865 | The following subsections describe the rest of @samp{component} | 875 | The following subsections describe the rest of @samp{component} |
866 | substatements. | 876 | substatements. |
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{} @} |
1317 | Set access control list for this component. @xref{ACL}, for a | 1322 | Set access control list for this component. This is valid only for |
1323 | @samp{inetd} and @samp{accept} components. @xref{ACL}, for a | ||
1318 | detailed description of access control lists. | 1324 | detailed 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 | ||
2054 | the running @command{pies} instance. It is used by the | ||
2055 | @command{piesctl} utility to query information about the instance and | ||
2056 | components it is currently running and to send it commands for | ||
2057 | controlling its operation (@pxref{piesctl}). By default the UNIX | ||
2058 | socket @file{/tmp/pies.ctl} is used for this purpose. If | ||
2059 | @command{pies} was started with the @option{--instance=@var{name}} | ||
2060 | option, the socket is named @file{/tmp/@var{name}.ctl}. Whatever its | ||
2061 | name, the socket will be owned by the user @command{pies} runs as | ||
2062 | (@pxref{Pies Privileges}) and will have access rights of 0500, | ||
2063 | allowing only that user to read and write to it. When @command{pies} | ||
2064 | is 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 | ||
2068 | limits access to it: | ||
2069 | |||
2070 | @example | ||
2071 | @group | ||
2072 | control @{ | ||
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} | ||
2084 | URL of the control socket. The @var{url} argument is a string of the | ||
2085 | following syntax: | ||
2086 | |||
2087 | @table @asis | ||
2088 | @item inet://@var{ip}:@var{port} | ||
2089 | Listen on IPv4 address @var{ip} (may be given as a symbolic host name), | ||
2090 | on 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}] | ||
2095 | Listen on the @acronym{UNIX} socket file @var{file}, which is either | ||
2096 | an absolute or relative file name. Optional arguments @var{args} | ||
2097 | control ownership and file mode of @var{file}. They are a | ||
2098 | semicolon-separated list of assignments to the following variables: | ||
2099 | |||
2100 | @table @asis | ||
2101 | @item user | ||
2102 | User name of the socket owner. | ||
2103 | |||
2104 | @item group | ||
2105 | Owner group of the socket, if it differs from the @code{user} group. | ||
2106 | |||
2107 | @item mode | ||
2108 | Socket file mode (octal number between @samp{0} and @samp{777}). | ||
2109 | |||
2110 | @item umask | ||
2111 | Umask to use when creating the socket (octal number between @samp{0} | ||
2112 | and @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} | ||
2119 | seconds. 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} | ||
2133 | operations (such as stopping or restarting components). | ||
2134 | |||
2135 | The @code{user-acl} controls read access to components that don't | ||
2136 | have 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} | ||
2141 | instance itself and to the components for which no specific | ||
2142 | @code{admin-acl} statements are supplied (@FIXME-pxref{per-component | ||
2143 | admin-acl}). | ||
2144 | |||
2145 | In particular, whoever passes @code{admin-acl} can issue commands | ||
2146 | for 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; | |||
2366 | This feature is designed for @command{pies} developers. | 2471 | This 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 | ||