aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2016-03-07 16:55:20 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2016-03-07 16:55:20 +0200
commitaecf895a2fc514a0e652cf225de5bc3b85b03d10 (patch)
treeff4e8d25cc12a50c27ac83e1819e1612778a7714 /doc
parenta8b7efe8b9433416be7513170d768bc4d9b6e58d (diff)
downloadpies-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.texi666
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
128Inetd-Style Components 133Inetd-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
140Communicating 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
149Init -- 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
135Configuration Examples 158Configuration Examples
136 159
137* Simple Pies:: 160* Simple Pies::
@@ -233,7 +256,7 @@ dependencies, restarts the component, and then starts its
233dependencies again, in the order of their appearance in the 256dependencies again, in the order of their appearance in the
234configuration file. 257configuration 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}
1054component terminates is to restart it. Unless the component 1078component terminates is to restart it. Unless the component
1055terminates with 0 exit code, a corresponding error message is issued 1079terminates with 0 exit code, a corresponding error message is issued
1056to the log file. This behavior can be modified using 1080to 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.
1553The only difference from @samp{init-style} components is that the 1577The 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
1555start an @samp{inet-style} component without a communication socket. 1579start 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{} @}
1606This list controls who can get listing of this component 1630This list controls who can get listing of this component
1607(@FIXME-pxref{component listing}). 1631(@pxref{piesctl list}).
1608 1632
1609In the first form, @var{name} refers to the name of an already defined 1633In the first form, @var{name} refers to the name of an already defined
1610global ACL (@pxref{defacl}). 1634global 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{} @}
1618This list controls who can stop, restart or otherwise modify this 1642This list controls who can stop, restart or otherwise modify this
1619component (@FIXME-pxref{component management}). 1643component (@pxref{components}).
1620 1644
1621As above, two forms are available: the first one for using an already 1645As above, two forms are available: the first one for using an already
1622defined named ACL, and the second one, for defining a new ACL in place. 1646defined 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
2223control interface can be distributed among several users. For
2224example, it is possible to grant some users the rights to only view
2225the component listing, or even to further limit their rights to only
2226see the components they are authorized to know about. Another user
2227may be able to stop or restart components and so on. This privilege
2228separation requires @command{pies} to have a notion of user and be
2229able to authenticate it.
2230
2231 @dfn{Identity provider} is an abstract mechanism that @command{pies}
2232uses to obtain information about the user trying to authenticate
2233himself for accessing a particular control function. As of version
2234@value{VERSION}, this mechanism is considered experimental. That
2235means, that although being fully functional, it can change
2236considerably in future releases.
2237
2238 Identity provider supports two operations: authenticating a user,
2239and checking if he is a member of particular @dfn{group}. It is
2240defined in the configuration file using the @code{identity provider}
2241statement.
2242
2243@deffn {Config} identity-provider @var{name}
2244Defines an identity provider. It is a block statement:
2245
2246@example
2247identity-provider @var{name} @{
2248 type @var{type};
2249 @dots{}
2250@}
2251
2252The provider @var{name} is used in diagnostic messages.
2253@end example
2254
2255The only required substatement is @code{type}, which defines the type
2256of the provider. Rest of statements (represented by @dots{} above)
2257depends on the type.
2258@end deffn
2259
2260Pies version @value{VERSION} supports identity providers of two types:
2261@samp{system} and @samp{pam}.
2262
2263The @samp{system} identity provider uses system user database for
2264authentication and system group database for checking group membership.
2265It is declared using the following statement:
2266
2267@example
2268@group
2269identity-provider @var{name} @{
2270 type system;
2271@}
2272@end group
2273@end example
2274
2275Obviously, to use the system identity provider for authentication,
2276@command{pies} must be run as root.
2277
2278The @samp{pam} identity provider uses the Pluggable Authentication
2279Modules (@acronym{PAM}) for authentication, and system group database
2280for checking group membership.
2281
2282@example
2283@group
2284identity-provider @var{name} @{
2285 type pam;
2286 service @var{srv};
2287@}
2288@end group
2289@end example
2290
2291The @samp{service} statement defines the name of PAM service to use
2292for authentication. If absent, the name @samp{pies} is used.
2293
2294Any number of different identity providers can be declared in the
2295configuration file. When authenticating the user, they will be tried