diff options
-rw-r--r-- | NEWS | 15 | ||||
-rw-r--r-- | doc/pies.texi | 102 |
2 files changed, 91 insertions, 26 deletions
@@ -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 |