aboutsummaryrefslogtreecommitdiff
path: root/doc/pies.texi
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2016-03-06 15:25:06 +0200
committerSergey Poznyakoff <gray@gnu.org>2016-03-06 15:27:39 +0200
commit1a37a444eea3d238e45d01d47ac157b470f536ac (patch)
tree5a992298b9cdc93c31ffce6a7db302670e8eb0b9 /doc/pies.texi
parentad5bd6e401657b9cb0fed04d15cdc6feeef91e15 (diff)
downloadpies-1a37a444eea3d238e45d01d47ac157b470f536ac.tar.gz
pies-1a37a444eea3d238e45d01d47ac157b470f536ac.tar.bz2
Reimplement the telinit legacy interface.
pies -T is now fully compatible with the legacy telinit command * src/telinit.opt: New file. * src/Makefile.am: Add telinit.opt * src/cmdline.opt (-T): Remove explicit variable. Rest of command line is processed specially. * src/pies.h (telinit): Change prototype. * src/sysvinit.c (telinit): Rewrite. * src/.gitignore: Update. * doc/pies.texi: Document telinit.
Diffstat (limited to 'doc/pies.texi')
-rw-r--r--doc/pies.texi193
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
@@ -1650,6 +1650,11 @@ component @var{tag} @{
# @r{List of flags.}
# @xref{flags}.
flags (@var{flags});
+
+ # @r{For @i{init} components: runlevels in which to start this}
+ # @r{component.}
+ # @xref{Runlevels}.
+ runlevels @var{string};
# @r{Listen on the given url.}
# @xref{Inetd-Style Components}.
@@ -1704,14 +1709,14 @@ component @var{tag} @{
# @xref{Inetd-Style Components, access-denied-message}.
access-denied-message @var{text};
- # @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};
# @r{or:}
admin-acl @{ @dots{} @}
# @r{ACL for read-only access to this component.}
- # @FIXME-xref{Access to Components}.
+ # @xref{Visibility}.
list-acl @var{name};
# @r{or:}
list-acl @{ @dots{} @}
@@ -2149,29 +2154,40 @@ seconds. This statement is reserved for use in the future. Currently
The control interface is protected by three access control lists
(@xref{ACL}, for a discussion of their syntax).
-@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}
(such as getting information about running components) and @dfn{write}
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}).
In particular, whoever passes @code{admin-acl} can issue commands
for stopping the instance and reloading its configuration.
@end deffn
+ 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}
Defines the realm for basic authentication. Default value is @samp{pies}.
@end deffn
@@ -2454,6 +2470,15 @@ Sets the PID file name.
Sets the name of the @samp{quotation-of-the-day} file.
@end deffn
+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
@chapter Pies Debugging
@xopindex{debug, described}
@@ -2573,8 +2598,9 @@ UNIX socket for communication using @command{piesctl}.
* Runlevels::
* Init Process Configuration::
* Init Command Line::
-* piesctl telinit::
* Init Environment::
+* piesctl telinit::
+* telinit command::
@end menu
@node Runlevels
@@ -2599,7 +2625,7 @@ Multiuser with X11.
@anchor{Ondemand runlevels}
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.
@node Init Process Configuration
@@ -2756,9 +2782,18 @@ Stop parsing after this line. The remaining material is ignored.
Both the traditional @file{/etc/inittab} and pies-native
@file{/etc/pies.init} files are entirely equivalent, excepting that,
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:
@example
component @var{id} @{
@@ -2768,6 +2803,18 @@ component @var{id} @{
@}
@end example
+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
latter can declare components with the same @var{id} as the ones
declared in the former. In that case, the two entries will be merged,
@@ -2822,6 +2869,32 @@ Initialize default runlevel @samp{S}.
Run emergency shell @command{/sbin/sulogin}, prior to initialization.
@end table
+@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
@section piesctl telinit
@@ -2847,31 +2920,72 @@ hold at most 32 variables.
Unset variable @var{NAME}.
@end deffn
-@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
@node Configuration Examples
@chapter Configuration Examples
@@ -3243,6 +3357,13 @@ arguments, dependencies for each component are listed. @xref{trace-depend}.
List prerequisites for components named in the command line. Without
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
Preprocess configuration file and exit. @xref{Preprocessor}.

Return to:

Send suggestions and report system problems to the System administrator.