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
2296in turn until the one is found where authentication succeeds.
2297Subsequent group membership checks will then use this identity provider.
2298
2195@node inetd 2299@node inetd
2196@section Using @command{inetd} Configuration Files 2300@section Using @command{inetd} Configuration Files
2197@cindex inetd.conf 2301@cindex inetd.conf
@@ -2524,7 +2628,460 @@ This feature is designed for @command{pies} developers.
2524 2628
2525@node piesctl 2629@node piesctl
2526@chapter Communicating with Running @command{pies} Instances 2630@chapter Communicating with Running @command{pies} Instances
2527@WRITEME 2631 The @command{piesctl} tool allows you to communicate with the
2632running @command{pies} program. The invocation syntax is:
2633
2634@example
2635piesctl [@var{options}] @var{command} [@var{args}...]
2636@end example
2637
2638The @var{command} determines the operation to perform. The following
2639sections describe available commands in detail.
2640
2641@menu
2642* id:: Get Info About the Running Instance.
2643* stop and reboot:: Instance Management.
2644* config:: Configuration Management.
2645* components:: Component Management.
2646* telinit:: Init Process Management.
2647* options:: @command{piesctl} options.
2648* piesctl.conf:: Configuration file for @command{piesctl}.
2649@end menu
2650
2651@node id
2652@section piesctl id -- Return Info About the Running Instance
2653@cindex id, piesctl
2654@cindex piesctl id
2655 The @option{id} subcommand returns information about the
2656@command{pies} instance organized as key-value pairs. When invoked
2657without arguments, the following data are returned:
2658
2659@table @asis
2660@item package
2661Canonical package name.
2662@item version
2663Version of @command{pies}.
2664@item instance
2665Instance name (@pxref{instances}).
2666@item binary
2667Full pathname of the @command{pies} executable file.
2668@item argv
2669Command line arguments supplied upon its startup.
2670@item PID
2671Process ID.
2672@end table
2673
2674For example:
2675
2676@example
2677@group
2678$ piesctl id
2679package: GNU Pies
2680version: @value{VERSION}
2681instance: pies
2682binary: /usr/sbin/pies
2683argv: /usr/sbin/pies --config-file=/etc/pies/pies.conf
2684PID: 15679
2685@end group
2686@end example
2687
2688To request a subset of these data, give the items of interest as
2689command line arguments:
2690
2691@example
2692@group
2693$ piesctl id binary PID
2694binary: /usr/sbin/pies
2695PID: 15679
2696@end group
2697@end example
2698
2699@node stop and reboot
2700@section Instance Management
2701
2702Two subcommands are provided for stopping and restarting @command{pies}.
2703
2704@deffn {piesctl} shutdown
2705Stop the running @command{pies} instance
2706@end deffn
2707
2708@deffn {piesctl} reboot
2709Restart @command{pies} instance. Upon receiving this command,
2710@command{pies} will restart itself with the same command line
2711arguments. Naturally, this means that all running components will
2712be restarted as well.
2713@end deffn
2714
2715These subcommands do nothing when init process is selected.
2716
2717@node config
2718@section piesctl config -- Configuration Management
2719
2720@deffn {piesctl} config file list
2721List currently loaded configuration files.
2722@end deffn
2723
2724@deffn {piesctl} config file clear
2725Clear configuration file list
2726@end deffn
2727
2728@deffn {piesctl} config file add @var{syntax} @var{file}
2729Add @var{file} to the list of configuration files. @var{syntax}
2730specifies its syntax: @samp{pies}, @samp{inetd}, @samp{meta1}, or
2731@samp{inittab}.
2732@end deffn
2733
2734@deffn {piesctl} config file del[ete] @var{name} [@var{name}...]
2735Remove listed names from the list of configuration files.
2736@end deffn
2737
2738@anchor{config reload}
2739@deffn {piesctl} config reload
2740Reload configuration.
2741@end deffn
2742
2743@node components
2744@section Component Management
2745
2746@anchor{piesctl list}
2747@deffn {piesctl} list [@var{condition}]
2748List configured components. When used without arguments, all
2749components are listed. Otherwise, only processes matching
2750@var{condition} are listed.
2751
2752 Each output line contains at least two columns. The first column
2753lists the tag of the component. The second one contains @dfn{flags},
2754describing the type and status of the component. The first flag
2755describes the type:
2756
2757@multitable @columnfractions 0.2 0.7
2758@headitem Flag @tab Meaning
2759@item 3 @tab SysV init @samp{ctrlaltdel} component
2760@item A @tab Accept-style component
2761@item B @tab SysV init @samp{boot} component
2762@item C @tab Respawn component
2763@item c @tab SysV init @samp{once} component
2764@item D @tab SysV init @samp{ondemand} component
2765@item E @tab Command being executed
2766@item F @tab SysV init @samp{powerfail} component
2767@item f @tab SysV init @samp{powerwait} component
2768@item I @tab Inetd-style component
2769@item i @tab SysV init @samp{sysinit} component
2770@item k @tab SysV init @samp{kbrequest} component
2771@item n @tab SysV init @samp{powerfailnow} component
2772@item o @tab SysV init @samp{powerokwait} component
2773@item P @tab Pass-style component
2774@item R @tab Output redirector
2775@item W @tab SysV init @samp{wait} component
2776@item w @tab SysV init @samp{bootwait} component
2777@end multitable
2778
2779 The second flag is meaningful only for components. Its values are:
2780
2781@multitable @columnfractions 0.2 0.7
2782@headitem Flag @tab Meaning
2783@item - @tab Disabled component
2784@item f @tab A finished @samp{once} component
2785@item L @tab Inetd listener
2786@item R @tab Running component
2787@item S @tab Component is stopping
2788@item s @tab Component is sleeping
2789@item T @tab Component is stopped
2790@end multitable
2791
2792 The next column lists the PID (for running components) or socket address
2793(for Internet listeners), or the string @samp{N/A} if neither of the
2794above applies.
2795
2796 If the component is sleeping, the time of its scheduled wake-up is
2797listed in the next column.
2798
2799 Rest of line shows the component command line.
2800
2801@example
2802@group
2803$ piesctl list
2804smtps/stderr R 4697
2805pmult/stderr R 4677
2806pmult/stdout R 4676
2807pmult CR 4678 /usr/local/sbin/pmult
2808smar CR 4680 smar -f /etc/meta1/meta1.conf -d 100
2809qmgr CR 4691 qmgr -f /etc/meta1/meta1.conf
2810smtpc CR 4696 smtpc -f /etc/meta1/meta1.conf
2811smtps PR 4698 smtps -d100 -f /etc/meta1/meta1.conf
2812finger IL inet+tcp://0.0.0.0:finger /usr/sbin/in.fingerd -u
2813eklogin IL inet+tcp://0.0.0.0:eklogin /usr/sbin/klogind -k -c -e
2814kshell IL inet+tcp://0.0.0.0:kshell /usr/sbin/kshd -k -c
2815eklogin IR 13836 /usr/local/sbin/klogind -k -c -e
2816@end group
2817@end example
2818@end deffn
2819
2820Use @var{condition} to select the components to list. In its simplest
2821form, @var{condition} is one of the following @dfn{terms}:
2822
2823@table @asis
2824@item all
2825Selects all processes, including internal services, such as output
2826redirectors.
2827
2828@item active
2829Selects only active components.
2830
2831@item component @var{tag}
2832Selects the component with the given tag. @xref{Component Statement, tag}.
2833
2834@item type @var{arg}
2835Selects processes of the given type. Argument is @samp{component}, to
2836select only components, @samp{command}, to select commands or
2837@samp{redirector} to select output redirectors. When @command{piesctl
2838list} is used without arguments, @option{type component} is assumed.
2839
2840@item mode @var{arg}
2841Selects components of the given mode (@pxref{Component Statement,
2842mode}). E.g. to list @samp{inetd} components:
2843
2844@example
2845piesctl list mode inetd
2846@end example
2847
2848@item status @var{arg}
2849Selects processes with the given status. Argument is one of:
2850
2851@table @asis
2852@item finished
2853Component is finished.
2854
2855@item listener
2856Component is an inet listener.
2857
2858@item running
2859Component is running.
2860
2861@item sleeping
2862Component is sleeping.
2863
2864@item stopped
2865Component is stopped.
2866
2867@item stopping
2868Component has been sent the SIGTERM signal and @command{pies} is
2869waiting for it to terminate.
2870@end table
2871@end table
2872
2873A term may be preceded by the word @samp{not} to indicate negation of
2874the condition. For example, the following command will list inactive
2875components:
2876
2877@example
2878piesctl list not active
2879@end example
2880
2881Furthermore, terms can be combined in logical expressions using
2882boolean @samp{and} and @samp{or} operators:
2883
2884@example
2885piesctl list type component and not mode inetd
2886@end example
2887
2888Conjunction (@samp{and}) has higher precedence than disjunction
2889(@samp{or}). In complex expressions parentheses can be used to
2890alter the precedence:
2891
2892@example
2893piesctl list type component \
2894 and \( status running or status sleeping \)
2895@end example
2896
2897Notice that parentheses must be escaped to prevent them from being
2898interpreted by the shell.
2899
2900The following summarizes the syntax of @var{condition} in BNF:
2901
2902@example
2903<condition> ::= <disjunction>
2904<disjunction> ::= <conjunction> | <conjunction> "or" <disjunction>
2905<conjunction> ::= <unary> | <unary> "and" <conjunction>
2906<unary> ::= <term> | "not" <condition> | "(" <condition> ")"
2907<term> ::= "all" | "active" | <keyword> <value>
2908<keyword> ::= "type" | "mode" | "status" | "component"
2909<value> ::= <word> | <quoted-string>
2910<word> ::= <printable> | <word> <printable>
2911<printable> ::= "A" - "Z" | "a" - "z" | "0" - "9" |
2912 "_" | "." | "*" | ":" | "@@" | "[" | "]" | "-" | "/"
2913<quoted-string> ::= """ <string> """
2914<string> ::= <char> | <string> <char>
2915<char> ::= <any character except "\" and """> | "\\" | "\""
2916@end example
2917
2918@deffn {piesctl} stop @var{condition}
2919Stop components matching @var{condition}.
2920@end deffn
2921
2922@deffn {piesctl} start @var{condition}
2923Start components matching @var{condition}.
2924@end deffn
2925
2926@deffn {piesctl} restart @var{condition}
2927Restart components.
2928@end deffn
2929
2930@node telinit
2931@section Init Process Management
2932
2933The @command{piesctl telinit} command communicates with @command{pies}
2934instance running as @dfn{init} process (PID 1). @xref{piesctl
2935telinit}, for a detailed discussion.
2936
2937@node options
2938@section @command{Piesctl} Command Line Options
2939
2940@table @option
2941@item -c @var{file}
2942@itemx --config-file=@var{file}
2943Read configuration from @var{file} instead of the default
2944@file{/etc/piesctl.conf}. @xref{piesctl.conf}, for its description.
2945
2946@item -d
2947@itemx --dump
2948Dump obained responses verbatim. This is useful mainly for debugging
2949purposes.
2950
2951@item -i @var{inst}
2952@itemx --instance=@var{inst}
2953Talk to @command{pies} instance @var{inst}.
2954
2955@item -u @var{url}
2956@itemx --url=@var{url}
2957Specifies the URL of the communication socket. @xref{piesctl url},
2958for a description of allowed URL forms.
2959
2960@item -v
2961@itemx --verbose
2962Enable verbose diagnostics.
2963@end table
2964
2965Before parsing, configuration file is preprocessed using
2966@command{m4}. The following options control this feature:
2967
2968@table @option
2969@item -E
2970Show preprocessed configuration on stdout and exit.
2971
2972@item --define=@var{sym}[=@var{value}]
2973@itemx -D @var{symbol}[=@var{value}]
2974Define symbol @var{sym} as having @var{value}, or empty, if
2975the @var{value} is not given.
2976
2977@item --include-directory=@var{dir}
2978@itemx -I @var{dir}
2979Add directory @var{dir} to the list of directories to be scanned for
2980include files. @xref{include search path}.
2981
2982@item --undefine=@var{sym}
2983@itemx -U @var{sym}
2984Undefine symbol @var{sym}.
2985@end table
2986
2987Finally, the following options can be used to obtain on-line assistance:
2988
2989@table @option
2990@item --config-help
2991Show a terse reference to configuration file syntax and exit.
2992
2993@item -h
2994@itemx --help
2995Display command line help summary.
2996
2997@item --usage
2998Give a short usage message
2999
3000@item -V
3001@itemx --version
3002Show program version.
3003@end table
3004
3005@node piesctl.conf
3006@section Configuration for @command{piesctl}
3007
3008 The configuration file @file{/etc/piesctl.conf} helps the
3009@command{piesctl} tool to determine the URL of the control socket.
3010This file is not mandatory, and its absence is not considered an
3011error. Its syntax is similar to that of @file{/etc/pies.conf}. The
3012following statements are defined:
3013
3014@deffn {piesctl.conf} socket @var{url}
3015Sets the default socket URL.
3016@end deffn
3017
3018@deffn {piesctl.conf} source @var{ip}
3019Sets the default source IP address. This is used if the control
3020socket is of @samp{inet} type.
3021@end deffn
3022
3023@deffn {piesctl.conf} instance @var{name}
3024Configures socket URL and (optionally) source address to use when
3025communicating with the @command{pies} instance @var{name} (i.e., when
3026invoked as @command{piesctl -i @var{name}}:
3027
3028@example
3029instance @var{name} @{
3030 # @r{Socket URL for that instance.}
3031 socket @var{url};
3032 # Source IP address.
3033 source @var{ip};
3034@}
3035@end example
3036@end deffn
3037
3038@anchor{piesctl url}
3039Valid values for @var{url} in the above statements are:
3040
3041@table @asis
3042@item inet://@var{ip}:@var{port}
3043Use the IPv4 address @var{ip} (may be given as a symbolic host name),
3044on port @var{port}.
3045
3046@item local://@var{file}
3047@itemx file://@var{file}
3048@itemx unix://@var{file}
3049Use the @acronym{UNIX} socket file @var{file}.
3050@end table
3051
3052The following algorithm is used to determine the name of the
3053communication socket:
3054
3055@enumerate 1
3056@item
3057If the @option{--url} (@option{-u}) option is given, use its argument.
3058@item
3059Determine the instance name (@var{inst}). If the @option{--instance}
3060(@option{-i}) is given, @var{inst} is its argument. Otherwise, assume
3061@var{inst}=@samp{pies}.
3062@item
3063If configuration file @file{/etc/piesctl.conf} exists, read it. On
3064success:
3065@enumerate a
3066@item
3067See if the @code{instance @var{inst}} statement is present
3068and has @code{socket} substatement. If so, the argument to
3069@code{socket} gives the socket URL.
3070@item
3071Otherwise, if global @code{socket} statement is present, its argument
3072gives the URL.
3073@end enumerate
3074@item
3075Otherwise, suppose that @command{piesctl} is run on the same box where
3076the target instance of @command{pies} is running, and see if the file
3077@file{/etc/@var{inst}.conf} exists. If so, parse it as
3078@command{pies} configuration file and look for @command{control} block
3079statement. If it has @code{socket} statement, take its argument as
3080the URL. @xref{control}.
3081@item
3082If socket URL is not determined by these steps, assume
3083@file{/tmp/@var{inst}.ctl}.
3084@end enumerate
2528 3085
2529@node Init Process 3086@node Init Process
2530@chapter Init -- parent of all processes 3087@chapter Init -- parent of all processes
@@ -2898,25 +3455,25 @@ the @command{piesctl telinit environ} (or @command{pies -T -e}) command.
2898@node piesctl telinit 3455@node piesctl telinit
2899@section piesctl telinit 3456@section piesctl telinit
2900 3457
2901@deffn {Telnit Runlevel} piesctl telinit runlevel 3458@deffn {piesctl} piesctl telinit runlevel
2902Report the runlevel and state of the process 1. 3459Report the runlevel and state of the process 1.
2903@end deffn 3460@end deffn
2904 3461
2905@deffn {Telnit Runlevel} piesctl telinit runlevel @var{n} 3462@deffn {piesctl} piesctl telinit runlevel @var{n}
2906Switch to runlevel @var{n}. 3463Switch to runlevel @var{n}.
2907@end deffn 3464@end deffn
2908 3465
2909@deffn {Telnit Env} piesctl telinit environ list [@var{NAME}] 3466@deffn {piesctl} piesctl telinit environ list [@var{NAME}]
2910List the environment. If @var{NAME} is given, list only the value of 3467List the environment. If @var{NAME} is given, list only the value of
2911that variable. 3468that variable.
2912@end deffn 3469@end deffn
2913 3470
2914@deffn {Telinit Env} piesctl telinit environ set @var{NAME}=@var{VALUE} 3471@deffn {piesctl} piesctl telinit environ set @var{NAME}=@var{VALUE}
2915Set variable @var{NAME} to @var{VALUE}. The environment is capable to 3472Set variable @var{NAME} to @var{VALUE}. The environment is capable to
2916hold at most 32 variables. 3473hold at most 32 variables.
2917@end deffn 3474@end deffn
2918 3475
2919@deffn {Telinit Env} piesctl telinit environ unset @var{NAME} 3476@deffn {piesctl} piesctl telinit environ unset @var{NAME}
2920Unset variable @var{NAME}. 3477Unset variable @var{NAME}.
2921@end deffn 3478@end deffn
2922 3479
@@ -3144,7 +3701,7 @@ the third one reads it from @file{/etc/mta.conf}.
3144 3701
3145@anchor{pies-status} 3702@anchor{pies-status}
3146 After startup, you can verify the status of the running process 3703 After startup, you can verify the status of the running process
3147using the @option{--status} command line option: 3704using the @option{--status} option.
3148 3705
3149@example 3706@example
3150@group 3707@group
@@ -3164,54 +3721,7 @@ eklogin IR 13836 /usr/local/sbin/klogind -k -c -e
3164@end group 3721@end group
3165@end example 3722@end example
3166 3723
3167 Each output line contains at least two columns. The first column 3724@xref{piesctl list}, for a description of the output format.
3168lists the tag of the component. The second one contains @dfn{flags},
3169describing the type and status of the component. The first flag
3170describes the type:
3171
3172@multitable @columnfractions 0.2 0.7
3173@headitem Flag @tab Meaning
3174@item 3 @tab SysV init @samp{ctrlaltdel} component
3175@item A @tab Accept-style component
3176@item B @tab SysV init @samp{boot} component
3177@item C @tab Init-style component
3178@item c @tab SysV init @samp{once} component
3179@item D @tab SysV init @samp{ondemand} component
3180@item E @tab Command being executed
3181@item F @tab SysV init @samp{powerfail} component
3182@item f @tab SysV init @samp{powerwait} component
3183@item I @tab Inetd-style component
3184@item i @tab SysV init @samp{sysinit} component
3185@item k @tab SysV init @samp{kbrequest} component
3186@item n @tab SysV init @samp{powerfailnow} component
3187@item o @tab SysV init @samp{powerokwait} component
3188@item P @tab Pass-style component
3189@item R @tab Output redirector
3190@item W @tab SysV init @samp{wait} component
3191@item w @tab SysV init @samp{bootwait} component
3192@end multitable
3193
3194 The second flag is meaningful only for components. Its values are:
3195
3196@multitable @columnfractions 0.2 0.7
3197@headitem Flag @tab Meaning
3198@item - @tab Disabled component
3199@item f @tab A finished @samp{once} component
3200@item L @tab Inetd listener
3201@item R @tab Running component
3202@item S @tab Component is stopping
3203@item s @tab Component is sleeping
3204@item T @tab Component is stopped
3205@end multitable
3206
3207 The next column lists the PID (for running components) or socket address
3208(for Internet listeners), or the string @samp{N/A} if neither of the
3209above applies.
3210
3211 If the component is sleeping, the time of its scheduled wake-up is
3212listed in the next column.
3213
3214 The rest of line contains the component command line.
3215 3725
3216@anchor{pies-restart} 3726@anchor{pies-restart}
3217@xopindex{restart-component, described} 3727@xopindex{restart-component, described}
@@ -3230,6 +3740,15 @@ $ pies -R pmult smtps
3230$ pies --stop 3740$ pies --stop
3231@end example 3741@end example
3232 3742
3743If you modified the configuration file, you can instruct
3744@command{pies} to read it again using the @option{--reload}
3745(@option{-r}) command line option.
3746
3747The @option{--status}, @option{--restart-component},
3748@option{--stop}, and @option{--reload} options actually run the
3749@command{piesctl} command, which provides a powerful tool for managing
3750@command{pies}. @xref{piesctl}, for a detailed description.
3751
3233@cindex dependencies 3752@cindex dependencies
3234@anchor{dump-depmap} 3753@anchor{dump-depmap}
3235@xopindex{dump-depmap option, introduced} 3754@xopindex{dump-depmap option, introduced}
@@ -3325,11 +3844,11 @@ This section summarizes @command{pies} command line options.
3325Read configuration from @var{file}, instead of the default 3844Read configuration from @var{file}, instead of the default
3326@file{/etc/pies.conf}. 3845@file{/etc/pies.conf}.
3327 3846
3328@xref{Pies Configuration File}. 3847@xref{Configuration}.
3329 3848
3330@opsummary{config-help} 3849@opsummary{config-help}
3331@item --config-help 3850@item --config-help
3332Show configuration file summary. @xref{Pies Configuration File}. 3851Show configuration file summary. @xref{Configuration}.
3333 3852
3334@opsummary{define} 3853@opsummary{define}
3335@item --define=@var{sym}[=@var{value}] 3854@item --define=@var{sym}[=@var{value}]
@@ -3406,7 +3925,8 @@ Show source info with debugging messages. @xref{source-info}.
3406@opsummary{status} 3925@opsummary{status}
3407@item --status 3926@item --status
3408@itemx -s 3927@itemx -s
3409Display info about the running instance. @xref{pies-status}. 3928Start @command{piesctl list} to obtain information about the running
3929processes. @xref{piesctl list}.
3410 3930
3411@opsummary{stderr} 3931@opsummary{stderr}
3412@item --stderr 3932@item --stderr
@@ -3415,7 +3935,8 @@ Log to standard error.
3415@opsummary{stop} 3935@opsummary{stop}
3416@item --stop 3936@item --stop
3417@itemx -S 3937@itemx -S
3418Stop the running instance. 3938Stop the running instance. This is equivalent to running
3939@command{piesctl shutdown}.
3419 3940
3420@opsummary{syntax} 3941@opsummary{syntax}
3421@item --syntax=@var{type} 3942@item --syntax=@var{type}
@@ -3425,7 +3946,7 @@ for @var{type} are:
3425 3946
3426@table @asis 3947@table @asis
3427@item pies 3948@item pies
3428Native @command{pies} configuration. @xref{Pies Configuration File}. 3949Native @command{pies} configuration. @xref{Configuration}.
3429 3950
3430@item inetd 3951@item inetd
3431@samp{Inetd}-style configuration files. @xref{inetd.conf}. 3952@samp{Inetd}-style configuration files. @xref{inetd.conf}.
@@ -3453,7 +3974,8 @@ components. @xref{max-rate,, inetd component rate}.
3453@item -r 3974@item -r
3454@itemx --reload 3975@itemx --reload
3455@itemx --hup 3976@itemx --hup
3456Reload the running instance of pies. 3977Reread the configuration files. This is equivalent to running
3978@command{piesctl config reload} (@pxref{config reload}).
3457 3979
3458@opsummary{restart-component} 3980@opsummary{restart-component}
3459@item -R 3981@item -R

Return to:

Send suggestions and report system problems to the System administrator.