Configuration.txt

= Configuring your daemon

daemon-kit provides a multitude of ways to configure your daemon, this document
will outline the different options available to you.

== Configuration files and #DaemonKit::Config

#DaemonKit::Config gives you easy access to any YAML configuration
files you have in your <em>config</em> directory.

You can access the configuration files like this:

  config = DaemonKit::Config.load('sample')

The above snippet relies on the presence of a <em>config/sample.yml</em> file.

#DaemonKit::Config is environment aware, so configuration files are
parsed for a top-level key that is the same as the value of
<em>DAEMON_ENV</em>, and if present is loaded into the object as the
configuration data. If the key is not present, the whole YAML
document is exposed as configuration data.

== Command line arguments

The most flexible way to configure your daemon is through command line
arguments, or switches.

DaemonKit includes a couple of its own arguments that can be used:

  -e ENV (or --env ENV) to set the daemon environment
  --pid /path/to/pidfile to set the path to a pidfile
  -l path (or --log path) to set the path for the log file
  -v shows the DaemonKit version
  -h shows a useful help message

=== Custom arguments

It is possible for you to specify your own arguments as well, by
updating the <em>config/arguments.rb</em> file. This file is eval'd
inside #DaemonKit::Arguments and gives you access to the following two
variables:

* opts - Instance of OptionParser[http://www.ruby-doc.org/stdlib/libdoc/optparse/rdoc/classes/OptionParser.html]
* @options - A standard Ruby hash that you can populate and access later

Your custom arguments can be accessed like this:

  DaemonKit.arguments.options

=== Advanced Configuration

All the writable attributes of the default #DaemonKit::Configuration
instance call also be modified from the command line using the special
<em>--config</em> arguments:

  --config force_kill_wait=30

This happens after <em>config/environment.rb</em> is processed, so all
command line arguments will overwrite those values.

=== Daemon umask

By default daemon processes run with a umask of 022, but this can be changed
on the command line or in +config/environment.rb+.

To set a more restrictive umask via command line arguments, you can start your
daemon like this:

  $ ./bin/daemon start --config umask=0077

Or the same in +config/environment.rb+

  DaemonKit::Initializer.run do |config|
    # ...

    # restrictive umask
    config.umask = 0077

    # ...
  end

=== Privilege Separation

By default daemon processes run as the user that starts them, inheriting all
their privileges (or lack thereof). Getting daemon-kit to drop privileges
can currently only be done using command-line parameters, and only works
reliable on *nix (OSX seemed cranky at the time of testing).

  $ ./bin/daemon start --config user=nobody --config group=nobody

Privileges are dropped at the earliest possible phase of starting the daemon.

Things to note on privilege separation:

* You generally have to be root to be able to perform this
* File system permissions for +log/+ needs to be correct
* Daemon-kit will only shed privileges on the +start+ command, not on +run+
* Make sure your code is secure if accepting stuff from the outside world
* The daemon will continue to run if it failed, this is because the feature is experimental and could change in the future.
* The damon logs the reduced privileges in the log file shortly after booting, please check it carefully

The implementation stems from the advice given by Joe Damato on his blog post
http://timetobleed.com/tag/privilege-escalation/

IMPORTANT NOTE FOR OSX USERS:

Testing on my iBook with OSX 10.5.8 using Ruby 1.8.6-p287 failed to drop
privileges correctly because of the 'nobody' user's UID being too large
(Bignum), however testing with Ruby 1.9.1-p129 on OSX 10.5.8 did work as
expected.