textgoeshere-daemon-kit 0.1.8rc3

data/.gitignore

@@ -0,0 +1,5 @@
+*#*
+pkg/
+tmp/
+doc/
+*.swp

data/Configuration.txt

@@ -0,0 +1,110 @@
+= 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.

data/Deployment.txt

@@ -0,0 +1,113 @@
+= Deploying your daemons
+
+daemon-kit provides built-in support for
+Capistrano[http://www.capify.org] deployments, using a customized
+version of the standard 'deploy' recipe for Ruby on Rails
+applications.
+
+User of Vlad[http://hitsquad.rubyforge.org/vlad/]? Get in touch so we
+can discuss your contribution to daemon-kit ;)
+
+== Generating capistrano configurations
+
+When generating a new daemon, you can pass the <em>-d capistrano</em>
+argument to the <em>daemon_kit</em> command. In case you already have
+a generated daemon, run the following command inside your project:
+
+  $ ruby script/generate deploy_capistrano
+
+== Overview of generated configurations
+
+The generator creates the following files worth noticing:
+
+  config/deploy.rb
+  config/deploy/*.rb
+
+The generator also creates a new environment for you, a
+<em>staging</em> environment. Useful for testing your deployments
+before taking anything into production.
+
+== Configuring capistrano
+
+For each environment (staging & production) you only need to specify
+the target hosts in <em>config/deploy/(staging|production).rb</em>.
+
+Each of the stub files have example configuration values you can just
+edit.
+
+The rest of your configuration generally occurs in
+<em>config/deploy.rb</em>.
+
+Everything works exactly like standard capistrano, with the exception
+of the following directives:
+
+* :config_files
+* :shared_children
+
+=== :config_files
+
+Since the daemon configuration files will almost always differ between
+your development environment and your staging/production environment,
+the deployment recipe makes adequate provision for this.
+
+Use the :config_files directive to set an array of file names from the
+<em>config</em> directory that you want replaced with production
+configuration files found on the server:
+
+  set :config_files, %w{ amqp.yaml }
+
+On your target server, in the <em>:deploy_to</em> folder, create a
+<em>config</em> directory and place your configuration files in
+there. One each deploy, capistrano will rename the files in your
+deployed configuration directory with a <em>.orig</em> extension, and copy
+the files from <em>:deploy_to/config</em> into the newly deployed
+release.
+
+This makes it easy to keep production configurations out of your
+working directories or version control systems.
+
+=== :shared_children
+
+The original capistrano recipe that daemon-kit's recipe is built from
+provided support for tracking shared directories between
+deployments. This works by removing the deployed directory, and
+creating a symlink from <em>:deploy_to/shared/</em> into the correct
+location within the deployed release.
+
+You specify your list of directories with the
+<em>:shared_children</em>, each being relative to the DAEMON_ROOT.
+
+  set :shared_children, %w{ log }
+
+The daemon-kit deployment recipe makes no assumptions on shared
+directories, and gives you full control. The default only includes the
+log directory, which you can remove if you want separate log
+directories for each deployed release.
+
+== Remote dependencies
+
+By default, the deployment configuration file is configured to check
+the remote dependencies before updating the code on the target
+host. You can disable this behaviour by commenting out the following
+line:
+
+  before "deploy:update_code", "deploy:check"
+
+The only default remote dependency is the daemon-kit gem, and it will
+check for the same version you currently have installed (or a later
+one).
+
+== More capistrano resources
+
+To see a list of available commands, please run the following command
+in the root of your project:
+
+  $ cap -vT
+
+For more information on capistrano, please refer to the following list
+of online resources:
+
+* Capistrano Website[http://www.capify.org]
+* Capistrano Wiki[http://wiki.capify.org]
+* Capistrano Group[http://groups.google.com/group/capistrano]
+* #capistrano on Freenode

data/History.txt

@@ -0,0 +1,124 @@
+== 0.1.18 (WIP)
+
+* Generators rewritten to use Thor
+* Evented XMPP now handled by blather
+* Boot script fixes
+* Removed Jabber generator, deprecating Jabber class (use XMPP)
+* Upgraded Hoptoad notifications to V2 of the notifier API
+* Fix various argument handling bugs
+* Removed support for exception emails
+* Improved log rotation support [mperham]
+
+== 0.1.7.12 2009-12-04
+
+* Bug fix, don't load environment files twice [grockit]
+
+== 0.1.7.11 2009-11-30
+
+* Renamed 'daemon_kit' executable to 'daemon-kit'
+* Fixed some broken links in README.rdoc
+* Sneaked in << on AbstractLogger for better Logger compatibility
+* Support for Test::Unit in generated projects [skaar]
+* Fixed missing DAEMON_ENV for test helpers
+* Fixes for nanite configuration [skaar]
+* Toughened up the ruote workitem parser
+* Fixed issue with nanite services not being advertised correctly [Wijnand]
+* Fixed some woes with rake if rspec gem is missing
+
+== 0.1.7.10 2009-08-12
+
+* Ruote remote participants
+* Allow process umask to be configured, defaults to 022
+* Updates to DaemonKit::Config hashes
+* Fixed argument parsing bug (reported by Mathijs Kwik (bluescreen303)
+* Support for privilege separation (See Configuration.txt)
+
+== 0.1.7.9 2009-06-22
+
+* Backtraces only logged on unclean shutdown
+* AMQP generator got new keep alive code
+
+== 0.1.7.8 2009-06-22
+
+* Optional logging of all exceptions when the daemon process dies
+  unexpectedly
+* Update generated environment.rb to reflect new backtraces option
+
+== 0.1.7.7 2009-06-22
+
+* Fixed compatibility with rufus-scheduler-2.0.0 (or newer) in cron
+  generator
+* Started central eventmachine reactor management code
+* Now depends on eventmachine
+
+== 0.1.7.6 (Not released)
+
+* Support for cucumber
+* Fixed issue in daemon_kit:upgrade task
+* Moved rspec generator into new home
+* Removed conflicting rubigen generator, messed with our script directory
+* Fixed bug where environment.rb overwrites some --config values (reported by Josh Owens)
+
+== 0.1.7.5 2009-06-08
+
+* New AbstractLogger
+** Default Logger backend
+** SysLogLogger support
+* More documentation
+
+== 0.1.7.4 2009-06-05
+
+* Fixed bug with control script generator (thanks Sho Fukamachi)
+* Enhanced deploy.rb template to check for current dk gem verion,
+  unless vendored
+* Fix bug in capistrano recipe for restarting daemons
+* Added log:truncate rake task
+* Error mails now handled by TMail
+
+== 0.1.7.3 2009-05-31
+
+* Removed dependency on daemons gem, now handled in house
+* New argument management
+* Some more docs
+
+== 0.1.7.1 2009-05-28
+
+* Fixed some minor issue with Capistrano support
+* Added support for generating dog/monit configuration files via rake
+* Initial implementation of ./script/* utilities
+
+== 0.1.7 2009-05-26
+
+* Capistrano deployment support
+
+== 0.1.6 2009-05-13
+
+* DaemonKit::Safety class to handle the trapping and logging of
+  exceptions, as well as email notifications or Hoptoad notifications.
+* New config/pre-daemonize and config/post-daemonize structure
+* New tasks to simplify upgrading daemon-kit projects
+* Fixed some other annoyances and bugs
+* Bigger TODO list
+
+== 0.1.5 2009-05-07
+
+* DaemonKit::Config class to easy the use of YAML configs internally,
+  and in generated daemons
+
+== 0.1.2 2009-04-28
+
+* Added missing rubigen dependency
+
+== 0.1.1 2009-04-27
+
+* AMQP consumer generator added
+* 'cron' style generator added
+* Allow configuring dir_mode and dir (pid file location) (Jim Lindley)
+
+== 0.1.0 2009-01-08
+
+* Ability to freeze the gem/edge copies of DaemonKit
+* Simple non-evented Jabber generator
+* Flexible UNIX signal trapping configuration
+* Basic generator completed
+* 1 small step for man, 1 giant leap for mankind

data/Logging.txt

@@ -0,0 +1,96 @@
+= Logging from inside your daemon
+
+Proper logging inside your daemon process is critical, and daemon-kit
+provides you with a great logging facility to (ab)use.
+
+== Logging examples
+
+From anywhere in your code you can access the
+<em>DaemonKit.logger</em> instance, which is a configured
+DaemonKit::AbstractLogger. It is compatible with Ruby's Logger class
+but is much more verbose to help you gain some insight into your
+running process.
+
+  DaemonKit.logger.info( "Hello world" )
+
+This logs a 'Hello world' line to the log file, complete with the
+calling file name and line number. Log lines look something like this:
+
+  2009-06-07 23:21:30.248575 capd(32513) [INFO] initializer.rb:91: DaemonKit (0.1.7.4) booted, now running capd
+
+Log as much as you can, but be careful not to abuse the <em>info</em>
+level since your log files can become huge. For general processing
+hints, use the <em>debug</em> level.
+
+To log exceptions, use the special <em>exception</em> helper:
+
+  begin
+    # dangerous operation
+  rescue => e
+    DaemonKit.logger.exception( e )
+  end
+
+== Controlling logging in a running process
+
+Logging can be controlled in a running process, either via code or by
+sending UNIX signals to the running process.
+
+=== Changing log levels in your code
+
+Log levels can be toggled with the <em>level=</em> method:
+
+  DaemonKit.logger.level = :info
+
+Alternatively you can silence all the logging activity for a while
+using the silence helper:
+
+  DaemonKit.logger.silence do |logger|
+    # logger will only report :error or higher levels
+  end
+
+You can also set the logging per environment by editing the correct file in <em>config/environments</em>
+
+  config.log_level = :debug
+
+=== Changing log levels via UNIX signals
+
+Send your process the +USR1+ signal to toggle between <em>:debug</em>
+and <em>:info</em> log levels. Sending a +USR2+ signal will force the
+logger into <em>:debug</em> mode (+USR1+ will revert).
+
+== Support for log rotation
+
+Support for logrotate is baked right into daemon-kit. By sending your
+daemon a +HUP+ signal all the log files file be closed and re-opened
+again on first use. Here is an example logrotate configuration:
+
+  /path/to/daemon.log {
+    rotate 5
+    weekly
+    postrotate
+      kill -HUP `cat /path/to/daemon.pid`
+    endscript
+  }
+
+== Support for syslog logging
+
+If you have the
+SyslogLogger[http://seattlerb.rubyforge.org/SyslogLogger/] gem
+installed, you can have your process log to a UNIX syslog server. You
+can change the logging to syslog by either updating your
+<em>environment.rb</em> file like this:
+
+  config.log_path = :syslog
+
+Or by passing 'syslog' as the logfile argument when starting a daemon
+
+  $ ruby ./bin/daemon start -l syslog
+
+The SyslogLogger rdoc's provide configuration examples for configuring
+various UNIX syslog servers.
+
+== More logging information
+
+If you're running your daemon in the foreground (with the <em>run</em>
+command, you'll get copies of all the log messages on STDOUT, and thus
+voiding the need to tail log files the whole time.