xdaemonocle 0.8.1

Installation

To install via pip:

pip install daemonocle

Or download the source code and install manually:

git clone https://github.com/jnrbsn/daemonocle.git
cd daemonocle/
python setup.py install

Basic Usage

Here’s a really really basic example:

import sys
import time

import daemonocle

# This is your daemon. It sleeps, and then sleeps again.
def main():
    while True:
        time.sleep(10)

if __name__ == '__main__':
    daemon = daemonocle.Daemon(
        worker=main,
        pidfile='/var/run/daemonocle_example.pid',
    )
    daemon.do_action(sys.argv[1])

And here’s the same example with logging and a Shutdown Callback:

import logging
import sys
import time

import daemonocle

def cb_shutdown(message, code):
    logging.info('Daemon is stopping')
    logging.debug(message)

def main():
    logging.basicConfig(
        filename='/var/log/daemonocle_example.log',
        level=logging.DEBUG, format='%(asctime)s [%(levelname)s] %(message)s',
    )
    logging.info('Daemon is starting')
    while True:
        logging.debug('Still running')
        time.sleep(10)

if __name__ == '__main__':
    daemon = daemonocle.Daemon(
        worker=main,
        shutdown_callback=cb_shutdown,
        pidfile='/var/run/daemonocle_example.pid',
    )
    daemon.do_action(sys.argv[1])

And here’s what it looks like when you run it:

user@host:~$ python example.py start
Starting example.py ... OK
user@host:~$ python example.py status
example.py -- pid: 1234, status: running, uptime: 1m, %cpu: 0.0, %mem: 0.0
user@host:~$ python example.py stop
Stopping example.py ... OK
user@host:~$ cat /var/log/daemonocle_example.log
2014-05-04 12:39:21,090 [INFO] Daemon is starting
2014-05-04 12:39:21,091 [DEBUG] Still running
2014-05-04 12:39:31,091 [DEBUG] Still running
2014-05-04 12:39:41,091 [DEBUG] Still running
2014-05-04 12:39:51,093 [DEBUG] Still running
2014-05-04 12:40:01,094 [DEBUG] Still running
2014-05-04 12:40:07,113 [INFO] Daemon is stopping
2014-05-04 12:40:07,114 [DEBUG] Terminated by SIGTERM (15)

For more details, see the Detailed Usage section below.

Rationale

If you think about it, a lot of Unix daemons don’t really know what the hell they’re doing. Have you ever found yourself in a situation that looked something like this?

user@host:~$ sudo example start
starting example ... ok
user@host:~$ ps aux | grep example
user      1234  0.0  0.0   1234  1234 pts/1    S+   12:34   0:00 grep example
user@host:~$ sudo example start
starting example ... ok
user@host:~$ echo $?
0
user@host:~$ tail -f /var/log/example.log
...

Or something like this?

user@host:~$ sudo example stop
stopping example ... ok
user@host:~$ ps aux | grep example
user       123  0.0  0.0   1234  1234 ?        Ss   00:00   0:00 /usr/local/bin/example
user      1234  0.0  0.0   1234  1234 pts/1    S+   12:34   0:00 grep example
user@host:~$ sudo example stop
stopping example ... ok
user@host:~$ ps aux | grep example
user       123  0.0  0.0   1234  1234 ?        Ss   00:00   0:00 /usr/local/bin/example
user      1240  0.0  0.0   1234  1234 pts/1    S+   12:34   0:00 grep example
user@host:~$ sudo kill -9 123
...

Or something like this?

user@host:~$ sudo example status
Usage: example {start|stop|restart}
user@host:~$ ps aux | grep example
...

These are just a few examples of unnecessarily common problems. It doesn’t have to be this way.

Note: You might be thinking, “Why not just write a smarter start/stop shell script wrapper for your daemon that checks whether or not it actually started, actually stopped, etc.?” Seriously? It doesn’t have to be this way. I believe daemons should be more self-aware. They should handle their own problems most of the time, and your start/stop script should only be a very thin wrapper around your daemon or simply a symlink to your daemon.

user@host:~$ python example.py status
example.py -- pid: 1234, status: running, uptime: 12d 3h 4m, %cpu: 12.4, %mem: 4.5

import os
import sys
import time

import daemonocle

class FileWatcher(object):

    def __init__(self, filename, daemon):
        self._filename = filename
        self._daemon = daemon
        self._file_mtime = os.stat(self._filename).st_mtime

    def file_has_changed(self):
        current_mtime = os.stat(self._filename).st_mtime
        if current_mtime != self._file_mtime:
            self._file_mtime = current_mtime
            return True
        return False

    def watch(self):
        while True:
            if self.file_has_changed():
                self._daemon.reload()
            time.sleep(1)

if __name__ == '__main__':
    daemon = daemonocle.Daemon(pidfile='/var/run/daemonocle_example.pid')
    fw = FileWatcher(filename='/etc/daemonocle_example.conf', daemon=daemon)
    daemon.worker = fw.watch
    daemon.do_action(sys.argv[1])

Detailed Usage

The daemonocle.Daemon class is the main class for creating a daemon using daemonocle. Here’s the constructor signature for the class:

class daemonocle.Daemon(
    worker=None, shutdown_callback=None, prog=None, pidfile=None, detach=True,
    uid=None, gid=None, workdir='/', chrootdir=None, umask=022, stop_timeout=10,
    close_open_files=False)

And here are descriptions of all the arguments:

worker

The function that does all the work for your daemon.

shutdown_callback

This will get called anytime the daemon is shutting down. It should take a message and a code argument. The message is a human readable message that explains why the daemon is shutting down. It might useful to log this message. The code is the exit code with which it intends to exit. See Shutdown Callback for more details.

prog

The name of your program to use in output messages. Default: os.path.basename(sys.argv[0])

pidfile

The path to a PID file to use. It’s not required to use a PID file, but if you don’t, you won’t be able to use all the features you might expect. Make sure the user your daemon is running as has permission to write to the directory this file is in.

detach

Whether or not to detach from the terminal and go into the background. See Non-Detached Mode for more details. Default: True

uid

The user ID to switch to when the daemon starts. The default is not to switch users.

gid

The group ID to switch to when the daemon starts. The default is not to switch groups.

workdir

The path to a directory to change to when the daemon starts. Note that a file system cannot be unmounted if a process has its working directory on that file system. So if you change the default, be careful about what you change it to. Default: "/"

chrootdir

The path to a directory to set as the effective root directory when the daemon starts. The default is not to do anything.

umask

The file creation mask (“umask”) for the process. Default: 022

stop_timeout

Number of seconds to wait for the daemon to stop before throwing an error. Default: 10

close_open_files

Whether or not to close all open files when the daemon detaches. Default: False

import daemonocle

class MyDaemon(daemonocle.Daemon):

    @daemonocle.expose_action
    def full_status(self):
        """Get more detailed status of the daemon."""
        pass

import time

import click
from daemonocle.cli import DaemonCLI

@click.command(cls=DaemonCLI, daemon_params={'pidfile': '/var/run/example.pid'})
def main():
    """This is my awesome daemon. It pretends to do work in the background."""
    while True:
        time.sleep(10)

if __name__ == '__main__':
    main()

user@host:~$ python example.py --help
Usage: example.py [<options>] <command> [<args>]...

  This is my awesome daemon. It pretends to do work in the background.

Options:
  --help  Show this message and exit.

Commands:
  start    Start the daemon.
  stop     Stop the daemon.
  restart  Stop then start the daemon.
  status   Get the status of the daemon.
user@host:~$ python example.py start --help
Usage: example.py start [<options>]

  Start the daemon.

Options:
  --debug  Do NOT detach and run in the background.
  --help   Show this message and exit.

Bugs, Requests, Questions, etc.

Please create an issue on GitHub.