aboutsummaryrefslogtreecommitdiff
path: root/doc
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
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')
-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} @{
1650 # @r{List of flags.} 1650 # @r{List of flags.}
1651 # @xref{flags}. 1651 # @xref{flags}.
1652 flags (@var{flags}); 1652 flags (@var{flags});
1653
1654 # @r{For @i{init} components: runlevels in which to start this}
1655 # @r{component.}
1656 # @xref{Runlevels}.
1657 runlevels @var{string};
1653 1658
1654 # @r{Listen on the given url.} 1659 # @r{Listen on the given url.}
1655 # @xref{Inetd-Style Components}. 1660 # @xref{Inetd-Style Components}.
@@ -1704,14 +1709,14 @@ component @var{tag} @{
1704 # @xref{Inetd-Style Components, access-denied-message}. 1709 # @xref{Inetd-Style Components, access-denied-message}.
1705 access-denied-message @var{text}; 1710 access-denied-message @var{text};
1706 1711
1707 # @r{ACL for administrative access to this component.} 1712 # @r{ACL for administrative (read-write) access to this component.}
1708 # @FIXME-xref{Access to Components}. 1713 # @xref{Visibility}.
1709 admin-acl @var{name}; 1714 admin-acl @var{name};
1710 # @r{or:} 1715 # @r{or:}
1711 admin-acl @{ @dots{} @} 1716 admin-acl @{ @dots{} @}
1712 1717
1713 # @r{ACL for read-only access to this component.} 1718 # @r{ACL for read-only access to this component.}
1714 # @FIXME-xref{Access to Components}. 1719 # @xref{Visibility}.
1715 list-acl @var{name}; 1720 list-acl @var{name};
1716 # @r{or:} 1721 # @r{or:}
1717 list-acl @{ @dots{} @} 1722 list-acl @{ @dots{} @}
@@ -2149,29 +2154,40 @@ seconds. This statement is reserved for use in the future. Currently
2149 The control interface is protected by three access control lists 2154 The control interface is protected by three access control lists
2150(@xref{ACL}, for a discussion of their syntax). 2155(@xref{ACL}, for a discussion of their syntax).
2151 2156
2152@deffn {Config: control} acl 2157@deffn {Config: control} acl @var{name}
2153 Controls who can connect to the control interface. 2158@deffnx {Config: control} acl @{ @dots{} @}
2159 Controls who can connect to the interface. The first form refers to
2160a named ACL that must have been defined earlier by @code{defacl}
2161statement (@pxref{defacl}). Use the second form to define a new ACL
2162in place.
2154@end deffn 2163@end deffn
2155 2164
2156@deffn {Config: control} user-acl 2165@deffn {Config: control} user-acl @var{name}
2166@deffnx {Config: control} user-acl @{ @dots{} @}
2157 Control interface provides two kinds of operations: @dfn{read-only} 2167 Control interface provides two kinds of operations: @dfn{read-only}
2158(such as getting information about running components) and @dfn{write} 2168(such as getting information about running components) and @dfn{write}
2159operations (such as stopping or restarting components). 2169operations (such as stopping or restarting components).
2160 2170
2161 The @code{user-acl} controls read access to components that don't 2171 The @code{user-acl} controls read access. Access to particular
2162have per-component @code{user-acl} (@FIXME-pxref{per-component user-acl}). 2172components can also be controlled individually, using the
2173per-component @code{list-acl} statement (@pxref{Visibility, list-acl}).
2163@end deffn 2174@end deffn
2164 2175
2165@deffn {Config: control} admin-acl 2176@deffn {Config: control} admin-acl @var{name}
2166 Defines access control list for write access to the @command{pies} 2177@deffnx {Config: control} admin-acl @{ @dots{} @}
2167instance itself and to the components for which no specific 2178 Controls write access to the @command{pies} instance itself and to
2168@code{admin-acl} statements are supplied (@FIXME-pxref{per-component 2179the components for which no specific @code{admin-acl} statements are
2169admin-acl}). 2180supplied (@pxref{Visibility, admin-acl}).
2170 2181
2171 In particular, whoever passes @code{admin-acl} can issue commands 2182 In particular, whoever passes @code{admin-acl} can issue commands
2172for stopping the instance and reloading its configuration. 2183for stopping the instance and reloading its configuration.
2173@end deffn 2184@end deffn
2174 2185
2186 When checking whether the user has a particular kind of access to a
2187component, first the corresponding ACL from the @code{control} section
2188is checked. If it allows access, then the per-component ACL is tried.
2189If it allows access too, then the operation is permitted.
2190
2175@deffn {Config: control} realm @var{name} 2191@deffn {Config: control} realm @var{name}
2176 Defines the realm for basic authentication. Default value is @samp{pies}. 2192 Defines the realm for basic authentication. Default value is @samp{pies}.
2177@end deffn 2193@end deffn
@@ -2454,6 +2470,15 @@ Sets the PID file name.
2454Sets the name of the @samp{quotation-of-the-day} file. 2470Sets the name of the @samp{quotation-of-the-day} file.
2455@end deffn 2471@end deffn
2456 2472
2473The following statements are retained for compatibility with earlier
2474@command{pies} versions. They are silently ignored:
2475
2476@deffn {Config} control-file @var{arg}
2477@end deffn
2478
2479@deffn {Config} stat-file @var{arg}
2480@end deffn
2481
2457@node Pies Debugging 2482@node Pies Debugging
2458@chapter Pies Debugging 2483@chapter Pies Debugging
2459@xopindex{debug, described} 2484@xopindex{debug, described}
@@ -2573,8 +2598,9 @@ UNIX socket for communication using @command{piesctl}.
2573* Runlevels:: 2598* Runlevels::
2574* Init Process Configuration:: 2599* Init Process Configuration::
2575* Init Command Line:: 2600* Init Command Line::
2576* piesctl telinit::
2577* Init Environment:: 2601* Init Environment::
2602* piesctl telinit::
2603* telinit command::
2578@end menu 2604@end menu
2579 2605
2580@node Runlevels 2606@node Runlevels
@@ -2599,7 +2625,7 @@ Multiuser with X11.
2599@anchor{Ondemand runlevels} 2625@anchor{Ondemand runlevels}
2600Additionally, three special runlevels @samp{a}, @samp{b} and @samp{c} 2626Additionally, three special runlevels @samp{a}, @samp{b} and @samp{c}
2601can be used to start @dfn{on-demand} components without actually 2627can be used to start @dfn{on-demand} components without actually
2602changing the runlevel. Once started, on-demain components persist 2628changing the runlevel. Once started, on-demain components persist
2603through eventual runlevel changes. 2629through eventual runlevel changes.
2604 2630
2605@node Init Process Configuration 2631@node Init Process Configuration
@@ -2756,9 +2782,18 @@ Stop parsing after this line. The remaining material is ignored.
2756Both the traditional @file{/etc/inittab} and pies-native 2782Both the traditional @file{/etc/inittab} and pies-native
2757@file{/etc/pies.init} files are entirely equivalent, excepting that, 2783@file{/etc/pies.init} files are entirely equivalent, excepting that,
2758naturally, the latter is more flexible and gives much more 2784naturally, the latter is more flexible and gives much more
2759possibilities in defining the system behavior. The inittab entry 2785possibilities in defining the system behavior. The declaration of a
2760discussed above is equivalent to the following statement in 2786component in @file{/etc/pies.init} can contain all the statements
2761@file{pies.init} file: 2787discussed in @ref{Component Statement}. The only difference is that
2788runlevels to start the component is must be specified:
2789
2790@deffn {Config: component} runlevels @var{string}
2791Specifies the runlevel to start the component in. The @var{string}
2792argument is a string of runlevel characters.
2793@end deffn
2794
2795For example, the inittab entry discussed above is equivalent to the
2796following statement in @file{pies.init} file:
2762 2797
2763@example 2798@example
2764component @var{id} @{ 2799component @var{id} @{
@@ -2768,6 +2803,18 @@ component @var{id} @{
2768@} 2803@}
2769@end example 2804@end example
2770 2805
2806The default runlevel is specified in @file{/etc/pies.init} using
2807the following construct:
2808
2809@deffn {Config} initdefault @var{rl}
2810Declare the default runlevel. The argument is the runlevel name.
2811E.g.
2812
2813@example
2814initdefault 3;
2815@end example
2816@end deffn
2817
2771If both @file{/etc/inittab} and @file{/etc/pies.init} are present, the 2818If both @file{/etc/inittab} and @file{/etc/pies.init} are present, the
2772latter can declare components with the same @var{id} as the ones 2819latter can declare components with the same @var{id} as the ones
2773declared in the former. In that case, the two entries will be merged, 2820declared in the former. In that case, the two entries will be merged,
@@ -2822,6 +2869,32 @@ Initialize default runlevel @samp{S}.
2822Run emergency shell @command{/sbin/sulogin}, prior to initialization. 2869Run emergency shell @command{/sbin/sulogin}, prior to initialization.
2823@end table 2870@end table
2824 2871
2872@node Init Environment
2873@section Init Environment
2874
2875Programs run from @command{pies} init process inherit a basic
2876environment consisting of the following variables:
2877
2878@table @option
2879@item PREVLEVEL=@var{L}
2880Previous runlevel, or letter @samp{N} if the runlevel hasn't been
2881changed since startup.
2882
2883@item RUNLEVEL=@var{L}
2884Current runlevel.
2885
2886@item CONSOLE=@var{device}
2887Pathname of the console device file.
2888
2889@item INIT_VERSION="GNU Pies @value{VERSION}"
2890Version of @command{pies}.
2891
2892@item PATH=/bin:/usr/bin:/sbin:/usr/sbin
2893@end table
2894
2895Once the system is booted up, the environment can be controlled using
2896the @command{piesctl telinit environ} (or @command{pies -T -e}) command.
2897
2825@node piesctl telinit 2898@node piesctl telinit
2826@section piesctl telinit 2899@section piesctl telinit
2827 2900
@@ -2847,31 +2920,72 @@ hold at most 32 variables.
2847Unset variable @var{NAME}. 2920Unset variable @var{NAME}.
2848@end deffn 2921@end deffn
2849 2922
2850@node Init Environment 2923@node telinit command
2851@section Init Environment 2924@section The Telinit Command
2852 2925
2853Programs run from @command{pies} init process inherit a basic 2926@xopindex{telinit option, introduced}
2854environment consisting of the following variables: 2927 When given the @option{-T} (@option{--telinit}) option,
2928@command{pies} emulates the behavior of the traditional
2929@command{telinit} command. This is a legacy way of communicating with
2930the init process. The commands are sent via named pipe
2931@file{/dev/initctl}. When the @option{-T} option is given, the rest
2932of command line after it is handled as @command{telinit} options. The
2933following command:
2855 2934
2856@table @option 2935@example
2857@item PREVLEVEL=@var{L} 2936pies -T [-t @var{n}] @var{r}
2858Previous runlevel, or letter @samp{N} if the runlevel hasn't been 2937@end example
2859changed since startup.
2860 2938
2861@item RUNLEVEL=@var{L} 2939@noindent
2862Current runlevel. 2940tells init process to switch to runlevel @var{r}. Possible values for
2941@var{r} are:
2863 2942
2864@item CONSOLE=@var{device} 2943@table @asis
2865Pathname of the console device file. 2944@item 0 to 9
2945Instructs init to switch to the specified runlevel.
2946@item S or s
2947Tells init to switch to the single user mode.
2948@item a, b, or c
2949Tells init to enable on-demand components with the specified
2950runlevel. The actual runlevel is not changed.
2951@item Q or q
2952Tells init to rescan configuration files.
2953@end table
2866 2954
2867@item INIT_VERSION="GNU Pies @value{VERSION}" 2955The @option{-t} (@option{--timeout}) option sets the time to wait
2868Version of @command{pies}. 2956for processes to terminate after sending them the SIGTERM signal. Any
2957processes that remain running after @var{n} seconds will be sent the
2958SIGKILL signal. The default value is 5 seconds.
2869 2959
2870@item PATH=/bin:/usr/bin:/sbin:/usr/sbin 2960This usage is equivalent to the @command{piesctl telinit runlevel}
2871@end table 2961command (@pxref{piesctl telinit}).
2872 2962
2873Once the system is booted up, the environment can be controlled using 2963The @option{-e} (@option{--environment}) option modifies the init
2874the @command{piesctl telinit environ} command. 2964process environment. Its argument is either a variable assignment
2965@samp{@var{name}=@var{value}} to set a variable, or the name of a
2966variable to unset it. Several @option{-e} options can be given to
2967process multiple variables in a single command. Note, however, that
2968given @var{n} @option{-e} options, the total length of their arguments
2969is limited to 367 - @var{n} bytes.
2970
2971This option provides a limited subset of the functionality offered by
2972the @command{piesctl telinit environ} command.
2973
2974The table below summarizes all options available in @option{telinit}
2975mode:
2976
2977@table @option
2978@item -t @var{n}
2979Wait @var{n} seconds for processes to terminate after sending them the
2980SIGTERM signal. Any processes that remain running after that time
2981will be sent the SIGKILL signal. The default value is 5 seconds.
2982
2983@item -e @var{var}=@var{value}
2984Define environment variable @var{var} as having value @var{value}.
2985
2986@item -e @var{var}
2987Unset environment variable @var{var}.
2988@end table
2875 2989
2876@node Configuration Examples 2990@node Configuration Examples
2877@chapter Configuration Examples 2991@chapter Configuration Examples
@@ -3243,6 +3357,13 @@ arguments, dependencies for each component are listed. @xref{trace-depend}.
3243List prerequisites for components named in the command line. Without 3357List prerequisites for components named in the command line. Without
3244arguments, prerequisites for each component are listed. @xref{trace-prereq}. 3358arguments, prerequisites for each component are listed. @xref{trace-prereq}.
3245 3359
3360@opsummary{telinit}
3361@item --telinit
3362@item -T
3363Emulate the @command{telinit} legacy interface. The rest of command
3364line following this option is processed as @command{telinit} options.
3365@xref{telinit command}, for a detailed description of these.
3366
3246@item -E 3367@item -E
3247Preprocess configuration file and exit. @xref{Preprocessor}. 3368Preprocess configuration file and exit. @xref{Preprocessor}.
3248 3369

Return to:

Send suggestions and report system problems to the System administrator.