aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2019-05-28 08:18:57 +0300
committerSergey Poznyakoff <gray@gnu.org>2019-05-28 08:18:57 +0300
commitf8a25debf6e6422f291c69c5cb5d7732c78a4250 (patch)
treed4692b195ac8a7ee252f28bb634e401cf46e989b
parenta8d45eff28e7e186d0749e3e9cf980a23d93231e (diff)
downloadpies-f8a25debf6e6422f291c69c5cb5d7732c78a4250.tar.gz
pies-f8a25debf6e6422f291c69c5cb5d7732c78a4250.tar.bz2
Document startup and shutdown components
-rw-r--r--NEWS15
-rw-r--r--doc/pies.texi102
2 files changed, 91 insertions, 26 deletions
diff --git a/NEWS b/NEWS
index 6492aa5..0840055 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-GNU Pies NEWS -- history of user-visible changes. 2019-05-23
+GNU Pies NEWS -- history of user-visible changes. 2019-05-28
See the end of file for copying conditions.
Please send Pies bug reports to <bug-pies@gnu.org> or
@@ -12,6 +12,19 @@ The --no-init option instructs pies not to switch to init mode if its
PID is 1. Use this option if you run pies as a process manager in a
docker container.
+* New component modes: startup and shutdown
+
+Startup components are run right after pies startup. Any other
+components start running only after last startup component has terminated.
+
+Shutdown components are executed at program shutdown, after
+all other components have been terminated.
+
+Any number of startup or shutdwon components can be defined in the
+configuration file. Such multiple components are run simultaneously,
+unless required otherwise by their "prerequisites" and "dependents"
+statements.
+
* Improved cyclic dependency diagnostics
diff --git a/doc/pies.texi b/doc/pies.texi
index 48259da..012ac88 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -182,28 +182,26 @@ background, controlling their execution.
redirected to a file or to an arbitrary @command{syslog} channel.
The way of handling each component, and in particular the action to
-be taken upon its termination is determined by the component's side.
+be taken upon its termination is determined by the component's @dfn{mode}.
@anchor{respawn}
@cindex respawn components
A @dfn{respawn} component is restarted each time it terminates. If
-it terminates too often, @command{pies} puts it in sleep mode for
-certain time and logs that fact. This prevents badly configured
-components from taking too much resources and allows administrator to
-take measures in order to fix the situation. More specific action can
+it terminates too often, @command{pies} puts it to sleep for certain
+time and logs that fact. This prevents badly configured components
+from taking too much resources and allows administrator to take
+measures in order to fix the situation. More specific action can
be configured, depending on the exit code of the component.
@anchor{inetd-style}
@cindex inetd-style components
- @dfn{Inetd}-style components are not executed right after @command{pies}
-startup. Instead, @command{pies} opens a socket for each of them and
-listens for connections on these sockets. When a connection arrives,
-it decides what component the socket corresponds to, and invokes this
-component to handle the connection. In this case, the connection is
-bound to component's @samp{stdin} and @samp{stdout} streams. The
-@samp{stderr} stream can be redirected to a file or to syslog, as
-described above. This mode of operation is similar to that of
-the @command{inetd} utility.
+ An @dfn{inetd}-style components is not started. Instead, @command{pies}
+opens a socket associated with it and listens for connections on that
+socket. When a connection arrives, @command{pies} runs this component
+to handle it. The connection is bound to the component's @samp{stdin}
+and @samp{stdout} streams. The @samp{stderr} stream can be redirected
+to a file or to syslog, as described above. This mode of operation is
+similar to that of the @command{inetd} utility.
@anchor{meta1-style}
@cindex meta1-style components
@@ -215,23 +213,31 @@ suggests, this type is designed expressly as a support for
MeTA1@footnote{See @uref{http://www.meta1.org}} components, namely
@command{smtps}. This type can be regarded as a mixture of the above
two. For each meta1-style component @command{pies} opens a socket
-after start-up, and starts the component binary. Once the component
+and starts the component executable program. Once the program
is running, @command{pies} passes it the file descriptor of that
socket, through another preconfigured @acronym{UNIX}-style socket. Further
-handling of the socket is the responsibility of the component itself.
+handling of the socket is the responsibility of the program itself.
@anchor{accept-style}
@cindex accept-style components
- The last flavor are @dfn{accept-style} components, which are handled
-basically as @samp{inetd-style} ones, except that after binding to the
-socket @command{pies} immediately starts the component, without
-waiting for an actual connection.
+ An @dfn{accept} component is basically handled as @samp{inetd},
+except that after binding to the socket @command{pies} immediately
+starts the program, without waiting for actual connections.
+
+@cindex startup components
+@cindex shutdown components
+ Finally, two special component modes are available. @dfn{Startup}
+components are run right after @command{pies} startup, prior to
+running any other components. Their counterpart, @dfn{shutdown}
+components are run before program termination, after all other
+components have finished.
Any number of components of all types can be handled simultaneously.
Components are started in the order of their appearance in the
-configuration file and terminated in reverse order. The same
-ordering applies when starting or stopping component dependencies,
+configuration file and terminated in reverse order. This order can
+be modified by declaring component @dfn{prerequisites} or
+@dfn{dependents}. This is described in the following chapter.
As an exception, this order is reversed for the components read from
MeTA1 configuration files, either included by @code{include-meta1}
@@ -727,21 +733,39 @@ The following are the basic statements which are allowed within the
values for @var{mode}:
@table @asis
+@kindex exec
+@kindex respawn
@item exec
@itemx respawn
Define a @samp{respawn} component (@pxref{respawn}). This is
the default.
-
+
+@kindex inetd
+@kindex nostartaccept
@item inetd
@itemx nostartaccept
Define an @samp{inetd-style} component (@pxref{inetd-style}).
-
+
+@kindex pass
+@kindex pass-fd
@item pass
@itemx pass-fd
Define a @samp{meta1-style} component (@pxref{meta1-style}).
-
+
+@kindex accept
@item accept
Define a @samp{accept-style} component (@pxref{accept-style}).
+
+@kindex startup
+@item startup
+ The component is run right after startup. Prior to starting any
+other components, @command{pies} will wait for all @code{startup}
+components to terminate.
+
+@kindex shutdown
+@item shutdown
+ These components are started as a part of program shutdown sequence,
+after all regular components have terminated.
@end table
When run as init process (@pxref{Init Process}), the following
@@ -2510,6 +2534,34 @@ description of this statement.
@deffn {Config} shutdown-timeout @var{number};
Wait @var{number} of seconds for all components to shut down.
Default is 5 seconds.
+
+@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.
+
+If any components are still running at the end of this interval:
+
+@enumerate a
+@item
+Send all components the 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 5*@code{shutdown-timeout} seconds.
@end deffn
@node Pies Privileges

Return to:

Send suggestions and report system problems to the System administrator.