Awesome
Daemon Sauce
Just add Daemon Sauce to your Node project, to make it a proper *nix daemon. This is intended to help build daemons that play nice on machines with services managed by something like (traditional) init(8) or Upstart.
The main things that this module does:
- Handle the creation of a disconnected child process.
- Manage a process lockfile.
- Redirect console to an error log and to the syslog (depending on the method).
- Setting user and group ids to drop privileges (when running as root).
Building and Installation
npm install daemonsauce
Or grab the source and
node-waf configure build
Note: This module contains native code, and so you will have to have a C compiler available. Consult your OS documentation for details on setting that up.
Testing
It is unfortunately not easy to put together a generic automated test for the functionality in this module, such that it can be expected to work in (that is, to successfully test) the wide range of environments in which it is potentially deployed. In practice, this module has been tested by a lot of trial and error, along with a fair amount of one-off poking and prodding.
The author would love some input (where "input" means "Pull requests, please!") on how to remedy this situation.
Usage
The easiest way to make use of this is by using the provided wrapper
bin-script
(in the examples
directory). Arrange your application files
so that the wrapper is in a bin
directory, and next to bin
is
a directory containing your main application. Rename the wrapper script
to have the same name as the main application directory. For example:
my-application/
bin/
server <-- the example bin-script
server/
package.json
main.js
...
If you do this, then the script will take care of all the forking and
setting of userids, and so on. It keys off of a few additional
properties that can be defined in your package.json
file:
-
rootMain
-- If you define this to to be a file name (relative to the application directory), then it will be loaded and run (viarequire()
) as the root userid (assuming the app started out running as root), just before Daemon Sauce drop privileges. -
daemonUser
-- Use this to specify the userid (by name) to run the main application as. If unset, it defaults to the product name (name
in thepackage.json
file.) -
daemonGroup
-- Use this to specify the groupid (by name) to run the main application as. If unset, it defaults to the userid (which may itself just be the default of the product name).
If you want to make life hard on yourself, there are also separate methods to handle most of the various bits and pieces. UTSL for details.
The one requirement for your commandline arguments is that you pass in
a --daemon
argument to kick things off. When running normally (that
is, to cause it to create a real daemon in the usual fork/detach
style), pass --daemon=parent
. When running in a development
environment, pass --daemon=foreground
to cause the process to remain
an attached foreground process (and not mess with log or lock files,
either). If you are trying to debug what happens as the child process
starts, make yourself a root shell (e.g., sudo su
), and try running
the daemon with --daemon=child
. In the last case, note that the
system will close and/or redirect stdio pretty early.
You should expect to see --daemon=child
in the arguments to your
application when it is running "for real" (as opposed to in one of
the set-up phases).
Directory Setup Details
The suggested/example bin-script
file assumes that a "normal"
installation of a daemon is done in /usr/...
, with associated data
in /var/...
(where the ...
s are the same). When you install a
daemon, it is probably a good idea to create that /var
directory at
the same time, assigning it a user and group that match the product
name or explicit daemonUser
/ daemonGroup
, as appropriate.
If the daemon is run from a directory that's not under /usr
, it
assumes it is in a development environment, and instead of looking for
a var/...
directory, it assumes that the data lives in a data
subdirectory of the installation.
Logging Details
This section only applies when running as a daemon (as opposed to in the foreground for development).
Once set up, console.log()
and most of the other standard logging
functions will write to a file called error.log
in the specified
logging directory. The one exception is that console.info()
will
emit a log message to the syslog. (You can find the syslog in the
file /var/log/messages
on many Linux distros and in the file
/var/log/system.log
on OS X.)
Daemon Sauce also arranges to rotate the error.log
file once a day
(at around midnight UTC), renaming the file based on the date that it
covered, and recreating / reopening the "plain" error.log
to cover
the upcoming day.
The idea behind all this is not that error.log
or the syslog are
great places to log to, but rather they are acceptable places to log
to as a fallback, when it is too early in a daemon's life to have
anything more durable or structured to use. It is also the case that
Node (in 0.6.*, as of this writing) will always write "uncaught
exception" messages to the underlying stderr stream, as the process is
dying. At least error.log
is a place where these messages can be
found, when doing forensics.
Lockfile Details
This section only applies when running as a daemon (as opposed to in the foreground for development).
A lockfile is used to ensure that only one instance of a daemon is running at any given time.
In this case, the lockfile is named product-name.pid
and placed in
the specified run directory. During startup, if it turns out that
another process has locked the lockfile (this uses the POSIX call
lockf()
), this will cause the new process to exit after writing a
message to that effect to the syslog.
If the lock is successful, then the "winning" process writes out its
process id to the lockfile, which makes it convenient to inspect,
e.g. by cat product-name.pid
from a console.
Using Upstart
The file upstart.conf
in the example directory is a simple example
of how one might hook up a service that uses Daemon Sauce.
To Do
- Find something to do!
Contributing
Questions, comments, bug reports, and pull requests are all welcome. Submit them at the project on GitHub.
Bug reports that include steps-to-reproduce (including code) are the best. Even better, make them in the form of pull requests that add tests (which, yes, is a hard nut to crack in this case). Thanks!
Author
Dan Bornstein (personal website), supported by The Obvious Corporation.
License
Copyright 2012 The Obvious Corporation.
Licensed under the Apache License, Version 2.0.
See the top-level file LICENSE.txt
and
(http://www.apache.org/licenses/LICENSE-2.0).