diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile.am | 3 | ||||
| -rw-r--r-- | doc/ctl.texi | 2 | ||||
| -rw-r--r-- | doc/gendocs.pl | 2 | ||||
| -rw-r--r-- | doc/htmlxref.cnf | 15 | ||||
| -rw-r--r-- | doc/inetd.texi | 2 | ||||
| -rw-r--r-- | doc/pies.texi | 542 | ||||
| -rw-r--r-- | doc/usr-acl.texi | 2 |
8 files changed, 437 insertions, 132 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index e58b88f..80a6a43 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -23,3 +23,4 @@ pies.tp pies.vr pies.fns pies.vrs +/manual diff --git a/doc/Makefile.am b/doc/Makefile.am index 15b5ca2..606367e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,5 +1,5 @@ # This file is part of GNU Pies. -# Copyright (C) 2005-2021 Sergey Poznyakoff +# Copyright (C) 2005-2023 Sergey Poznyakoff # # GNU Pies is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -87,3 +87,4 @@ manual: $(GENDOCS) -C manual -o otherdoc.texi $(PACKAGE) otherdoc.texi.in $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -DWEBDOC \ --html --init-file=webdoc.init $(info_TEXINFOS) -o manual + diff --git a/doc/ctl.texi b/doc/ctl.texi index 77f519c..2194f39 100644 --- a/doc/ctl.texi +++ b/doc/ctl.texi @@ -1,5 +1,5 @@ @c This is part of the GNU Pies manual. -@c Copyright (C) 2009--2021 Sergey Poznyakoff +@c Copyright (C) 2009--2023 Sergey Poznyakoff @c This file is distributed under GFDL 1.3 or any later version @c published by the Free Software Foundation. diff --git a/doc/gendocs.pl b/doc/gendocs.pl index 3574687..c229345 100644 --- a/doc/gendocs.pl +++ b/doc/gendocs.pl @@ -1,5 +1,5 @@ # This file is part of GNU Pies. -# Copyright (C) 2020-2021 Sergey Poznyakoff +# Copyright (C) 2020-2023 Sergey Poznyakoff # # GNU Pies is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by diff --git a/doc/htmlxref.cnf b/doc/htmlxref.cnf new file mode 100644 index 0000000..5e9d9c5 --- /dev/null +++ b/doc/htmlxref.cnf @@ -0,0 +1,15 @@ +PUSZCZA=https://www.gnu.org.ua/software +MAILFROMD=${PUSZCZA}/mailfromd/manual +mailfromd mono ${MAILFROMD}/mailfromd.html +mailfromd node ${MAILFROMD}/html_node/ +mailfromd section ${MAILFROMD}/html_section/ +mailfromd chapter ${MAILFROMD}/html_chapter/ + +GNU=http://www.gnu.org/software +M4=${GNU}/m4/manual +m4 mono ${M4}/m4.html +m4 node ${M4}/html_node/ +m4 section ${M4}/html_section/ +m4 chapter ${M4}/html_chapter/ + +identd(1) mono https://man.gnu.org.ua/8/identd
\ No newline at end of file diff --git a/doc/inetd.texi b/doc/inetd.texi index 23850c1..9337f44 100644 --- a/doc/inetd.texi +++ b/doc/inetd.texi @@ -1,5 +1,5 @@ @c This is part of the GNU Pies manual. -@c Copyright (C) 2009--2021 Sergey Poznyakoff +@c Copyright (C) 2009--2023 Sergey Poznyakoff @c This file is distributed under GFDL 1.3 or any later version @c published by the Free Software Foundation. diff --git a/doc/pies.texi b/doc/pies.texi index 747c7ea..84304e1 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -43,7 +43,7 @@ Published by the Free Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -Copyright @copyright{} 2005--2021 Sergey Poznyakoff +Copyright @copyright{} 2005--2023 Sergey Poznyakoff Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -79,7 +79,7 @@ documents @command{pies} Version @value{VERSION}. @menu * Intro:: Introduction to Process Management with @command{Pies}. * Dependencies:: Inter-process dependencies. -* Configuration:: Configuration Files of Various Syntaxes. +* Configuration:: Configuration Files of Various Syntax. * Pies Debugging:: Debugging @command{Pies}. * piesctl:: Communication with Running @command{pies} Instances. * Init Process:: Using @command{Pies} as Parent of All Processes. @@ -108,6 +108,7 @@ Appendices Pies Configuration File * Syntax:: Configuration File Syntax +* Preprocessor:: Using Preprocessor * Component Statement:: * Notification:: Mail Notification. * ACL:: Access Control Lists. @@ -122,7 +123,6 @@ Configuration File Syntax * Comments:: * Statements:: -* Preprocessor:: Using preprocessor to improve the configuration. Component Statement @@ -361,6 +361,7 @@ line option. @menu * Syntax:: Configuration File Syntax +* Preprocessor:: Using preprocessor. * Component Statement:: * Notification:: Mail Notification. * ACL:: Access Control Lists. @@ -386,7 +387,6 @@ keywords and values. @menu * Comments:: * Statements:: -* Preprocessor:: Using preprocessor to improve the configuration. @end menu @node Comments @@ -495,19 +495,6 @@ physical lines, e.g.: If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued. -@ignore - Two or more adjacent quoted strings are concatenated, which gives -another way to split long strings over several lines to improve -readability. The following fragment produces the same result as in the -example above: - -@example -@group -"a long string may be" -" split over several lines" -@end group -@end example -@end ignore @anchor{here-document} @item Here-document @cindex here-document @@ -596,7 +583,7 @@ component multiplexor @{ this is not required. @node Preprocessor -@subsection Using Preprocessor to Improve the Configuration. +@section Preprocessor @cindex preprocessor Before parsing, configuration file is preprocessed. This goes in three stages. First, include directives are expanded. An @@ -608,13 +595,8 @@ replaced using the following rules: @table @code @kwindex #include -@item #include <@var{file}> -@itemx #include @var{file} -The contents of the file @var{file} is included. There are three possible -use cases. - -If @var{file} is an absolute file name, the named file is included. -An error message will be issued if it does not exist. +@item #include @var{file} +The contents of the file @var{file} is included. If @var{file} contains wildcard characters (@samp{*}, @samp{[}, @samp{]} or @samp{?}), it is interpreted as shell globbing pattern and @@ -622,35 +604,13 @@ all files matching that pattern are included, in lexicographical order. If no matching files are found, the directive is replaced with an empty line. -Otherwise, the form with angle brackets searches for file in the -@dfn{include search path}, while the second one looks for it in the -current working directory first, and, if not found there, in the -include search path. If the file is not found, an error message will -be issued. - -@cindex include search path, preprocessor -@cindex include directories, preprocessor -@cindex preprocessor include search path -@anchor{include search path} -The include search path is: - -@enumerate 1 -@item -@xopindex{include-directory, described} -Any directories supplied with the @option{-I} (@option{--include-directory}) -command line option. These directories are scanned in the same order -as they appear in the command line. - -@item @file{@var{prefix}/share/pies/@value{VERSION}/include} -@item @file{@var{prefix}/share/pies/include} -@end enumerate - -@noindent -where @var{prefix} is the installation prefix. +Otherwise, the named file is included. Unless @var{file} is an +absolute file name, it will be searched relative to the current +working directory. An error message will be issued if it does not +exist. @kwindex #include_once -@item #include_once <@var{file}> -@itemx #include_once @var{file} +@item #include_once @var{file} Same as @code{#include}, except that, if the @var{file} has already been included, it will not be included again. @end table @@ -659,45 +619,21 @@ been included, it will not be included again. @cindex preprocessor, external @cindex external preprocessor The obtained material is then passed to @dfn{external -preprocessor}. By default, @command{pies} uses GNU @command{m4}@footnote{The -default preprocessor can be changed (or even disabled) when building the -package. When invoked with the @option{--help} option @command{pies} -reports, among others, the preprocessor it is configured to use and -the location of the preprocessor startup file. - -The use of alternative preprocessor can also be requested when -invoking @command{pies} by the @option{--preprocessor} option or even -disabled, using the @option{--no-preprocessor}.}. It is a powerful -macro processor, described in detail in -@ifnothtml -@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}. -@end ifnothtml -@ifhtml -@uref{http://www.gnu.org/software/m4/manual, GNU M4 manual}. -@end ifhtml +preprocessor}. By default, @command{pies} uses GNU @command{m4}. +This powerful macro processor is described +in @ref{Top, GNU M4 manual,, m4, GNU M4 macro processor}. For the rest of this subsection we assume the reader is sufficiently acquainted with the @command{m4} macro processor. -@anchor{pp-setup} -@flindex pp-setup - The external preprocessor is invoked with @option{-s} flag, instructing -it to include line synchronization information in its output. This -information is then used by the parser to display meaningful -diagnostic. An initial set of macro definitions is supplied by the -@file{pp-setup} file, located in -@file{@var{$prefix}/share/pies/@value{VERSION}/include} directory. - -The default @file{pp-setup} file renames all @command{m4} built-in -macro names so they all start with the prefix @samp{m4_}. This -is similar to GNU m4 @option{--prefix-builtin} options, but has an -advantage that it works with non-GNU @command{m4} implementations as -well. - -The include path for @command{m4} is set as described above. - -Additional preprocessor symbols may be defined and existing -definitions cancelled using the following command line options: + The external preprocessor is invoked with the following two flags: +@option{-s} flag, instructing it to include line synchronization +information in its output, and @option{-P}, which changes all +@command{m4} built-in macro names by prefixing them with @samp{m4_}. +@anchor{additional preprocessor options} + The following command line options are passed to @command{m4} +verbatim: + @table @option @xopindex{define, described} @cindex @option{-D} @@ -713,9 +649,31 @@ the @var{value} is not given. Undefine symbol @var{sym}. @end table -Finally, the @command{m4} output is passed to the configuration -parser. When parsing, the following constructs appearing at the -beginning of a line are handled specially: +@xopindex{include-directory, described} +The @option{--include-directory=@var{dir}} or @option{-I @var{dir}} +option causes the option @option{-I @var{dir}} to be appended to +the preprocessor command line. This option modifies the @command{m4} +include search path (@pxref{Search Path, GNU M4 manual,, Search Path, GNU M4 macro processor}). + +Finally, the following two options are appended: + +@table @option +@item -I @var{$prefix}/share/pies/include +@item -I @var{$prefix}/share/pies/@value{VERSION}/include +@end table + +@noindent +(where @var{$prefix} stands for installation prefix chosen when the +package was built. Normally it is @file{/usr}.) This step can be +disabled using the @option{--no-include} option. + +These provide the default search path. + +The name of the source file is appended to the command line, and the +constructed command is executed via @command{$SHELL -c} and its output +is then passed to the configuration parser. When parsing, the +following constructs appearing at the beginning of a line are handled +specially: @table @code @kwindex #line @@ -729,8 +687,96 @@ If the latter is absent, the remembered file name does not change. @item # @var{num} "@var{file}" This is a special form of @code{#line} statement, understood for compatibility with the @sc{c} preprocessor. + +@kwindex #warning +@item #warning "@var{text}" + Emits @var{text} as a warning. + +@kwindex #error +@item #error "@var{text}" + Emits @var{text} as an error message. Further parsing continues, +but will end with failure. + +@kwindex #abend +@item #abend "@var{text}" + Emits @var{text} as an error message and stops further processing +immediately. @end table +If @code{#error} or @code{#abend} is encountered, the effect is the same +as if syntax error has been detected. If it occurs at @command{pies} +startup, the program will terminate abnormally. If it occurs as +part of the reload sequence in a running instance of @command{pies}, +the configuration file will be rejected and old configuration will +remain in effect. + +@menu +* m4:: Using M4. +* custom preprocessor:: Using Custom Preprocessor. +@end menu + +@node m4 +@subsection Using M4 +@WRITEME + This subsection gives some tips on using the default preprocessor. + +@node custom preprocessor +@subsection Using Custom Preprocessor + The default preprocessor can be changed (or even disabled) at +compile time as well as on the runtime. When invoked with the +@option{--help} option @command{pies} reports, among others, the +preprocessor it is configured to use and the default include search +path. + + To disable preprocessing, use the @option{--no-preprocessor} command +line option. + + To change the default preprocessor at runtime, use the +@option{--preprocessor} option. Its argument is the initial +preprocessor command line. Depending on the @command{pies} command line, +it can be further modified by appending new options as described in +@ref{additional preprocessor options}. + + When selecting another preprocessor, please bear in mind that +@command{pies} assumes that the preprocessor program understands the +following three options: + +@table @option +@item -D @var{name}[=@var{value}] +Define the preprocessor symbol @var{name}. + +@item -I @var{dir} +Add the directory @var{dir} to the preprocessor search path for +include files. + +@item -U @var{name} +Undefine the preprocessor symbol @var{name}. +@end table + +@command{pies} never passes @option{-D} and @option{-U} options, +except as if these were passed to it in the command line. + +However, it normally adds one or more @option{-I} options to configure +the default search path. + +If the preprocessor of your choice doesn't support some or any of these +options, there are several possible solutions. + +@itemize @bullet +@item +If the preprocessor doesn't support @option{-D} and +@option{-U} options, don't pass them in the @command{pies} command +line. + +@item +If it does not support the @option{-I} option, run @command{pies} with +the @option{--no-include} option or create a wrapper script which will +consume all @option{-I} options without affecting the preprocessor +command line. +@end itemize + + For an example of using alternative preprocessor, @xref{xenv}. + @node Component Statement @section The @code{component} Statement @kwindex component @@ -793,7 +839,8 @@ components to terminate. @kindex shutdown @item shutdown These components are started as a part of program shutdown sequence, -after all regular components have terminated. +after all regular components have terminated. @xref{shutdown +sequence}, for a detailed discussion. @end table When run as init process (@pxref{Init Process}), the following @@ -957,6 +1004,14 @@ process instead. @end table @end deffn +@anchor{sigterm} +@deffn {Config: component} sigterm @var{sig} +Defines signal which should be sent to terminate this component. The +default is @code{SIGTERM}. The argument @var{sig} is either the name +of a signal defined in @file{/usr/include/signal.h}, or +@samp{SIG+@var{n}}, where @var{n} is signal number. +@end deffn + The following subsections describe the rest of @samp{component} substatements. @@ -1080,7 +1135,7 @@ the @code{env} statement. It has two variants: @dfn{compound} and @dfn{legacy}. The legacy one-line statement was used in @command{pies} versions up to 1.3 and is still retained for backward compatibility. It is described in @ref{env legacy syntax}. This subsection describes the -modern compount syntax. +modern compound syntax. The @code{env} statement can also be used in global context, in which case it modifies environment for the master @command{pies} program, @@ -1337,7 +1392,7 @@ them, there are two @dfn{flags} (@pxref{flags}) at your disposal: The @samp{shell} flag instructs @command{pies} to pass the command line specified by the the @code{command} statement as the argument to the @samp{/bin/sh -c} command (or another shell, if specified by the -@samp{program} statement). This naturaly causes all references to the +@samp{program} statement). This naturally causes all references to the environment variables to be expanded, as in shell. The overhead is that two processes are run instead of the one: first the shell and second the command itself, being run as its child. This overhead @@ -1472,10 +1527,30 @@ is the signal number, or as signal names from the following list: @samp{SIGWINCH}, @samp{SIGPOLL}, @samp{SIGIO}, @samp{SIGPWR}, @samp{SIGSYS}. - If the component exits with an exit code listed in @var{codes} -or is terminated on a signal listed in @var{codes}, -@command{pies} executes actions specified in that @samp{return-code} -block. The actions are executed in the order of their appearance below: + Each element in the list can be prefixed with @samp{!} to revert +the sense of matching. Thus, e.g. @samp{!0} would match any status +code except 0 and @samp{!SIGHUP} would match any signal other than +@code{SIGHUP}. If such a negated element yields true, the result is +saved and matching continues from the next element. If any subsequent +element evaluates to false, false is returned. Otherwise, the saved +return value (true) will be returned as the final result when the list +is exhausted. For example, the following list: + +@example +(!0, !SIGHUP, !SIGQUIT) +@end example + +@noindent +will match if the program exits with any status, except 0 or if it is +terminated with any signal, except @code{SIGHUP} and @code{SIGQUIT}. + + Empty list or @samp{*} in its place matches any exit status and +any signal number. + + If the component exits with an exit code or is terminated on a +signal that matches @var{codes}, @command{pies} executes actions +specified in that @samp{return-code} block. The actions are executed +in the order of their appearance below: @deffn {Config: return-code} exec @var{command} Execute the supplied external command. Prior to execution, all @@ -2002,7 +2077,7 @@ statement, a reference to its detailed description is provided. component @var{tag} @{ # @r{Component execution mode.} # @xref{Component Statement, mode}. - mode @samp{exec | wait | accept | inetd | nostartaccept | pass-fd | pass}; + mode @var{modename}; # @r{Full name of the program.} # @xref{Component Statement, program}. @@ -2126,8 +2201,8 @@ component @var{tag} @{ umask @var{number}; # @r{Set program environment.} - # @xref{Resources, env}. - env @var{assignments}; + # @xref{Environment}. + env @{ @dots{} @} # @r{Change to this directory before executing the component.} # @xref{Actions Before Startup, chdir}. @@ -2873,33 +2948,31 @@ description of this statement. Wait @var{number} of seconds for all components to shut down. Default is 5 seconds. +@anchor{shutdown sequence} @cindex shutdown sequence The normal shutdown sequence looks as follows: @enumerate 1 @item -Send all components the SIGTERM signal. -@item -Wait at most @code{shutdown-timeout} seconds for their termination. +Compute shutdown sequence that takes into account dependencies +between components, so as to ensure that dependent components +stop before their prerequisites. This sequence can be viewed +using the @option{--list-shutdown-sequence} option. -If any components are still running at the end of this interval: - -@enumerate a @item -Send all components the SIGKILL signal. +For each stage in the shutdown sequence, send the @dfn{termination signal} +to each component marked for that stage. By default, @code{SIGTERM} +is used, but it can be changed for each component using the @code{sigterm} +configuration statement (@pxref{sigterm}). Wait for the signalled +components to terminate. If any of them remain running after +@code{shutdown-timeout} seconds, send them the @code{SIGKILL} signal. @item -Wait at most @code{shutdown-timeout} seconds for their termination. -@end enumerate -@end enumerate - If any @code{shutdown} components are defined, start them and wait for their termination. If any components are left running after -@code{shutdown-timeout} seconds, terminate them using the above -procedure. - -This means that @command{pies} termination sequence can take -up to 2*@code{shutdown-timeout} seconds. +@code{shutdown-timeout} seconds, terminate them by sending the +@code{SIGKILL} signal. +@end enumerate @end deffn @node Pies Privileges @@ -3358,7 +3431,7 @@ Enable verbose diagnostics. @end table Before parsing, configuration file is preprocessed using external -command defined at buid time (normally @command{m4}). The following +command defined at build time (normally @command{m4}). The following options control this feature: @table @option @@ -3380,7 +3453,7 @@ the @var{value} is not given. @item --include-directory=@var{dir} @itemx -I @var{dir} Add directory @var{dir} to the list of directories to be scanned for -include files. @xref{include search path}. +preprocessor include files. @item --undefine=@var{sym} @itemx -U @var{sym} @@ -3958,11 +4031,11 @@ in this case @command{pies} uses its regular configuration file. @opindex --no-init When started with PID 1 from a docker container, @command{pies} -detects the fact automatically and switches to the entrypoint mode. -Up to version 1.4.90, automatical detection was not implemented, and -it was necessary to use the @option{--no-init} option to discern -between the @code{entrypoint} and @code{init} modes. This is no longer -the case. The option, however, is still retained. +tries to detect the fact automatically and switch to the entrypoint +mode. As of version @value{VERSION}, this detection might fail in +containers run under Kubernetes. For such cases, use the +@option{--no-init} option to inform @command{pies} that it should +run in @code{entrypoint} mode. The following @file{Dockerfile} fragment illustrates how to configure @command{pies} to be run from a container: @@ -3998,6 +4071,19 @@ undefined), use: command "syslogd -n -R $@{LOGHOST:-172.19.255.255@}"; @end example +Quite often a need arises to expand environment variables in other +parts of the configuration file and to conditionally exclude portions +of configuration, depending on whether a particular variable is set. +The following sections describe two approaches to solving this problem. + +@menu +* m4 environment:: Expanding Environment Variables in GNU m4. +* xenv:: Specialized Preprocessor Program. +@end menu + +@node m4 environment +@section Expanding Environment Variables in GNU m4 + Configuration preprocessing (@pxref{Preprocessor}) can be used to conditionally enable parts of the @file{pies.conf} file, depending on the value of an environment variable. The technique described @@ -4073,9 +4159,205 @@ component logger @{ @end deffn Place both macros in a single file and include it at the top of your -@file{pies.conf} using the @code{m4_include} command. Alternatively, -you can place them in the @file{pp-setup} file (@pxref{pp-setup}), -in which case they will be included automatically. +@file{pies.conf} using the @code{m4_include} command (@pxref{m4}). + +@node xenv +@section Using xenv +@prindex xenv + +Another way to expand environment variables in the configuration file +is to use @command{xenv}. @command{xenv} is a specialized +preprocessor that expands environment variables in its input. It is +also able to conditionally include parts of text depending on whether +the environment variable is defined. The program is described in +@uref{https://www.gnu.org.ua/software/xenv/}. + +To use @command{xenv} as preprocessor, start @command{pies} as +follows: + +@example +pies --foreground --stderr --preprocessor="xenv -s" +@end example + +The @option{-s} option instructs @command{xenv} to emit +@dfn{synchronization lines}, that inform @command{pies} about actual +location of configuration statements in case when the expansion adds +or removes portions of text spanning several lines. + +You can also combine the functionality of @command{m4} and +@command{xenv} by running + +@example +pies --foreground --stderr --preprocessor="xenv -s -m" +@end example + +In this case @command{xenv} will automatically feed its output to the +standard input of @command{m4}, started for this purpose. + +By default, @command{xenv} uses the shell syntax to expand the +variables. For example, in the following configuration file +fragment, @samp{$WORKDIR} will expand to the actual value of +the @env{WORKDIR} environment variable: + +@example +component @{ + chdir "$WORKDIR"; + ... +@} +@end example + +There are two ways to conditionally include portions of text. The first +one is to use the @samp{$@{X:+W@}} construct. For example: + +@example +component @{ + $@{WORKDIR:+chdir "$WORKDIR";@} + ... +@} +@end example + +Another way is to use the @command{xenv} @samp{$$ifset} (or +@samp{$$ifdef}) statement: + +@example +component @{ +$$ifset WORKDIR + chdir "$WORKDIR"; +$$endif + ... +@} +@end example + +The difference between @samp{$$ifset X} and @samp{$$ifdef X} is the +same as between @samp{$@{X:+W@}} and @samp{$@{X+W@}}, +i.e. @samp{$$ifset} tests whether the variable is set and not-null, +and @samp{$$ifdef} tests only whether it is set, no matter its value. + +@command{xenv} extends the shell syntax by providing a @dfn{ternary} +operator. The construct @samp{$@{X|A|B@}} expands to @samp{A} if +the variable @env{X} is set and to @samp{B} otherwise (as usual, +placing the colon before first @samp{|} checks if the variable is set +and not null). This allows for writing compact conditionals: + +@example +@group +component syslogd @{ + mode respawn; + command "/sbin/syslogd -n $@{LOGHOST:|-R $LOGHOST|-O /proc/1/fd/1@}"; +@} +@end group +@end example + +In this example @command{syslogd} is instructed to relay messages to +the IP address specified by the @env{LOGHOST} variable and to send +messages to the container stdout otherwise. + +Using shell indirection operator @samp{$} can be confusing in parts of +@command{pies} configuration file that deal with environment variables +by themselves. The common point of confusion is using @code{env} and +@code{command} statements when @code{shell} or @code{expandenv} flag +is set. For example: + +@example +@group +component X @{ + env @{ + set "HOME=/var/lib/nobody"; + @} + flags shell; + command "marb -C $HOME"; +@} +@end group +@end example + +Here, the intent is to pass @samp{/var/lib/nobody} as the command line +argument to @command{marb}. However, if @command{pies} was started +with @command{xenv} as preprocessor, the reference @samp{$HOME} will +be expanded by @command{xenv} at the early stage to whatever value the +@env{HOME} variable had at @command{pies} startup. Consequently, +when it comes to launching the @samp{X} component, the intended +expansion won't take place. + +There are three options to handle such cases: + +@enumerate 1 +@item Escape the @samp{$} + +Use backslash to suppress expansion by @command{xenv}: + +@example +@group +component X @{ + env @{ + set "HOME=/var/lib/nobody"; + @} + flags shell; + command "marb -C \$HOME"; +@} +@end group +@end example + +@item Use the @dfn{verbatim} operator + +This allows to reproduce the desired part of text verbatim. There are +two verbatim operators: inline operator @samp{$[...]} and block +operator @samp{$$verbatim ... $$end}. Examples: + +@example +@group +component X @{ + env @{ + set "HOME=/var/lib/nobody"; + @} + flags shell; + $[command "marb -C $HOME";] +@} +@end group +@end example + +or + +@example +@group +component X @{ + env @{ + set "HOME=/var/lib/nobody"; + @} + flags shell; +$$verbatim + command "marb -C $HOME"; +$$end +@} +@end group +@end example + +@item Change the indirection operator + +The indirection operator @samp{$} can be changed either globally, +by using the @option{-S} option, or locally by using the +@samp{$$sigil} statement. E.g.: + +@example +@group +$$sigil @@ +# From this point on, $ looses its special meaning in xenv. + +component X @{ + env @{ + set "HOME=/var/lib/nobody"; + @} + flags shell; + command "marb -C $HOME @@FILE"; +@} +@end group +@end example + +In the @code{command} line of this example, @code{@@FILE} will be +expanded by @command{xenv} when processing the configuration file, +and @code{$HOME} will be expanded by shell (to the value +@samp{/var/lib/nobody}, set by the @code{env} statement) when +@command{pies} will start the command. +@end enumerate @node Configuration Examples @chapter Configuration Examples @@ -4423,7 +4705,7 @@ equivalent to @command{pies --instance=inetd --syntax=inetd}. @item --include-directory=@var{dir} @itemx -I @var{dir} Add directory @var{dir} to the list of directories to be scanned for -include files. @xref{include search path}. +preprocessor include files. @opsummary{instance} @item --instance=@var{name} @@ -4438,6 +4720,12 @@ Define the name of the @command{pies} instance. @xref{instances}. Don't assume @dfn{init mode} (@pxref{Init Process}) if running with PID 1. @xref{Docker Entrypoint}. +@opsummary{list-shutdown-sequence} +@item --list-shutdown-sequence +List components in order of @dfn{shutdown sequence}. Each line lists +the sequence stage number and the component name. @xref{shutdown +sequence}, for a detailed discussion of its meaning. + @opsummary{no-preprocessor} @item --no-preprocessor Disable the use of the external preprocessor. diff --git a/doc/usr-acl.texi b/doc/usr-acl.texi index 61f307d..efa9830 100644 --- a/doc/usr-acl.texi +++ b/doc/usr-acl.texi @@ -1,5 +1,5 @@ @c This is part of the GNU Pies manual. -@c Copyright (C) 2009--2021 Sergey Poznyakoff +@c Copyright (C) 2009--2023 Sergey Poznyakoff @c This file is distributed under GFDL 1.3 or any later version @c published by the Free Software Foundation. |