diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2016-03-07 16:55:20 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2016-03-07 16:55:20 +0200 |
commit | aecf895a2fc514a0e652cf225de5bc3b85b03d10 (patch) | |
tree | ff4e8d25cc12a50c27ac83e1819e1612778a7714 /doc | |
parent | a8b7efe8b9433416be7513170d768bc4d9b6e58d (diff) | |
download | pies-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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/pies.texi | 666 |
1 files changed, 594 insertions, 72 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 @@ | |||
32 | @direntry | 32 | @direntry |
33 | * GNU Pies: (pies). Program Invocation and Execution Supervisor. | 33 | * GNU Pies: (pies). Program Invocation and Execution Supervisor. |
34 | * pies: (pies) Invocation. GNU Pies Command Line Options. | 34 | * pies: (pies) Invocation. GNU Pies Command Line Options. |
35 | * pies.conf: (pies) Configuration. GNU Pies Configuration File. | ||
36 | * piesctl: (pies) piesctl. GNU Pies Control Tool. | ||
37 | * piesctl.conf: (pies) piesctl.conf. Configuration File for the @command{piesctl} tool. | ||
35 | @end direntry | 38 | @end direntry |
36 | @end ifinfo | 39 | @end ifinfo |
37 | 40 | ||
@@ -76,10 +79,10 @@ documents @command{pies} Version @value{VERSION}. | |||
76 | @menu | 79 | @menu |
77 | * Intro:: Introduction to Process Management with @command{Pies}. | 80 | * Intro:: Introduction to Process Management with @command{Pies}. |
78 | * Dependencies:: Inter-process dependencies. | 81 | * Dependencies:: Inter-process dependencies. |
79 | * Pies Configuration File:: Configuration Files of Various Syntaxes. | 82 | * Configuration:: Configuration Files of Various Syntaxes. |
80 | * Pies Debugging:: Debugging @command{Pies}. | 83 | * Pies Debugging:: Debugging @command{Pies}. |
81 | * piesctl:: Communication with Running @command{pies} Instances. | 84 | * piesctl:: Communication with Running @command{pies} Instances. |
82 | * Init Process:: @command{Pies} as Parent of All Processes. | 85 | * Init Process:: Using @command{Pies} as Parent of All Processes. |
83 | * Configuration Examples:: Examples of Configuration Files. | 86 | * Configuration Examples:: Examples of Configuration Files. |
84 | * Command Line Usage:: | 87 | * Command Line Usage:: |
85 | * Invocation:: | 88 | * Invocation:: |
@@ -99,10 +102,11 @@ Pies Configuration File | |||
99 | 102 | ||
100 | * Syntax:: Configuration File Syntax | 103 | * Syntax:: Configuration File Syntax |
101 | * Component Statement:: | 104 | * Component Statement:: |
102 | * Notification:: Mail Notification | 105 | * Notification:: Mail Notification. |
103 | * ACL:: Access Control Lists | 106 | * ACL:: Access Control Lists. |
104 | * inetd:: Using @command{inetd} Configuration Files | 107 | * control:: The @samp{control} statement. |
105 | * include-meta1:: Using @command{meta1} Configuration Files | 108 | * inetd:: Using @command{inetd} Configuration Files. |
109 | * include-meta1:: Using @command{meta1} Configuration Files. | ||
106 | * Global Configuration:: | 110 | * Global Configuration:: |
107 | * Pies Privileges:: | 111 | * Pies Privileges:: |
108 | * State Files:: | 112 | * State Files:: |
@@ -123,6 +127,7 @@ Component Statement | |||
123 | * Output Redirectors:: | 127 | * Output Redirectors:: |
124 | * Inetd-Style Components:: | 128 | * Inetd-Style Components:: |
125 | * Meta1-Style Components:: | 129 | * Meta1-Style Components:: |
130 | * Visibility:: | ||
126 | * Component Syntax Summary:: | 131 | * Component Syntax Summary:: |
127 | 132 | ||
128 | Inetd-Style Components | 133 | Inetd-Style Components |
@@ -132,6 +137,24 @@ Inetd-Style Components | |||
132 | * sockenv:: Socket Environment Variables | 137 | * sockenv:: Socket Environment Variables |
133 | * inetd exit:: Exit Actions in Inetd Components | 138 | * inetd exit:: Exit Actions in Inetd Components |
134 | 139 | ||
140 | Communicating with Running @command{pies} Instances | ||
141 | |||
142 | * id:: Get Info About the Running Instance. | ||
143 | * stop and reboot:: Instance Management. | ||
144 | * config:: Configuration Management. | ||
145 | * components:: Component Management. | ||
146 | @c * telinit:: | ||
147 | * piesctl.conf:: Configuration file for @command{piesctl}. | ||
148 | |||
149 | Init -- parent of all processes | ||
150 | |||
151 | * Runlevels:: | ||
152 | * Init Process Configuration:: | ||
153 | * Init Command Line:: | ||
154 | * Init Environment:: | ||
155 | * piesctl telinit:: | ||
156 | * telinit command:: | ||
157 | |||
135 | Configuration Examples | 158 | Configuration Examples |
136 | 159 | ||
137 | * Simple Pies:: | 160 | * Simple Pies:: |
@@ -233,7 +256,7 @@ dependencies, restarts the component, and then starts its | |||
233 | dependencies again, in the order of their appearance in the | 256 | dependencies again, in the order of their appearance in the |
234 | configuration file. | 257 | configuration file. |
235 | 258 | ||
236 | @node Pies Configuration File | 259 | @node Configuration |
237 | @chapter Pies Configuration File | 260 | @chapter Pies Configuration File |
238 | @cindex configuration file | 261 | @cindex configuration file |
239 | @flindex pies.conf | 262 | @flindex pies.conf |
@@ -323,6 +346,7 @@ line option. | |||
323 | * Notification:: Mail Notification. | 346 | * Notification:: Mail Notification. |
324 | * ACL:: Access Control Lists. | 347 | * ACL:: Access Control Lists. |
325 | * control:: The @samp{control} statement. | 348 | * control:: The @samp{control} statement. |
349 | * Identities:: User Identities for Accessing Control Interface. | ||
326 | * inetd:: Using @command{inetd} Configuration Files. | 350 | * inetd:: Using @command{inetd} Configuration Files. |
327 | * include-meta1:: Using @command{meta1} Configuration Files. | 351 | * include-meta1:: Using @command{meta1} Configuration Files. |
328 | * Global Configuration:: | 352 | * Global Configuration:: |
@@ -1050,7 +1074,7 @@ to become available (@pxref{Meta1-Style Components}). Default is | |||
1050 | @node Exit Actions | 1074 | @node Exit Actions |
1051 | @subsection Exit Actions | 1075 | @subsection Exit Actions |
1052 | @kwindex return-code | 1076 | @kwindex return-code |
1053 | The default behavior of @command{pies} when an @samp{init-style} | 1077 | The default behavior of @command{pies} when a @samp{respawn} |
1054 | component terminates is to restart it. Unless the component | 1078 | component terminates is to restart it. Unless the component |
1055 | terminates with 0 exit code, a corresponding error message is issued | 1079 | terminates with 0 exit code, a corresponding error message is issued |
1056 | to the log file. This behavior can be modified using | 1080 | to the log file. This behavior can be modified using |
@@ -1550,7 +1574,7 @@ for @acronym{TCP} connections. | |||
1550 | @subsubsection Exit Actions in Inetd Components | 1574 | @subsubsection Exit Actions in Inetd Components |
1551 | 1575 | ||
1552 | Exit actions (@pxref{Exit Actions}) work for @samp{inet-style} components. | 1576 | Exit actions (@pxref{Exit Actions}) work for @samp{inet-style} components. |
1553 | The only difference from @samp{init-style} components is that the | 1577 | The only difference from @samp{respawn} components is that the |
1554 | @samp{restart} action is essentially ignored, as it makes no sense to | 1578 | @samp{restart} action is essentially ignored, as it makes no sense to |
1555 | start an @samp{inet-style} component without a communication socket. | 1579 | start an @samp{inet-style} component without a communication socket. |
1556 | 1580 | ||
@@ -1604,7 +1628,7 @@ lists define who can list and modify the particular component. | |||
1604 | @deffn {Config: component} list-acl @var{name} | 1628 | @deffn {Config: component} list-acl @var{name} |
1605 | @deffnx {Config: component} list-acl @{ @dots{} @} | 1629 | @deffnx {Config: component} list-acl @{ @dots{} @} |
1606 | This list controls who can get listing of this component | 1630 | This list controls who can get listing of this component |
1607 | (@FIXME-pxref{component listing}). | 1631 | (@pxref{piesctl list}). |
1608 | 1632 | ||
1609 | In the first form, @var{name} refers to the name of an already defined | 1633 | In the first form, @var{name} refers to the name of an already defined |
1610 | global ACL (@pxref{defacl}). | 1634 | global ACL (@pxref{defacl}). |
@@ -1616,7 +1640,7 @@ detail in @ref{ACL}. | |||
1616 | @deffn {Config: component} admin-acl @var{name} | 1640 | @deffn {Config: component} admin-acl @var{name} |
1617 | @deffnx {Config: component} admin-acl @{ @dots{} @} | 1641 | @deffnx {Config: component} admin-acl @{ @dots{} @} |
1618 | This list controls who can stop, restart or otherwise modify this | 1642 | This list controls who can stop, restart or otherwise modify this |
1619 | component (@FIXME-pxref{component management}). | 1643 | component (@pxref{components}). |
1620 | 1644 | ||
1621 | As above, two forms are available: the first one for using an already | 1645 | As above, two forms are available: the first one for using an already |
1622 | defined named ACL, and the second one, for defining a new ACL in place. | 1646 | 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. | |||
2192 | Defines the realm for basic authentication. Default value is @samp{pies}. | 2216 | Defines the realm for basic authentication. Default value is @samp{pies}. |
2193 | @end deffn | 2217 | @end deffn |
2194 | 2218 | ||
2219 | @node Identities | ||
2220 | @section User Identities for Accessing Control Interface | ||
2221 | |||
2222 | Privileges for using and performing various commands over the | ||
2223 | control interface can be distributed among several users. For | ||
2224 | example, it is possible to grant some users the rights to only view | ||
2225 | the component listing, or even to further limit their rights to only | ||
2226 | see the components they are authorized to know about. Another user | ||
2227 | may be able to stop or restart components and so on. This privilege | ||
2228 | separation requires @command{pies} to have a notion of user and be | ||
2229 | able to authenticate it. | ||
2230 | |||
2231 | @dfn{Identity provider} is an abstract mechanism that @command{pies} | ||
2232 | uses to obtain information about the user trying to authenticate | ||
2233 | himself for accessing a particular control function. As of version | ||
2234 | @value{VERSION}, this mechanism is considered experimental. That | ||
2235 | means, that although being fully functional, it can change | ||
2236 | considerably in future releases. | ||
2237 | |||
2238 | Identity provider supports two operations: authenticating a user, | ||
2239 | and checking if he is a member of particular @dfn{group}. It is | ||
2240 | defined in the configuration file using the @code{identity provider} | ||
2241 | statement. | ||
2242 | |||
2243 | @deffn {Config} identity-provider @var{name} | ||
2244 | Defines an identity provider. It is a block statement: | ||
2245 | |||
2246 | @example | ||
2247 | identity-provider @var{name} @{ | ||
2248 | type @var{type}; | ||
2249 | @dots{} | ||
2250 | @} | ||
2251 | |||
2252 | The provider @var{name} is used in diagnostic messages. | ||
2253 | @end example | ||
2254 | |||
2255 | The only required substatement is @code{type}, which defines the type | ||
2256 | of the provider. Rest of statements (represented by @dots{} above) | ||
2257 | depends on the type. | ||
2258 | @end deffn | ||
2259 | |||
2260 | Pies version @value{VERSION} supports identity providers of two types: | ||
2261 | @samp{system} and @samp{pam}. | ||
2262 | |||
2263 | The @samp{system} identity provider uses system user database for | ||
2264 | authentication and system group database for checking group membership. | ||
2265 | It is declared using the following statement: | ||
2266 | |||
2267 | @example | ||
2268 | @group | ||
2269 | identity-provider @var{name} @{ | ||
2270 | type system; | ||
2271 | @} | ||
2272 | @end group | ||
2273 | @end example | ||
2274 | |||
2275 | Obviously, to use the system identity provider for authentication, | ||
2276 | @command{pies} must be run as root. | ||
2277 | |||
2278 | The @samp{pam} identity provider uses the Pluggable Authentication | ||
2279 | Modules (@acronym{PAM}) for authentication, and system group database | ||
2280 | for checking group membership. | ||
2281 | |||
2282 | @example | ||
2283 | @group | ||
2284 | identity-provider @var{name} @{ | ||
2285 | type pam; | ||
2286 | service @var{srv}; | ||
2287 | @} | ||
2288 | @end group | ||
2289 | @end example | ||
2290 | |||
2291 | The @samp{service} statement defines the name of PAM service to use | ||
2292 | for authentication. If absent, the name @samp{pies} is used. | ||
2293 | |||
2294 | Any number of different identity providers can be declared in the | ||
2295 | configuration file. When authenticating the user, they will be tried | ||