*****************************************************
``zdaemon`` process controller for Unix-based systems
*****************************************************
``zdaemon`` is a Unix (Unix, Linux, Mac OS X) Python program that wraps
commands to make them behave as proper daemons.
.. contents::
===============
Using zdaemon
===============
zdaemon provides a script, zdaemon, that can be used to run other
programs as POSIX (Unix) daemons. (Of course, it is only usable on
POSIX-complient systems.)
Using zdaemon requires specifying a number of options, which can be
given in a configuration file, or as command-line options. It also
accepts commands teling it what do do. The commands are:
start
Start a process as a daemon
stop
Stop a running daemon process
restart
Stop and then restart a program
status
Find out if the program is running
foreground or fg
Run a program
kill signal
Send a signal to the daemon process
reopen_transcript
Reopen the transcript log. See the discussion of the transcript
log below.
help command
Get help on a command
Commands can be given on a command line, or can be given using an
interactive interpreter.
Let's start with a simple example. We'll use command-line options to
run the echo command:
sh> ./zdaemon -p 'echo hello world' fg
echo hello world
hello world
Here we used the -p option to specify a program to run. We can
specify a program name and command-line options in the program
command. Note, however, that the command-line parsing is pretty
primitive. Quotes and spaces aren't handled correctly. Let's look at
a slightly more complex example. We'll run the sleep command as a
daemon :)
sh> ./zdaemon -p 'sleep 100' start
. .
daemon process started, pid=819
This ran the sleep daemon. We can check whether it ran with the
status command:
sh> ./zdaemon -p 'sleep 100' status
program running; pid=819
We can stop it with the stop command:
sh> ./zdaemon -p 'sleep 100' stop
. .
daemon process stopped
sh> ./zdaemon -p 'sleep 100' status
daemon manager not running
Failed: 3
Normally, we control zdaemon using a configuration file. Let's create
a typical configuration file::
<runner>
program sleep 100
</runner>
.. -> text
>>> with open('conf', 'w') as file:
... _ = file.write(text)
Now, we can run with the -C option to read the configuration file:
sh> ./zdaemon -Cconf start
. .
daemon process started, pid=1136
If we list the directory:
sh> ls
conf
zdaemon
zdsock
We'll see that a file, zdsock, was created. This is a unix-domain
socket used internally by ZDaemon. We'll normally want to control
where this goes.
sh> ./zdaemon -Cconf stop
. .
daemon process stopped
Here's an updated configuration::
<runner>
program sleep 100
socket-name /tmp/demo.zdsock
</runner>
.. -> text
>>> with open('conf', 'w') as file:
... _ = file.write(text.replace('/tmp', tmpdir))
Now, when we run zdaemon:
sh> ./zdaemon -Cconf start
. .
daemon process started, pid=1139
sh> ls
conf
zdaemon
.. test
>>> import os
>>> os.path.exists("/tmp/demo.zdsock".replace('/tmp', tmpdir))
True
The socket file is created in the given directory.
sh> ./zdaemon -Cconf stop
. .
daemon process stopped
In the example, we included a command-line argument in the program
option. We can also provide options on the command line::
<runner>
program sleep
socket-name /tmp/demo.zdsock
</runner>
.. -> text
>>> with open('conf', 'w') as file:
... _ = file.write(text.replace('/tmp', tmpdir))
Then we can pass the program argument on the command line:
sh> ./zdaemon -Cconf start 100
. .
daemon process started, pid=1149
sh> ./zdaemon -Cconf status
program running; pid=1149
sh> ./zdaemon -Cconf stop
. .
daemon process stopped
Environment Variables
=====================
Sometimes, it is necessary to set environment variables before running
a program. Perhaps the most common case for this is setting
LD_LIBRARY_PATH so that dynamically loaded libraries can be found.
::
<runner>
program env
socket-name /tmp/demo.zdsock
</runner>
<environment>
LIBRARY_PATH /home/foo/lib
HOME /home/foo
</environment>
.. -> text
>>> with open('conf', 'w') as file:
... _ = file.write(text.replace('/tmp', tmpdir))
Now, when we run the command, we'll see out environment settings reflected:
sh> ./zdaemon -Cconf fg
env
USER=jim
HOME=/home/foo
LOGNAME=jim
USERNAME=jim
TERM=dumb
PATH=/home/jim/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin
EMACS=t
LANG=en_US.UTF-8
SHELL=/bin/bash
EDITOR=emacs
LIBRARY_PATH=/home/foo/lib
Transcript log
==============
When zdaemon run a program in daemon mode, it disconnects the
program's standard input, standard output, and standard error from the
controlling terminal. It can optionally redirect the output to
standard error and standard output to a file. This is done with the
transcript option. This is, of course, useful for logging output from
long-running applications.
Let's look at an example. We'll have a long-running process that
simple tails a data file:
>>> f = open('data', 'w', 1)
>>> import os
>>> _ = f.write('rec 1\n'); f.flush(); os.fsync(f.fileno())
Now, here's out zdaemon configuration::
<runner>
program tail -f data
transcript log
</runner>
.. -> text
>>> with open('conf', 'w') as file:
... _ = file.write(text)
Now we'll start:
sh> ./zdaemon -Cconf start
. .
daemon process started, pid=7963
.. Wait a little bit to make sure tail has a chance to work
>>> import time
>>> time.sleep(0.1)
After waiting a bit, if we look at the log file, it contains the tail output:
>>> with open('log') as file:
... file.read()
'rec 1\n'
We can rotate the transcript log by renaming it and telling zdaemon to
reopen it:
>>> import os
>>> os.rename('log', 'log.1')
If we generate more output:
>>> _ = f.write('rec 2\n'); f.flush(); os.fsync(f.fileno())
.. Wait a little bit to make sure tail has a chance to work
>>> time.sleep(1)
The output will appear in the old file, because zdaemon still has it
open:
>>> with open('log.1') as file:
... file.read()
'rec 1\nrec 2\n'
Now, if we tell zdaemon to reopen the file:
sh> ./zdaemon -Cconf reopen_transcript
and generate some output:
>>> _ = f.write('rec 3\n'); f.flush(); os.fsync(f.fileno())
.. Wait a little bit to make sure tail has a chance to work
>>> time.sleep(1)
the output will show up in the new file, not the old:
>>> with open('log') as file:
... file.read()
'rec 3\n'
>>> with open('log.1') as file:
... file.read()
'rec 1\nrec 2\n'
Close files and clean up:
>>> f.close()
sh> ./zdaemon -Cconf stop
. .
daemon process stopped
Start test program and timeout
==============================
Normally, zdaemon considers a process to have started when the process
itself has been created. A process may take a while before it is
truly up and running. For example, a database server or a web server
may take time before they're ready to accept requests.
You can optionally supply a test program, via the ``start-test-program``
configuration option, that is called repeatedly until it returns a 0
exit status or until a time limit, ``start-timeout``, has been reached.
Reference Documentation
=======================
The following options are available for use in the runner section of
configuration files and as command-line options.
program
Command-line option: -p or --program
This option gives the command used to start the subprocess
managed by zdaemon. This is currently a simple list of
whitespace-delimited words. The first word is the program
file, subsequent words are its command line arguments. If the
program file contains no slashes, it is searched using $PATH.
(Note that there is no way to to include whitespace in the program
file or an argument, and under certain circumstances other
shell metacharacters are also a problem.)
socket-name
Command-line option: -s or --socket-name.
The pathname of the Unix domain socket used for communication
between the zdaemon command-line tool and a daemon-management
process. The default is relative to the current directory in
which zdaemon is started. You want to specify
an absolute pathname here.
This defaults to "zdsock", which is created in the directory
in which zdrun is started.
daemon
Command-line option: -d or --daemon.
If this option is true, zdaemon runs in the background as a
true daemon. It forks a child process which becomes the
subprocess manager, while the parent exits (making the shell
that started it believe it is done). The child process also
does the following:
- if the directory option is set, change into that directory
- redirect stdin, stdout and stderr to /dev/null
- call setsid() so it becomes a session leader
- call umask() with specified value
The default for this option is on by default. The
command-line option therefore has no effect. To disable
daemon mode, you must use a configuration file::
<runner>
program sleep 1
daemon off
</runner>
directory
Command-line option: -z or --directory.
If the daemon option is true (default), this option can
specify a directory into which zdrun.py changes as part of the
"daemonizing". If the daemon option is false, this option is
ignored.
backoff-limit
Command-line option: -b or --backoff-limit.
When the subprocess crashes, zdaemon inserts a one-second
delay before it restarts it. When the subprocess crashes
again right away, the delay is incremented by one second, and
so on. What happens when the delay has reached the value of
backoff-limit (in seconds), depends on the value of the
forever option. If forever is false, zdaemon gives up at
this point, and exits. An always-crashing subprocess will
have been restarted exactly backoff-limit times in this case.
If forever is true, zdaemon continues to attempt to restart
the process, keeping the delay at backoff-limit seconds.
If the subprocess stays up for more than backoff-limit
seconds, the delay is reset to 1 second.
This defaults to 10.
forever
Command-line option: -f or --forever.
If this option is true, zdaemon will keep restarting a
crashing subprocess forever. If it is false, it will give up
after backoff-limit crashes in a row. See the description of
backoff-limit for details.
This is disabled by default.
exit-codes
Command-line option: -x or --exit-codes.
This defaults to 0,2.
If the subprocess exits with an exit status that is equal to
one of the integers in this list, zdaemon will not restart
it. The default list requires some explanation. Exit status
0 is considered a willful successful exit; the ZEO and Zope
server processes use this exit status when they want to stop
without being restarted. (Including in response to a
SIGTERM.) Exit status 2 is typically issued for command line
syntax errors; in this case, restarting the program will not
help!
NOTE: this mechanism overrides the backoff-limit and forever
options; i.e. even if forever is true, a subprocess exit
status code in this list makes zdaemon give up. To disable
this, change the value to an empty list.
start-test-program
A command that tests whether the program is up and running.
The command should exit with a zero exit statis if the program
is running and with a non-zero status otherwise.
start-timeout
Command-line option: -T or --start-timeout.
If the program takes more than ``start-timeout`` seconds to
start, then an error is printed and the control script will
exit with a non-zero exit status.
stop-timeout
This defaults to 300 seconds (5 minutes).
When a stop command is issued, a SIGTERM signal is sent to the
process. zdaemon waits for stop-timeout seconds for the
process to gracefully exit. If the process doesn't exit in
that time, a SIGKILL signal is sent.
user
Command-line option: -u or --user.
When zdaemon is started by root, this option specifies the
user as who the the zdaemon process (and hence the daemon
subprocess) will run. This can be a user name or a numeric
user id. Both the user and the group are set from the
corresponding password entry, using setuid() and setgid().
This is done before zdaemon does anything else besides
parsing its command line arguments.
NOTE: when zdaemon is not started by root, specifying this
option is an error. (XXX This may be a mistake.)
XXX The zdaemon event log file may be opened *before*
setuid() is called. Is this good or bad?
umask
Command-line option: -m or --umask.
When daemon mode is used, this option specifies the octal umask
of the subprocess.
default-to-interactive
If this option is true, zdaemon enters interactive mode
when it is invoked without a positional command argument. If
it is false, you must use the -i or --interactive command line
option to zdaemon to enter interactive mode.
This is enabled by default.
logfile
Command-line option: -l or --logfile.
This option specifies a log file that is the default target of
the "logtail" zdaemon command.
NOTE: This is NOT the log file to which zdaemon writes its
logging messages! That log file is specified by the
<eventlog> section described below.
transcript
Command-line option: -t or --transcript.
The name of a file in which a transcript of all output from
the command being run will be written to when daemonized.
If not specified, output from the command will be discarded.
This only takes effect when the "daemon" option is enabled.
prompt
The prompt shown by the controller program. The default must
be provided by the application.
(Note that a few other options are available to support old
configuration files, but aren't needed any more and can generally be
ignored.)
In addition to the runner section, you can use an eventlog section
that specified one or more logfile subsections::
<eventlog>
<logfile>
path /var/log/foo/foo.log
</logfile>
<logfile>
path STDOUT
</logfile>
</eventlog>
In this example, log output is sent to a file and to standard out.
Log output from zdaemon usually isn't very interesting but can be
handy for debugging.
==========
Change log
==========
5.1 (2024-05-03)
================
- Add support for Python 3.12.
- Fix ``SIGCHLD``/``wait`` raise condition associated with the
``start-test-program`` option.
For details see `#33 <https://github.com/zopefoundation/zdaemon/pull/33>`_.
5.0 (2023-05-24)
================
- Drop support for Python 2.7, 3.5, 3.6.
4.4 (2022-12-02)
================
- Add support for Python 3.8, 3.9, 3.10, 3.11.
- Drop support for Python 3.4.
- Drop support for ``python setup.py test`` to run the tests. (#23)
- Drop support for installing this package without having ``setuptools``.
4.3 (2018-10-30)
================
- Add support for Python 3.6 and 3.7.
- Drop support for Python 3.3.
4.2.0 (2016-12-07)
==================
- Add support for Python 3.5.
- Drop support for Python 2.6 and 3.2.
4.1.0 (2015-04-16)
==================
- Add ``--version`` command line option (fixes
https://github.com/zopefoundation/zdaemon/issues/4).
- ``kill`` now accepts signal names, not just numbers
(https://github.com/zopefoundation/zdaemon/issues/11).
- Restore ``logreopen`` as an alias for ``kill USR2`` (removed in version
3.0.0 due to lack of tests):
https://github.com/zopefoundation/zdaemon/issues/10.
- Make ``logreopen`` also reopen the transcript log:
https://github.com/zopefoundation/zdaemon/issues/9.
- Reopen event log on ``logreopen`` or ``reopen_transcript``:
https://github.com/zopefoundation/zdaemon/issues/8.
- Help message for ``reopen_transcript``
(https://github.com/zopefoundation/zdaemon/issues/5).
- Fix race condition where ``stop`` would be ignored if the daemon
manager was waiting before respawning a crashed program.
https://github.com/zopefoundation/zdaemon/issues/13.
- Partially fix delayed deadlock when the transcript file runs into a
full disk (https://github.com/zopefoundation/zdaemon/issues/1).
- Fix test suite leaving stale processes behind
(https://github.com/zopefoundation/zdaemon/issues/7).
4.0.1 (2014-12-26)
==================
- Add support for PyPy. (PyPy3 is pending release of a fix for:
https://bitbucket.org/pypy/pypy/issue/1946)
- Add support for Python 3.4.
- Add ``-t/--transcript`` command line option.
- zdaemon can now be invoked as a module as in ``python -m zdaemon ...``
4.0.0 (2013-05-10)
==================
- Add support for Python 3.2.
4.0.0a1 (2013-02-15)
====================
- Add tox support and MANIFEST.in for proper releasing.
- Add Python 3.3 support.
- Drop Python 2.4 and 2.5 support.
3.0.5 (2012-11-27)
==================
- Fixed: the status command didn't return a non-zero exit status when
the program wasn't running. This made it impossible for other
software (e.g. Puppet) to tell if a process was running.
3.0.4 (2012-07-30)
==================
- Fixed: The start command exited with a zero exit status even when
the program being started failed to start (or exited imediately).
3.0.3 (2012-07-10)
==================
- Fixed: programs started with zdaemon couldn't, themselves, invoke
zdaemon.
3.0.2 (2012-07-10)
==================
Fail :(
3.0.1 (2012-06-08)
==================
- Fixed:
The change in 2.0.6 to set a user's supplemental groups broke common
configurations in which the effective user was set via ``su`` or
``sudo -u`` prior to invoking zdaemon.
Now, zdaemon doesn't set groups or the effective user if the
effective user is already set to the configured user.
3.0.0 (2012-06-08)
==================
- Added an option, ``start-test-program`` to supply a test command to
test whether the program managed by zdaemon is up and operational,
rather than just running. When starting a program, the start
command doesn't return until the test passes. You could, for
example, use this to wait until a web server is actually accepting
connections.
- Added a ``start-timeout`` option to error if a program takes too long to
start. This is especially useful in combination with the
``start-test-program`` option.
- Added an option, stop-timeout, to control how long to wait
for a graceful shutdown.
Previously, this was controlled by backoff-limit, which didn't make
much sense.
- Several undocumented, untested, and presumably unused features were removed.
2.0.6 (2012-06-07)
==================
- Fixed: When the ``user`` option was used to run as a particular
user, supplemental groups weren't set to the user's supplemental
groups.
2.0.5 (2012-06-07)
==================
(Accidental release. Please ignore.)
2.0.4 (2009-04-20)
==================
- Version 2.0.3 broke support for relative paths to the socket (``-s``
option and ``socket-name`` parameter), now relative paths work again
as in version 2.0.2.
- Fixed change log format, made table of contents nicer.
- Fixed author's email address.
- Removed zpkg stuff.
2.0.3 (2009-04-11)
==================
- Added support to bootstrap on Jython.
- If the run directory does not exist it will be created. This allow to use
`/var/run/mydaemon` as run directory when /var/run is a tmpfs (LP #318118).
Bugs Fixed
----------
- No longer uses a hard-coded file name (/tmp/demo.zdsock) in unit tests.
This lets you run the tests on Python 2.4 and 2.5 simultaneously without
spurious errors.
- make -h work again for both runner and control scripts.
Help is now taken from the __doc__ of the options class users by
the zdaemon script being run.
2.0.2 (2008-04-05)
==================
Bugs Fixed
----------
- Fixed backwards incompatible change in handling of environment option.
2.0.1 (2007-10-31)
==================
Bugs Fixed
----------
- Fixed test renormalizer that did not work in certain cases where the
environment was complex.
2.0.0 (2007-07-19)
==================
- Final release for 2.0.0.
2.0a6 (2007-01-11)
==================
Bugs Fixed
----------
- When the user option was used, it only affected running the daemon.
2.0a3, 2.0a4, 2.0a5 (2007-01-10)
================================
Bugs Fixed
----------
- The new (2.0) mechanism used by zdaemon to start the daemon manager
broke some applications that extended zdaemon.
- Added extra checks to deal with programs that extend zdaemon
and copy the schema and thus don't see updates to the ZConfig schema.
2.0a2 (2007-01-10)
==================
New Features
------------
- Added support for setting environment variables in the configuration
file. This is useful when zdaemon is used to run programs that need
environment variables set (e.g. LD_LIBRARY_PATH).
- Added a command to rotate the transcript log.
2.0a1 (2006-12-21)
==================
Bugs Fixed
----------
- In non-daemon mode, start hung, producing annoying dots
when the program exited.
- The start command hung producing annoying dots if the daemon failed
to start.
- foreground and start had different semantics because one used
os.system and another used os.spawn
New Features
------------
- Documentation
- Command-line arguments can now be supplied to the start and
foreground (fg) commands
- zdctl now invokes itself to run zdrun. This means that it's
no-longer necessary to generate a separate zdrun script. This
especially when the magic techniques to find and run zdrun using
directory sniffing fail to set the path correctly.
- The daemon mode is now enabled by default. To get non-daemon mode,
you have to use a configuration file and set daemon to off
there. The old -d option is kept for backward compatibility, but is
a no-op.
1.4a1 (2005-11-21)
==================
- Fixed a bug in the distribution setup file.
1.4a1 (2005-11-05)
==================
- First semi-formal release.
After some unknown release(???)
===============================
- Made 'zdaemon.zdoptions' not fail for --help when __main__.__doc__
is None.
After 1.1
=========
- Updated test 'testRunIgnoresParentSignals':
o Use 'mkdtemp' to create a temporary directory to hold the test socket
rather than creating the test socket in the test directory.
Hopefully this will be more robust. Sometimes the test directory
has a path so long that the test socket can't be created.
o Changed management of 'donothing.sh'. This script is now created by
the test in the temporarily directory with the necessary
permissions. This is to avoids possible mangling of permissions
leading to spurious test failures. It also avoids management of a
file in the source tree, which is a bonus.
- Rearranged source tree to conform to more usual zpkg-based layout:
o Python package lives under 'src'.
o Dependencies added to 'src' as 'svn:externals'.
o Unit tests can now be run from a checkout.
- Made umask-based test failures due to running as root emit a more
forceful warning.
1.1 (2005-06-09)
================
- SVN tag: svn://svn.zope.org/repos/main/zdaemon/tags/zdaemon-1.1
- Tagged to make better 'svn:externals' linkage possible.
To-Dos
======
More docs:
- Document/demonstrate some important features, such as:
- working directory
Bugs:
- help command
Raw data
{
"_id": null,
"home_page": "https://github.com/zopefoundation/zdaemon",
"name": "zdaemon",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Zope Foundation and Contributors",
"author_email": "zope-dev@zope.dev",
"download_url": "https://files.pythonhosted.org/packages/1b/8f/d2e2748ab114b577b10889873cb370f7faf3ace5ce9b9b36a450452a2bd5/zdaemon-5.1.tar.gz",
"platform": null,
"description": "*****************************************************\n``zdaemon`` process controller for Unix-based systems\n*****************************************************\n\n``zdaemon`` is a Unix (Unix, Linux, Mac OS X) Python program that wraps\ncommands to make them behave as proper daemons.\n\n.. contents::\n\n===============\n Using zdaemon\n===============\n\nzdaemon provides a script, zdaemon, that can be used to run other\nprograms as POSIX (Unix) daemons. (Of course, it is only usable on\nPOSIX-complient systems.)\n\nUsing zdaemon requires specifying a number of options, which can be\ngiven in a configuration file, or as command-line options. It also\naccepts commands teling it what do do. The commands are:\n\nstart\n Start a process as a daemon\n\nstop\n Stop a running daemon process\n\nrestart\n Stop and then restart a program\n\nstatus\n Find out if the program is running\n\nforeground or fg\n Run a program\n\nkill signal\n Send a signal to the daemon process\n\nreopen_transcript\n Reopen the transcript log. See the discussion of the transcript\n log below.\n\nhelp command\n Get help on a command\n\n\nCommands can be given on a command line, or can be given using an\ninteractive interpreter.\n\nLet's start with a simple example. We'll use command-line options to\nrun the echo command:\n\n sh> ./zdaemon -p 'echo hello world' fg\n echo hello world\n hello world\n\n\nHere we used the -p option to specify a program to run. We can\nspecify a program name and command-line options in the program\ncommand. Note, however, that the command-line parsing is pretty\nprimitive. Quotes and spaces aren't handled correctly. Let's look at\na slightly more complex example. We'll run the sleep command as a\ndaemon :)\n\n sh> ./zdaemon -p 'sleep 100' start\n . .\n daemon process started, pid=819\n\nThis ran the sleep daemon. We can check whether it ran with the\nstatus command:\n\n sh> ./zdaemon -p 'sleep 100' status\n program running; pid=819\n\nWe can stop it with the stop command:\n\n sh> ./zdaemon -p 'sleep 100' stop\n . .\n daemon process stopped\n\n sh> ./zdaemon -p 'sleep 100' status\n daemon manager not running\n Failed: 3\n\nNormally, we control zdaemon using a configuration file. Let's create\na typical configuration file::\n\n <runner>\n program sleep 100\n </runner>\n\n.. -> text\n\n >>> with open('conf', 'w') as file:\n ... _ = file.write(text)\n\nNow, we can run with the -C option to read the configuration file:\n\n sh> ./zdaemon -Cconf start\n . .\n daemon process started, pid=1136\n\nIf we list the directory:\n\n sh> ls\n conf\n zdaemon\n zdsock\n\nWe'll see that a file, zdsock, was created. This is a unix-domain\nsocket used internally by ZDaemon. We'll normally want to control\nwhere this goes.\n\n sh> ./zdaemon -Cconf stop\n . .\n daemon process stopped\n\nHere's an updated configuration::\n\n <runner>\n program sleep 100\n socket-name /tmp/demo.zdsock\n </runner>\n\n.. -> text\n\n >>> with open('conf', 'w') as file:\n ... _ = file.write(text.replace('/tmp', tmpdir))\n\nNow, when we run zdaemon:\n\n sh> ./zdaemon -Cconf start\n . .\n daemon process started, pid=1139\n\n sh> ls\n conf\n zdaemon\n\n.. test\n\n >>> import os\n >>> os.path.exists(\"/tmp/demo.zdsock\".replace('/tmp', tmpdir))\n True\n\nThe socket file is created in the given directory.\n\n sh> ./zdaemon -Cconf stop\n . .\n daemon process stopped\n\nIn the example, we included a command-line argument in the program\noption. We can also provide options on the command line::\n\n <runner>\n program sleep\n socket-name /tmp/demo.zdsock\n </runner>\n\n.. -> text\n\n >>> with open('conf', 'w') as file:\n ... _ = file.write(text.replace('/tmp', tmpdir))\n\nThen we can pass the program argument on the command line:\n\n sh> ./zdaemon -Cconf start 100\n . .\n daemon process started, pid=1149\n\n sh> ./zdaemon -Cconf status\n program running; pid=1149\n\n sh> ./zdaemon -Cconf stop\n . .\n daemon process stopped\n\nEnvironment Variables\n=====================\n\nSometimes, it is necessary to set environment variables before running\na program. Perhaps the most common case for this is setting\nLD_LIBRARY_PATH so that dynamically loaded libraries can be found.\n\n::\n\n <runner>\n program env\n socket-name /tmp/demo.zdsock\n </runner>\n <environment>\n LIBRARY_PATH /home/foo/lib\n HOME /home/foo\n </environment>\n\n.. -> text\n\n >>> with open('conf', 'w') as file:\n ... _ = file.write(text.replace('/tmp', tmpdir))\n\nNow, when we run the command, we'll see out environment settings reflected:\n\n sh> ./zdaemon -Cconf fg\n env\n USER=jim\n HOME=/home/foo\n LOGNAME=jim\n USERNAME=jim\n TERM=dumb\n PATH=/home/jim/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin\n EMACS=t\n LANG=en_US.UTF-8\n SHELL=/bin/bash\n EDITOR=emacs\n LIBRARY_PATH=/home/foo/lib\n\nTranscript log\n==============\n\nWhen zdaemon run a program in daemon mode, it disconnects the\nprogram's standard input, standard output, and standard error from the\ncontrolling terminal. It can optionally redirect the output to\nstandard error and standard output to a file. This is done with the\ntranscript option. This is, of course, useful for logging output from\nlong-running applications.\n\nLet's look at an example. We'll have a long-running process that\nsimple tails a data file:\n\n >>> f = open('data', 'w', 1)\n >>> import os\n >>> _ = f.write('rec 1\\n'); f.flush(); os.fsync(f.fileno())\n\nNow, here's out zdaemon configuration::\n\n <runner>\n program tail -f data\n transcript log\n </runner>\n\n.. -> text\n\n >>> with open('conf', 'w') as file:\n ... _ = file.write(text)\n\nNow we'll start:\n\n sh> ./zdaemon -Cconf start\n . .\n daemon process started, pid=7963\n\n.. Wait a little bit to make sure tail has a chance to work\n\n >>> import time\n >>> time.sleep(0.1)\n\nAfter waiting a bit, if we look at the log file, it contains the tail output:\n\n >>> with open('log') as file:\n ... file.read()\n 'rec 1\\n'\n\nWe can rotate the transcript log by renaming it and telling zdaemon to\nreopen it:\n\n >>> import os\n >>> os.rename('log', 'log.1')\n\nIf we generate more output:\n\n >>> _ = f.write('rec 2\\n'); f.flush(); os.fsync(f.fileno())\n\n.. Wait a little bit to make sure tail has a chance to work\n\n >>> time.sleep(1)\n\nThe output will appear in the old file, because zdaemon still has it\nopen:\n\n >>> with open('log.1') as file:\n ... file.read()\n 'rec 1\\nrec 2\\n'\n\nNow, if we tell zdaemon to reopen the file:\n\n sh> ./zdaemon -Cconf reopen_transcript\n\nand generate some output:\n\n >>> _ = f.write('rec 3\\n'); f.flush(); os.fsync(f.fileno())\n\n.. Wait a little bit to make sure tail has a chance to work\n\n >>> time.sleep(1)\n\nthe output will show up in the new file, not the old:\n\n >>> with open('log') as file:\n ... file.read()\n 'rec 3\\n'\n\n >>> with open('log.1') as file:\n ... file.read()\n 'rec 1\\nrec 2\\n'\n\nClose files and clean up:\n\n >>> f.close()\n\n sh> ./zdaemon -Cconf stop\n . .\n daemon process stopped\n\n\nStart test program and timeout\n==============================\n\nNormally, zdaemon considers a process to have started when the process\nitself has been created. A process may take a while before it is\ntruly up and running. For example, a database server or a web server\nmay take time before they're ready to accept requests.\n\nYou can optionally supply a test program, via the ``start-test-program``\nconfiguration option, that is called repeatedly until it returns a 0\nexit status or until a time limit, ``start-timeout``, has been reached.\n\nReference Documentation\n=======================\n\nThe following options are available for use in the runner section of\nconfiguration files and as command-line options.\n\nprogram\n Command-line option: -p or --program\n\n This option gives the command used to start the subprocess\n managed by zdaemon. This is currently a simple list of\n whitespace-delimited words. The first word is the program\n file, subsequent words are its command line arguments. If the\n program file contains no slashes, it is searched using $PATH.\n (Note that there is no way to to include whitespace in the program\n file or an argument, and under certain circumstances other\n shell metacharacters are also a problem.)\n\nsocket-name\n Command-line option: -s or --socket-name.\n\n The pathname of the Unix domain socket used for communication\n between the zdaemon command-line tool and a daemon-management\n process. The default is relative to the current directory in\n which zdaemon is started. You want to specify\n an absolute pathname here.\n\n This defaults to \"zdsock\", which is created in the directory\n in which zdrun is started.\n\ndaemon\n Command-line option: -d or --daemon.\n\n If this option is true, zdaemon runs in the background as a\n true daemon. It forks a child process which becomes the\n subprocess manager, while the parent exits (making the shell\n that started it believe it is done). The child process also\n does the following:\n\n - if the directory option is set, change into that directory\n\n - redirect stdin, stdout and stderr to /dev/null\n\n - call setsid() so it becomes a session leader\n\n - call umask() with specified value\n\n The default for this option is on by default. The\n command-line option therefore has no effect. To disable\n daemon mode, you must use a configuration file::\n\n <runner>\n program sleep 1\n daemon off\n </runner>\n\ndirectory\n Command-line option: -z or --directory.\n\n If the daemon option is true (default), this option can\n specify a directory into which zdrun.py changes as part of the\n \"daemonizing\". If the daemon option is false, this option is\n ignored.\n\nbackoff-limit\n Command-line option: -b or --backoff-limit.\n\n When the subprocess crashes, zdaemon inserts a one-second\n delay before it restarts it. When the subprocess crashes\n again right away, the delay is incremented by one second, and\n so on. What happens when the delay has reached the value of\n backoff-limit (in seconds), depends on the value of the\n forever option. If forever is false, zdaemon gives up at\n this point, and exits. An always-crashing subprocess will\n have been restarted exactly backoff-limit times in this case.\n If forever is true, zdaemon continues to attempt to restart\n the process, keeping the delay at backoff-limit seconds.\n\n If the subprocess stays up for more than backoff-limit\n seconds, the delay is reset to 1 second.\n\n This defaults to 10.\n\nforever\n Command-line option: -f or --forever.\n\n If this option is true, zdaemon will keep restarting a\n crashing subprocess forever. If it is false, it will give up\n after backoff-limit crashes in a row. See the description of\n backoff-limit for details.\n\n This is disabled by default.\n\nexit-codes\n Command-line option: -x or --exit-codes.\n\n This defaults to 0,2.\n\n If the subprocess exits with an exit status that is equal to\n one of the integers in this list, zdaemon will not restart\n it. The default list requires some explanation. Exit status\n 0 is considered a willful successful exit; the ZEO and Zope\n server processes use this exit status when they want to stop\n without being restarted. (Including in response to a\n SIGTERM.) Exit status 2 is typically issued for command line\n syntax errors; in this case, restarting the program will not\n help!\n\n NOTE: this mechanism overrides the backoff-limit and forever\n options; i.e. even if forever is true, a subprocess exit\n status code in this list makes zdaemon give up. To disable\n this, change the value to an empty list.\n\nstart-test-program\n A command that tests whether the program is up and running.\n The command should exit with a zero exit statis if the program\n is running and with a non-zero status otherwise.\n\nstart-timeout\n Command-line option: -T or --start-timeout.\n\n If the program takes more than ``start-timeout`` seconds to\n start, then an error is printed and the control script will\n exit with a non-zero exit status.\n\nstop-timeout\n This defaults to 300 seconds (5 minutes).\n\n When a stop command is issued, a SIGTERM signal is sent to the\n process. zdaemon waits for stop-timeout seconds for the\n process to gracefully exit. If the process doesn't exit in\n that time, a SIGKILL signal is sent.\n\nuser\n Command-line option: -u or --user.\n\n When zdaemon is started by root, this option specifies the\n user as who the the zdaemon process (and hence the daemon\n subprocess) will run. This can be a user name or a numeric\n user id. Both the user and the group are set from the\n corresponding password entry, using setuid() and setgid().\n This is done before zdaemon does anything else besides\n parsing its command line arguments.\n\n NOTE: when zdaemon is not started by root, specifying this\n option is an error. (XXX This may be a mistake.)\n\n XXX The zdaemon event log file may be opened *before*\n setuid() is called. Is this good or bad?\n\numask\n Command-line option: -m or --umask.\n\n When daemon mode is used, this option specifies the octal umask\n of the subprocess.\n\ndefault-to-interactive\n If this option is true, zdaemon enters interactive mode\n when it is invoked without a positional command argument. If\n it is false, you must use the -i or --interactive command line\n option to zdaemon to enter interactive mode.\n\n This is enabled by default.\n\nlogfile\n Command-line option: -l or --logfile.\n\n This option specifies a log file that is the default target of\n the \"logtail\" zdaemon command.\n\n NOTE: This is NOT the log file to which zdaemon writes its\n logging messages! That log file is specified by the\n <eventlog> section described below.\n\ntranscript\n Command-line option: -t or --transcript.\n\n The name of a file in which a transcript of all output from\n the command being run will be written to when daemonized.\n\n If not specified, output from the command will be discarded.\n\n This only takes effect when the \"daemon\" option is enabled.\n\nprompt\n The prompt shown by the controller program. The default must\n be provided by the application.\n\n(Note that a few other options are available to support old\nconfiguration files, but aren't needed any more and can generally be\nignored.)\n\nIn addition to the runner section, you can use an eventlog section\nthat specified one or more logfile subsections::\n\n <eventlog>\n <logfile>\n path /var/log/foo/foo.log\n </logfile>\n\n <logfile>\n path STDOUT\n </logfile>\n </eventlog>\n\nIn this example, log output is sent to a file and to standard out.\nLog output from zdaemon usually isn't very interesting but can be\nhandy for debugging.\n\n==========\nChange log\n==========\n\n5.1 (2024-05-03)\n================\n\n- Add support for Python 3.12.\n\n- Fix ``SIGCHLD``/``wait`` raise condition associated with the\n ``start-test-program`` option.\n For details see `#33 <https://github.com/zopefoundation/zdaemon/pull/33>`_.\n\n\n5.0 (2023-05-24)\n================\n\n- Drop support for Python 2.7, 3.5, 3.6.\n\n\n4.4 (2022-12-02)\n================\n\n- Add support for Python 3.8, 3.9, 3.10, 3.11.\n\n- Drop support for Python 3.4.\n\n- Drop support for ``python setup.py test`` to run the tests. (#23)\n\n- Drop support for installing this package without having ``setuptools``.\n\n\n4.3 (2018-10-30)\n================\n\n- Add support for Python 3.6 and 3.7.\n\n- Drop support for Python 3.3.\n\n\n4.2.0 (2016-12-07)\n==================\n\n- Add support for Python 3.5.\n\n- Drop support for Python 2.6 and 3.2.\n\n\n4.1.0 (2015-04-16)\n==================\n\n- Add ``--version`` command line option (fixes\n https://github.com/zopefoundation/zdaemon/issues/4).\n\n- ``kill`` now accepts signal names, not just numbers\n (https://github.com/zopefoundation/zdaemon/issues/11).\n\n- Restore ``logreopen`` as an alias for ``kill USR2`` (removed in version\n 3.0.0 due to lack of tests):\n https://github.com/zopefoundation/zdaemon/issues/10.\n\n- Make ``logreopen`` also reopen the transcript log:\n https://github.com/zopefoundation/zdaemon/issues/9.\n\n- Reopen event log on ``logreopen`` or ``reopen_transcript``:\n https://github.com/zopefoundation/zdaemon/issues/8.\n\n- Help message for ``reopen_transcript``\n (https://github.com/zopefoundation/zdaemon/issues/5).\n\n- Fix race condition where ``stop`` would be ignored if the daemon\n manager was waiting before respawning a crashed program.\n https://github.com/zopefoundation/zdaemon/issues/13.\n\n- Partially fix delayed deadlock when the transcript file runs into a\n full disk (https://github.com/zopefoundation/zdaemon/issues/1).\n\n- Fix test suite leaving stale processes behind\n (https://github.com/zopefoundation/zdaemon/issues/7).\n\n\n4.0.1 (2014-12-26)\n==================\n\n- Add support for PyPy. (PyPy3 is pending release of a fix for:\n https://bitbucket.org/pypy/pypy/issue/1946)\n\n- Add support for Python 3.4.\n\n- Add ``-t/--transcript`` command line option.\n\n- zdaemon can now be invoked as a module as in ``python -m zdaemon ...``\n\n4.0.0 (2013-05-10)\n==================\n\n- Add support for Python 3.2.\n\n4.0.0a1 (2013-02-15)\n====================\n\n- Add tox support and MANIFEST.in for proper releasing.\n\n- Add Python 3.3 support.\n\n- Drop Python 2.4 and 2.5 support.\n\n3.0.5 (2012-11-27)\n==================\n\n- Fixed: the status command didn't return a non-zero exit status when\n the program wasn't running. This made it impossible for other\n software (e.g. Puppet) to tell if a process was running.\n\n3.0.4 (2012-07-30)\n==================\n\n- Fixed: The start command exited with a zero exit status even when\n the program being started failed to start (or exited imediately).\n\n3.0.3 (2012-07-10)\n==================\n\n- Fixed: programs started with zdaemon couldn't, themselves, invoke\n zdaemon.\n\n3.0.2 (2012-07-10)\n==================\n\nFail :(\n\n3.0.1 (2012-06-08)\n==================\n\n- Fixed:\n\n The change in 2.0.6 to set a user's supplemental groups broke common\n configurations in which the effective user was set via ``su`` or\n ``sudo -u`` prior to invoking zdaemon.\n\n Now, zdaemon doesn't set groups or the effective user if the\n effective user is already set to the configured user.\n\n3.0.0 (2012-06-08)\n==================\n\n- Added an option, ``start-test-program`` to supply a test command to\n test whether the program managed by zdaemon is up and operational,\n rather than just running. When starting a program, the start\n command doesn't return until the test passes. You could, for\n example, use this to wait until a web server is actually accepting\n connections.\n\n- Added a ``start-timeout`` option to error if a program takes too long to\n start. This is especially useful in combination with the\n ``start-test-program`` option.\n\n- Added an option, stop-timeout, to control how long to wait\n for a graceful shutdown.\n\n Previously, this was controlled by backoff-limit, which didn't make\n much sense.\n\n- Several undocumented, untested, and presumably unused features were removed.\n\n2.0.6 (2012-06-07)\n==================\n\n- Fixed: When the ``user`` option was used to run as a particular\n user, supplemental groups weren't set to the user's supplemental\n groups.\n\n2.0.5 (2012-06-07)\n==================\n\n(Accidental release. Please ignore.)\n\n2.0.4 (2009-04-20)\n==================\n\n- Version 2.0.3 broke support for relative paths to the socket (``-s``\n option and ``socket-name`` parameter), now relative paths work again\n as in version 2.0.2.\n\n- Fixed change log format, made table of contents nicer.\n\n- Fixed author's email address.\n\n- Removed zpkg stuff.\n\n\n2.0.3 (2009-04-11)\n==================\n\n- Added support to bootstrap on Jython.\n\n- If the run directory does not exist it will be created. This allow to use\n `/var/run/mydaemon` as run directory when /var/run is a tmpfs (LP #318118).\n\nBugs Fixed\n----------\n\n- No longer uses a hard-coded file name (/tmp/demo.zdsock) in unit tests.\n This lets you run the tests on Python 2.4 and 2.5 simultaneously without\n spurious errors.\n\n- make -h work again for both runner and control scripts.\n Help is now taken from the __doc__ of the options class users by\n the zdaemon script being run.\n\n2.0.2 (2008-04-05)\n==================\n\nBugs Fixed\n----------\n\n- Fixed backwards incompatible change in handling of environment option.\n\n2.0.1 (2007-10-31)\n==================\n\nBugs Fixed\n----------\n\n- Fixed test renormalizer that did not work in certain cases where the\n environment was complex.\n\n2.0.0 (2007-07-19)\n==================\n\n- Final release for 2.0.0.\n\n2.0a6 (2007-01-11)\n==================\n\nBugs Fixed\n----------\n\n- When the user option was used, it only affected running the daemon.\n\n2.0a3, 2.0a4, 2.0a5 (2007-01-10)\n================================\n\nBugs Fixed\n----------\n\n- The new (2.0) mechanism used by zdaemon to start the daemon manager\n broke some applications that extended zdaemon.\n\n- Added extra checks to deal with programs that extend zdaemon\n and copy the schema and thus don't see updates to the ZConfig schema.\n\n2.0a2 (2007-01-10)\n==================\n\nNew Features\n------------\n\n- Added support for setting environment variables in the configuration\n file. This is useful when zdaemon is used to run programs that need\n environment variables set (e.g. LD_LIBRARY_PATH).\n\n- Added a command to rotate the transcript log.\n\n2.0a1 (2006-12-21)\n==================\n\nBugs Fixed\n----------\n\n- In non-daemon mode, start hung, producing annoying dots\n when the program exited.\n\n- The start command hung producing annoying dots if the daemon failed\n to start.\n\n- foreground and start had different semantics because one used\n os.system and another used os.spawn\n\nNew Features\n------------\n\n- Documentation\n\n- Command-line arguments can now be supplied to the start and\n foreground (fg) commands\n\n- zdctl now invokes itself to run zdrun. This means that it's\n no-longer necessary to generate a separate zdrun script. This\n especially when the magic techniques to find and run zdrun using\n directory sniffing fail to set the path correctly.\n\n- The daemon mode is now enabled by default. To get non-daemon mode,\n you have to use a configuration file and set daemon to off\n there. The old -d option is kept for backward compatibility, but is\n a no-op.\n\n1.4a1 (2005-11-21)\n==================\n\n- Fixed a bug in the distribution setup file.\n\n1.4a1 (2005-11-05)\n==================\n\n- First semi-formal release.\n\nAfter some unknown release(???)\n===============================\n\n- Made 'zdaemon.zdoptions' not fail for --help when __main__.__doc__\n is None.\n\nAfter 1.1\n=========\n\n- Updated test 'testRunIgnoresParentSignals':\n\n o Use 'mkdtemp' to create a temporary directory to hold the test socket\n rather than creating the test socket in the test directory.\n Hopefully this will be more robust. Sometimes the test directory\n has a path so long that the test socket can't be created.\n\n o Changed management of 'donothing.sh'. This script is now created by\n the test in the temporarily directory with the necessary\n permissions. This is to avoids possible mangling of permissions\n leading to spurious test failures. It also avoids management of a\n file in the source tree, which is a bonus.\n\n- Rearranged source tree to conform to more usual zpkg-based layout:\n\n o Python package lives under 'src'.\n\n o Dependencies added to 'src' as 'svn:externals'.\n\n o Unit tests can now be run from a checkout.\n\n- Made umask-based test failures due to running as root emit a more\n forceful warning.\n\n1.1 (2005-06-09)\n================\n\n- SVN tag: svn://svn.zope.org/repos/main/zdaemon/tags/zdaemon-1.1\n\n- Tagged to make better 'svn:externals' linkage possible.\n\nTo-Dos\n======\n\nMore docs:\n\n- Document/demonstrate some important features, such as:\n\n - working directory\n\nBugs:\n\n- help command\n",
"bugtrack_url": null,
"license": "ZPL 2.1",
"summary": "Daemon process control library and tools for Unix-based systems",
"version": "5.1",
"project_urls": {
"Homepage": "https://github.com/zopefoundation/zdaemon"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d71417ae4ef5c94ee3e5508469511a3fe09d20b87f214ffc20c7a4123f43cdef",
"md5": "8fdadf88ffd3cbf8264d9c2fc34981a1",
"sha256": "e84327546e7c96613925d87b2eb204ff9c17d6343f9f81b28e3c3f52687fc4b3"
},
"downloads": -1,
"filename": "zdaemon-5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8fdadf88ffd3cbf8264d9c2fc34981a1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 57019,
"upload_time": "2024-05-03T13:25:09",
"upload_time_iso_8601": "2024-05-03T13:25:09.284262Z",
"url": "https://files.pythonhosted.org/packages/d7/14/17ae4ef5c94ee3e5508469511a3fe09d20b87f214ffc20c7a4123f43cdef/zdaemon-5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b8fd2e2748ab114b577b10889873cb370f7faf3ace5ce9b9b36a450452a2bd5",
"md5": "509e0b8a3709149cc220ad11cb132ed6",
"sha256": "22e9fe5050eaebb9e03d9ad64e4f63ccd85e04c38fdb351cf113bef6f68db7a4"
},
"downloads": -1,
"filename": "zdaemon-5.1.tar.gz",
"has_sig": false,
"md5_digest": "509e0b8a3709149cc220ad11cb132ed6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 60726,
"upload_time": "2024-05-03T13:25:11",
"upload_time_iso_8601": "2024-05-03T13:25:11.875552Z",
"url": "https://files.pythonhosted.org/packages/1b/8f/d2e2748ab114b577b10889873cb370f7faf3ace5ce9b9b36a450452a2bd5/zdaemon-5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-03 13:25:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zopefoundation",
"github_project": "zdaemon",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "zdaemon"
}
JSON
