diff options
Diffstat (limited to 'doc/pies.texi')
-rw-r--r-- | doc/pies.texi | 193 |
1 files changed, 157 insertions, 36 deletions
diff --git a/doc/pies.texi b/doc/pies.texi index ae4a56a..1f162a2 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -1652,2 +1652,7 @@ component @var{tag} @{ flags (@var{flags}); + + # @r{For @i{init} components: runlevels in which to start this} + # @r{component.} + # @xref{Runlevels}. + runlevels @var{string}; @@ -1706,4 +1711,4 @@ component @var{tag} @{ - # @r{ACL for administrative access to this component.} - # @FIXME-xref{Access to Components}. + # @r{ACL for administrative (read-write) access to this component.} + # @xref{Visibility}. admin-acl @var{name}; @@ -1713,3 +1718,3 @@ component @var{tag} @{ # @r{ACL for read-only access to this component.} - # @FIXME-xref{Access to Components}. + # @xref{Visibility}. list-acl @var{name}; @@ -2151,7 +2156,12 @@ seconds. This statement is reserved for use in the future. Currently -@deffn {Config: control} acl - Controls who can connect to the control interface. +@deffn {Config: control} acl @var{name} +@deffnx {Config: control} acl @{ @dots{} @} + Controls who can connect to the interface. The first form refers to +a named ACL that must have been defined earlier by @code{defacl} +statement (@pxref{defacl}). Use the second form to define a new ACL +in place. @end deffn -@deffn {Config: control} user-acl +@deffn {Config: control} user-acl @var{name} +@deffnx {Config: control} user-acl @{ @dots{} @} Control interface provides two kinds of operations: @dfn{read-only} @@ -2160,11 +2170,12 @@ 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}). + The @code{user-acl} controls read access. Access to particular +components can also be controlled individually, using the +per-component @code{list-acl} statement (@pxref{Visibility, list-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 -admin-acl}). +@deffn {Config: control} admin-acl @var{name} +@deffnx {Config: control} admin-acl @{ @dots{} @} + Controls write access to the @command{pies} instance itself and to +the components for which no specific @code{admin-acl} statements are +supplied (@pxref{Visibility, admin-acl}). @@ -2174,2 +2185,7 @@ for stopping the instance and reloading its configuration. + When checking whether the user has a particular kind of access to a +component, first the corresponding ACL from the @code{control} section +is checked. If it allows access, then the per-component ACL is tried. +If it allows access too, then the operation is permitted. + @deffn {Config: control} realm @var{name} @@ -2456,2 +2472,11 @@ Sets the name of the @samp{quotation-of-the-day} file. +The following statements are retained for compatibility with earlier +@command{pies} versions. They are silently ignored: + +@deffn {Config} control-file @var{arg} +@end deffn + +@deffn {Config} stat-file @var{arg} +@end deffn + @node Pies Debugging @@ -2575,4 +2600,5 @@ UNIX socket for communication using @command{piesctl}. * Init Command Line:: -* piesctl telinit:: * Init Environment:: +* piesctl telinit:: +* telinit command:: @end menu @@ -2601,3 +2627,3 @@ Additionally, three special runlevels @samp{a}, @samp{b} and @samp{c} can be used to start @dfn{on-demand} components without actually -changing the runlevel. Once started, on-demain components persist +changing the runlevel. Once started, on-demain components persist through eventual runlevel changes. @@ -2758,5 +2784,14 @@ Both the traditional @file{/etc/inittab} and pies-native naturally, the latter is more flexible and gives much more -possibilities in defining the system behavior. The inittab entry -discussed above is equivalent to the following statement in -@file{pies.init} file: +possibilities in defining the system behavior. The declaration of a +component in @file{/etc/pies.init} can contain all the statements +discussed in @ref{Component Statement}. The only difference is that +runlevels to start the component is must be specified: + +@deffn {Config: component} runlevels @var{string} +Specifies the runlevel to start the component in. The @var{string} +argument is a string of runlevel characters. +@end deffn + +For example, the inittab entry discussed above is equivalent to the +following statement in @file{pies.init} file: @@ -2770,2 +2805,14 @@ component @var{id} @{ +The default runlevel is specified in @file{/etc/pies.init} using +the following construct: + +@deffn {Config} initdefault @var{rl} +Declare the default runlevel. The argument is the runlevel name. +E.g. + +@example +initdefault 3; +@end example +@end deffn + If both @file{/etc/inittab} and @file{/etc/pies.init} are present, the @@ -2824,2 +2871,28 @@ Run emergency shell @command{/sbin/sulogin}, prior to initialization. +@node Init Environment +@section Init Environment + +Programs run from @command{pies} init process inherit a basic +environment consisting of the following variables: + +@table @option +@item PREVLEVEL=@var{L} +Previous runlevel, or letter @samp{N} if the runlevel hasn't been +changed since startup. + +@item RUNLEVEL=@var{L} +Current runlevel. + +@item CONSOLE=@var{device} +Pathname of the console device file. + +@item INIT_VERSION="GNU Pies @value{VERSION}" +Version of @command{pies}. + +@item PATH=/bin:/usr/bin:/sbin:/usr/sbin +@end table + +Once the system is booted up, the environment can be controlled using +the @command{piesctl telinit environ} (or @command{pies -T -e}) command. + @node piesctl telinit @@ -2849,27 +2922,68 @@ Unset variable @var{NAME}. -@node Init Environment -@section Init Environment +@node telinit command +@section The Telinit Command -Programs run from @command{pies} init process inherit a basic -environment consisting of the following variables: +@xopindex{telinit option, introduced} + When given the @option{-T} (@option{--telinit}) option, +@command{pies} emulates the behavior of the traditional +@command{telinit} command. This is a legacy way of communicating with +the init process. The commands are sent via named pipe +@file{/dev/initctl}. When the @option{-T} option is given, the rest +of command line after it is handled as @command{telinit} options. The +following command: -@table @option -@item PREVLEVEL=@var{L} -Previous runlevel, or letter @samp{N} if the runlevel hasn't been -changed since startup. +@example +pies -T [-t @var{n}] @var{r} +@end example -@item RUNLEVEL=@var{L} -Current runlevel. +@noindent +tells init process to switch to runlevel @var{r}. Possible values for +@var{r} are: -@item CONSOLE=@var{device} -Pathname of the console device file. +@table @asis +@item 0 to 9 +Instructs init to switch to the specified runlevel. +@item S or s +Tells init to switch to the single user mode. +@item a, b, or c +Tells init to enable on-demand components with the specified +runlevel. The actual runlevel is not changed. +@item Q or q +Tells init to rescan configuration files. +@end table -@item INIT_VERSION="GNU Pies @value{VERSION}" -Version of @command{pies}. +The @option{-t} (@option{--timeout}) option sets the time to wait +for processes to terminate after sending them the SIGTERM signal. Any +processes that remain running after @var{n} seconds will be sent the +SIGKILL signal. The default value is 5 seconds. -@item PATH=/bin:/usr/bin:/sbin:/usr/sbin -@end table +This usage is equivalent to the @command{piesctl telinit runlevel} +command (@pxref{piesctl telinit}). -Once the system is booted up, the environment can be controlled using -the @command{piesctl telinit environ} command. +The @option{-e} (@option{--environment}) option modifies the init +process environment. Its argument is either a variable assignment +@samp{@var{name}=@var{value}} to set a variable, or the name of a +variable to unset it. Several @option{-e} options can be given to +process multiple variables in a single command. Note, however, that +given @var{n} @option{-e} options, the total length of their arguments +is limited to 367 - @var{n} bytes. + +This option provides a limited subset of the functionality offered by +the @command{piesctl telinit environ} command. + +The table below summarizes all options available in @option{telinit} +mode: + +@table @option +@item -t @var{n} +Wait @var{n} seconds for processes to terminate after sending them the +SIGTERM signal. Any processes that remain running after that time +will be sent the SIGKILL signal. The default value is 5 seconds. + +@item -e @var{var}=@var{value} +Define environment variable @var{var} as having value @var{value}. + +@item -e @var{var} +Unset environment variable @var{var}. +@end table @@ -3245,2 +3359,9 @@ arguments, prerequisites for each component are listed. @xref{trace-prereq}. +@opsummary{telinit} +@item --telinit +@item -T +Emulate the @command{telinit} legacy interface. The rest of command +line following this option is processed as @command{telinit} options. +@xref{telinit command}, for a detailed description of these. + @item -E |