jobmanager 1.0.0

data/FAQ.txt

@@ -0,0 +1,151 @@
+=== Does +jobmanager+ rotate its own log file?
+
+No.  If +jobmanager+ is configured to log directly to a file
+(+central_log_mode+ is set to +file+), +jobmanager+ does not rotate
+this file.  This is because most versions of Unix ship with a standard
+log rotation utility that already provides a large number of features.
+Most variants of Linux ship with +logrotate+, Solaris ships with
++logadm+, FreeBSD with +newsyslog+.
+
+For example, in Fedora, one can specify that +jobmanager+'s central
+log file be rotated weekly (via the +logrotate+ utility) by creating
+the following file.
+
+======<tt>/etc/logrotate.d/jobmanager</tt>:
+ /var/log/jobmanager.log {
+    weekly
+    missingok
+ }
+
+
+If +jobmanager+ is configured to log via syslog (+central_log_mode+
+is set to +syslog+), the +jobmanager+ output will be directed to a
+central system log file (eg. +/var/log/messages+ on many Unix systems)
+for which log rotation will already be in place.
+
+=== Can I run +jobmanager+ out of my own user crontab even though I don't have permissions to edit +/etc/croncan.yaml+?
+
+Yes.  You can do this by setting the environment variable
++JOBMANAGER_CONFIG_FILE+ to a config file location of your choosing.
+
+=== What should I set the +central_log_mode+ configuration parameter to?  +syslog+ or +file+?
+
+This depends on how +jobmanager+ will be used as well as the user's
+personal preference.  One caveat with using the +file+ option is that
+if +jobmanager+ is invoked from the cron and there is an error
+reading the configuration file, +jobmanager+ will not be able to log
+this error to the central log file because it doesn't yet know the
+name of the central log file- it's in the configuration file!  Thus,
++jobmanager+ will attempt to log this error to syslog.  This can be
+avoided by doing a test run and invoking jobmanager with your new
+cron job via the command line before editing your crontab.
+
+A second point to keep in mind is that if you plan to have multiple
+users share the configuration file, and log to the same central log
+file, you will have to be careful about write permissions on the
+central log file (the central log file must be world writable or group
+writable with all users sharing the same group).  If you make the
+central log file group writable (and not world writable), you must
+make sure that the central_log_file is created (after rotation) with
+the proper group name.  You need not consider these concerns if you
+have multiple users logging via syslog as no permissions are required
+for this.
+
+=== When I run +jobmanager+ on the command line everything works, but when I run it through cron, it fails!  Why?
+
+There are a number reasons this could be the case all arising from the
+fact that the environment from which you invoke +jobmanager+ on the
+command line is different than the environment from which cron
+invokes +jobmanager+.  When you run a command from the shell, your
++.profile+ has already been loaded (which has set a number of
+environment variables).  When cron invokes a command, the +.profile+
+will not be loaded unless you explicitly load it yourself.
+
+Here is an example crontab entry which calls upon bash to load your
++.profile+ before running +jobmanager+.
+ 00 22 * * * bash -lc "jobmanager --job_name nightly_backup 'mysql_backup test'"
+
+If you have set the environment variable +JOBMANAGER_CONFIG_FILE+ in
+your +.profile+, you will need to explicitly load your +.profile+ before
+calling +jobmanager+ in the crontab entry.
+
+=== +jobmanager+ fails when invoked through the cron.  But there are no error messages in the central log file! Why?
+If +jobmanager+ encounters an error before opening the central log
+file, it will not be able to log this error to the central log file!
+Such errors will be logged to syslog.  Possible errors include:
+failure to open or parse the +jobmanager+ configuration file, failure
+to open or parse the email settings file, and failure to open the
+central log file.
+
+=== I have configured +jobmanager+ to log via syslog.  Where does this go?  
+
+Most if not all standard Unix systems ship with a syslog daemon
+(eg. {+rsyslogd+}[http://www.rsyslog.com/] on Fedora 8 and above,
+{+syslog-ng+}[http://www.balabit.com/network-security/syslog-ng/] on a
+number of Linux distributions).  The syslog daemon writes all log
+messages to a set of log files.  Which log messages are written to
+which file depends on the syslog daemon's configuration.  There is
+usually a default log file (eg. +/var/log/messages+) where the majority
+of syslog log messages are written to.
+
+=== I have configured +jobmanager+ to log via syslog.  Can all the +jobmanager+ specific output be sent to a separate file?
+
+Yes.  This requires configuring the syslog daemon.
+
+Here, I will provide an example of how to edit +rsyslogd+'s
+configuration file (<tt>/etc/rsyslog.conf</tt>) to send all
++jobmanager+ output to +/var/log/jobmanager.log+.
+{+rsyslogd+}[http://www.rsyslog.com/] is the syslog daemon that ships
+with Fedora 8 (and above).  At the top of the Rules section, add the
+lines below.
+
+======<tt>/etc/rsyslog.conf</tt>:
+ # RULES
+ ...
+ 
+ :programname, isequal, "jobmanager"               /var/log/jobmanager.log
+ 
+ # Prevent the jobmanager specific messages from being written to any other log files.
+ :programname, isequal, "jobmanager"     ~
+ 
+ ...
+ 
+
+
+See the {<tt>rsyslog home page</tt>}[http://www.rsyslog.com/] for further details.  For other Unix systems, consult the appropriate syslog daemon's manual.
+
+If you configure the syslog daemon to write +jobmanager+ specific
+output to a separate file, you may also want to configure your Unix
+system's log rotation utility to rotate this file as well.
+
+=== Can multiple users use the same configuration file?  Are there any caveats with doing this?
+
+Yes, multiple users can use the same configuration file.  In fact, if
+so desired, you can specify that the +job_logs_directory+,
++central_log_file+, and/or +email_settings_file+ each be different for
+each user.  This can be achieved by including the +user_name+ variable
+(with ERB syntax) in the desired configuration parameter's value.
+
+Here is an example configuration file excerpt that includes the +user_name+ variable.
+
+
+ job_logs_directory: /home/<%=user_name%>/cron_jobs
+
+If you have configured +jobmanager+ to log directly to a file, and the
+central log file is the same across multiple users, you must ensure
+that all users have permissions to write to this central log file.
+Refer to the FAQ question concerning whether to set the central log
+mode to file or syslog for more details concerning this.
+
+=== Should I specify the to/from email addresses in the {+simpleemail+}[http://simpleemail.rubyforge.org] configuration file or directly in +jobmanager.yaml+?
+
+Both options will work fine.  On my system, I use the
+{+simpleemail+}[http://simpleemail.rubyforge.org] gem in other pieces
+of Ruby code, and in most cases, send email from one default email
+address.  As a result, I prefer to specify the +default_to+,
++default_from+ email address parameters in the
+{+simpleemail+}[http://simpleemail.rubyforge.org] configuration file
+to minimize duplication.
+
+=== Can +jobmanager+ send email via smtp with tls/ssl enabled?
+Yes.  See the {+simpleemail+}[http://simpleemail.rubyforge.org] gem for details.

data/History.txt

@@ -0,0 +1,2 @@
+=== 1.0.0 / 2008-07-18
+Initial release of jobmanager.  This package is unit tested fully.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Designing Patterns
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,42 @@
+Manifest.txt
+LICENSE
+History.txt
+FAQ.txt
+README.txt
+Rakefile
+bin/jobmanager
+examples/email_settings.rb
+examples/example.rb
+examples/mysql_backup.rb
+examples/jobmanager.yaml
+lib/jobmanager.rb
+lib/jobmanager/applicationconfig.rb
+lib/jobmanager/applicationlogger.rb
+lib/jobmanager/applicationoptionparser.rb
+lib/jobmanager/application.rb
+lib/jobmanager/system.rb
+lib/jobmanager/teestream.rb
+lib/jobmanager/util.rb
+test/helpers.rb
+test/mock_syslog.rb
+test/test_applicationlogger.rb
+test/test_config.rb
+test/test_jobmanager.rb
+test/test_system.rb
+test/test_teestream.rb
+test/configs/email_settings.rb
+test/configs/all_values.yaml
+test/configs/bad_email_condition.yaml
+test/configs/bad_no_central_log_file.yaml
+test/configs/bad_number_of_job_logs.yaml
+test/configs/bad_timeout_zero.yaml
+test/configs/incomplete_1.yaml
+test/configs/jobmanager_1.yaml
+test/configs/jobmanager_2.yaml
+test/configs/jobmanager_3.yaml
+test/configs/jobmanager_4_bad_central_log_file.yaml
+test/configs/jobmanager_4_bad_email_settings_file.yaml
+test/configs/jobmanager_4_bad_job_logs_directory_1.yaml
+test/configs/jobmanager_4_bad_job_logs_directory_2.yaml
+test/configs/minimum_plus_email_settings.yaml
+test/configs/minimum_required.yaml

data/README.txt

@@ -0,0 +1,395 @@
+= jobmanager
+* Project Page: http://rubyforge.org/projects/jobmanager/
+* Documentation: http://jobmanager.rubyforge.org/
+
+== DESCRIPTION:
+
+This package makes managing cron jobs on unix systems a breeze!  It is
+composed of a single program, +jobmanager+, which is intended to be
+invoked by cron, or a cron-like application.  +jobmanager+, in turn,
+invokes the specified cron job, in addition to providing the following
+added value:
+
+* Logs the output of the cron jobs.
+* Rotates the cron job logs.
+* Manages a central log which records all cron events (when each job
+  starts, finishes, the job's success, etc).
+* Emails the user the results of the cron job on a configurable
+  condition (on failure only, on success only, etc.) via sendmail or
+  smtp.
+* Times out a cron job that runs past the configurable timeout.
+* Easily scales to handle multiple users' cron jobs.
+* Both the default behavior and the per-cron job behavior are highly
+  configurable.
+
+== SYNOPSIS:
+
+Lets walk through an example invocation of +jobmanager+ via cron.  
+
+Here is an example +crontab+ entry that invokes a simplified database
+backup script via +jobmanager+ every day at 22:00.
+ 00 22 * * * jobmanager --job_name nightly_backup "mysql_backup test"
+
+Here is the example +mysql_backup+ script referenced above:
+======<tt>examples/mysql_backup.rb</tt>:
+ #!/usr/bin/env ruby
+ 
+ print "=================================================\n"
+ print "Backing up Database\n"
+ print "=================================================\n"
+ 
+ database = ARGV[0]
+ 
+ command     = "mysqldump #{database} > /tmp/#{database}.mysql"
+ print command, "\n"
+ 
+ if (system("#{command}"))
+   print"\nSuccess!\n"
+ else
+   print "\nFailure!\n"
+   exit(1)
+ end
+ 
+
+
+Here is the configuration file to be read by +jobmanager+.
+======<tt>/etc/jobmanager.yaml</tt>:
+ ################################################################################
+ # The jobmanager configuration file.
+ #
+ # For a full description of each of the fields, and their default values,
+ # see the CONFIGURATION FILE section in README.txt.
+ ################################################################################
+ 
+ # The number of log files to be kept per job.
+ number_of_job_logs: 5
+ 
+ # The directory in which the job logs will be kept, to be interpreted
+ # by ERB.  Allowed variables: user_name.
+ job_logs_directory: /tmp/logs
+ 
+ # jobmanager logs operational information (when jobs are launched,
+ # exit, etc).  This can be done via syslog or directly to a log file.
+ # Possible values are: syslog, file.
+ central_log_mode: file
+ 
+ # If the central_log_mode is set to "file", the log file must be
+ # specified.  This parameter will be interpreted by ERB.  Allowed
+ # variables: user_name.
+ central_log_file: /tmp/logs/jobmanager.log
+ 
+ # The path to search for the command that jobmanager is invoked with.  
+ #command_path: /usr/bin:/usr/designingpatterns/bin
+ 
+ # Whether jobmanager should print debug trace to the central log file.
+ debug: false
+ 
+ # The condition upon which condition results should be emailed.
+ # Possible values are: always, never, on_failure.  
+ email_condition: always
+ 
+ # The configuration file for the simpleemail gem.  This parameter will
+ # be interpreted by ERB.  Allowed variables: user_name.  Note: If a
+ # relative path is specified, it will be considered to be relative to
+ # the location of this configuration file.
+ email_settings_file: email_settings.rb
+ 
+ # The email subject, to be interpreted by ERB.
+ # Allowed variables: job_name, command, host_name, results, user_name.
+ email_subject: "jobmanager results for <%=job_name%> on <%=host_name%> : <%=result%>"
+ 
+ # The extension of the rotated job log file.  If true, the extension
+ # is a date_time.  Otherwise, it is a simple count (.1, .2, etc.).
+ date_time_extension: true
+ 
+ # If date_time_extension is true, this field will be used as the
+ # format for the date/time extension of the rotated job log file
+ # name.
+ date_time_extension_format: '%F_%T'
+ 
+ # Whether the rotated job log file should be zipped.
+ zip_rotated_log_file: false
+ 
+ # The timeout (in seconds).  If not present, no timeout will be used.
+ timeout: 1800
+ 
+ # The sender of emails sent from jobmanager.  This can also be
+ # specified in the email_settings_file (attribute default_from).
+ #email_from_address: "Sender <sender@gmail.com>"
+ 
+ # The receiver of emails sent from jobmanager.  This can also be
+ # specified in the email_settings_file (attributes default_to).
+ #email_to_address: "Receiver <receiver@gmail.com>"
+
+
+Here is the email configuration file referenced in +jobmanager.yaml+
+above.  In this example, we choose to email via smtp, although
+sendmail is also an option.  This file is documented further in the
+{+simpleemail+}[http://simpleemail.rubyforge.org] gem.
+======<tt>/etc/email_settings.rb</tt>:
+ ActionMailer::Base.delivery_method = :smtp
+ 
+ ActionMailer::Base.smtp_settings = {
+   :address => 'smtp.gmail.com',
+   :port   => 587,
+   :domain => "gmail.com",
+   :authentication => "login",
+   :user_name => "sender_address@gmail.com",
+   :password => "password",
+   :tls => :auto
+ }
+ 
+ SimpleEmail::Email.default_from = "Sender Address <sender_address@gmail.com>"
+ SimpleEmail::Email.default_to = "Receiver Address <receiver_address@gmail.com>"
+
+
+Here is the central log file that +jobmanager+ updated.
+======<tt>/tmp/logs/jobmanager.log</tt>:
+ I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Command (/usr/bin/mysql_backup test) launched, pid = 2302.
+ I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Exited successfully
+ I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Job log rotated to /tmp/logs/nightly_backup.log.2008-07-30_22:00:00.
+
+
+Here is the rotated job log file.
+======<tt>/tmp/logs/nightly_backup.log.2008-07-30_22:00:00</tt>:
+ =================================================
+ Backing up Database
+ =================================================
+ mysqldump test > /tmp/test.mysql
+ 
+ Success!
+
+Here is the subject and body of the email that was sent upon job completion.
+
+======<tt>Email Subject</tt>:
+ jobmanager results for nightly_backup on jackfruit : Success
+
+======<tt>Email Body</tt>:
+ ---------------------------------------------------------
+ jobmanager Output:
+ ---------------------------------------------------------
+ I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Command (/usr/bin/mysql_backup test) launched, pid = 2302.
+ I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Exited successfully
+ I, [2008-07-30T22:00:00 #2301]  INFO -- : [janet, nightly_backup] Job log rotated to /tmp/logs/nightly_backup.log.2008-08-01_11:29:47.
+ 
+ ---------------------------------------------------------
+ Job Output:
+ ---------------------------------------------------------
+ =================================================
+ Backing up Database
+ =================================================
+ mysqldump test > /tmp/test.mysql
+ 
+ Success!
+ 
+
+
+== CONFIGURATION FILE:
+
+A configuration file is required for +jobmanager+ to run.  By default,
++jobmanager+ will expect the configuration file to be located at
++/etc/jobmanager.yaml+.  If the environment variable
++JOBMANAGER_CONFIG_FILE+ is set, +jobmanager+ will instead read the
+configuration file specified by this variable.
+
+The configuration file provides the following parameters:
+
+[+job_logs_directory+: required] 
+   The directory in which the job log files will be kept.  The
+   +job_logs_directory+ parameter will be interpreted by ERB.  The
+   allowed variables are: +user_name+.  Specifying the +user_name+
+   variable in the +job_logs_directory+ value can be useful if you
+   want multiple users to share the same configuration file, but have
+   different job logs directories.
+
+[+central_log_mode+: optional, default: +syslog+]
+   +jobmanager+ logs operational information (when jobs are
+   launched, exit, etc).  This can be done via +syslog+ or directly to a
+   log file.  Possible values are: <tt>syslog, file</tt>.
+
+[+central_log_file+: optional]
+   If +central_log_mode+ is set to +file+, this parameter must be set.
+   The +central_log_file+ parameter will be interpreted by ERB.  The
+   allowed variables are: +user_name+.  Specifying the +user_name+
+   variable in the +central_log_file+ value can be useful if you want
+   multiple users to share the same configuration file, but have
+   different central log files.
+
+[+number_of_job_logs+: optional, default: +3+]
+   The number of logs to be kept per job.
+
+[+command_path+: optional, default: <tt>ENV['PATH']</tt> ]
+   The path to be searched for the command that +jobmanager+ is
+   invoked with.  If unspecified, the environment path will be used.
+
+[+debug+: optional, default: +false+]
+   Whether +jobmanager+ should print debug trace to the central log file.
+
+[+email_condition+: optional, default: +on_failure+]
+   The condition upon which results should be emailed.  Possible
+   values are: <tt>always, never, on_failure</tt>.
+
+[+email_settings_file+: optional, default: +email_settings.rb+]
+  The configuration file for the
+  {+simpleemail+}[http://simpleemail.rubyforge.org] gem.  This
+  specifies the delivery method (+smtp+, +sendmail+), as well as
+  delivery method specific settings.  Default to/from emails can be
+  specified in here.  If the path specified is relative, it is assumed
+  that it is relative to the directory in which the +jobmanager+
+  configuration file is located.  If +email_condition+ is set to a
+  value other than +never+, this parameter must specified.  The
+  +email_settings_file+ parameter will be interpreted by ERB.  The
+  allowed variables are: +user_name+.  Specifying the +user_name+
+  variable in the +email_settings_file+ value can be useful if you
+  want multiple users to share the same configuration file, but have
+  separate email settings files.
+
+
+[+email_subject+, optional, default: <tt>"jobmanager results for <%=job_name%> on <%=host_name%> : <%=result%>"</tt>]
+  The email subject, to be interpreted by ERB.  Allowed variables
+  inside the string are: <tt>job_name, command, host_name, results, user_name</tt>.
+
+[+date_time_extension+, optional, default: +true+]
+   This refers to the extension of the rotated job log file.  If
+   +date_time_extension+ is present and set to +true+, the extension
+   represents a date and time.  Otherwise, it is a simple count (.1, .2, etc.).
+
+[+date_time_extension_format+, optional, default: <tt>'%F_%T'</tt>]
+   If +date_time_extension+ is +true+, this parameter will be used as the
+   format for the date and time extension of the rotated job log file.
+
+[+zip_rotated_log_file+, optional, default: +false+]
+   Whether the rotated job log file should be gzip'ed.
+
+[+timeout+, optional]
+   The timeout (in seconds).  If the job spawned by +jobmanager+ does not
+   exit after +timeout+ seconds, +jobmanager+ will kill the process, and
+   report failure.  If +timeout+ is unspecifed, +jobmanager+ will let the
+   process run for an unlimited amount of time (+jobmanager+ will simply
+   wait til it returns).
+
+[+email_from_address+, optional]
+   The sender of emails sent from +jobmanager+.  This can also be
+   specified in the +email_settings_file+ (attribute +default_from+).
+
+[+email_to_address+, optional]
+   The receiver of emails sent from +jobmanager+.  This can also be
+   specified in the +email_settings_file+ (attribute +default_to+).
+
+== COMMAND LINE ARGUMENTS:
+
+Usage:
+ Usage: jobmanager.rb [options] <command>
+
+Notable command line options:
+[<tt>-j, --job_name</tt>]
+   The name of the job to be run.  If this is unspecified, the
+   job name will be set to the basename of the COMMAND specified.
+   The job name is used when logging to the central log file, and
+   in the name of the job log file.
+
+The remaining command line options are duplicates of the configuration
+file parameters.  In fact, all of the configuration parameters
+specified in the configuration file can be overriden via +jobmanager+
+command line options.  
+
+== STARTING JOBMANAGER FROM THE COMMAND LINE VS. CRON:
+
+The most common use case for +jobmanager+ is to be run from cron, or a
+cron-like application.  However, invoking +jobmanager+ from the
+command line can be useful for testing, debugging, and one-off runs.
+As +jobmanager+ is commonly invoked via the cron, +jobmanager+ logs
+all output to either +syslog+ or a central log file (specified by the
+configuration parameters +central_log_mode+, +central_log_file+).
+When +jobmanager+ is run from the command line (or any script whose
+STDIN, STDOUT, or STDERR is connected to a terminal), these two
+configuration parameters will be ignored and +jobmanager+'s output
+will be sent to the terminal.
+
+== REQUIREMENTS:
+
+The +jobmanager+ application requires a number of gems: hoe,
+SyslogLogger, sys-host, configtoolkit, simpleemail, logrotate,
+assertions, and relative.
+
+Hoe and assertions are required only for running the tests.  Relative is
+required for running the tests and the examples.  The rest of the gems
+listed above are required for the proper functioning of the
++jobmanager+ application.  The sys-host gem is required only for the
+purpose of including the hostname in the email subject line.
+
+== INSTALL:
+
+1. <tt>sudo gem install jobmanager</tt>
+
+2. Set up the +jobmanager+ configuration file (+jobmanager.yaml+).
+   For more detailed instructions, see the CONFIGURATION FILE section
+   above.
+
+3. Set up the simpleemail configuration file (+email_settings.rb+).
+   Alternately, if you want to disable email, set the configuration
+   parameter +email_condition+ to +never+ in +jobmanager.yaml+.  See
+   the {+simpleemail+}[http://simpleemail.rubyforge.org] gem rdoc for
+   more details.
+
+4. Confirm that the configuration files are valid by invoking
+   +jobmanager+ from the command line with one of your cron jobs or a
+   test command.
+
+5. Edit your +crontab+ to run new and/or existing cron jobs through
+   +jobmanager+.
+
+For possible reasons why running +jobmanager+ via the command line may
+be successful, but running +jobmanager+ with the same configuration
+via the cron may fail, consult FAQ.txt.
+
+== PROBLEMS:
+
+None (known).
+
+== AUTHORS:
+=== Designing Patterns
+* Homepage: http://www.designingpatterns.com
+* Blogs: http://blogs.designingpatterns.com
+
+== SUPPORT:
+Please post questions, concerns, or requests for enhancement to the forums on
+the project page.  Alternatively, direct contact information for
+Designing Patterns can be found on the project page for this gem.
+
+== ENHANCEMENTS:
+Please feel free to contact us with any ideas; we will try our best to
+enhance the software and respond to user requests.  Of course, we are more
+likely to work on a particular enhancement if we know that there are users
+who want it.  Designing Patterns provides contracting and consulting services,
+so if there is an enhancement that *must* get done (and in a specified time
+frame), please inquire about retaining our services!
+
+== LICENSE:
+The license text can be found in the +LICENSE+ file at the root of the
+distribution.
+
+This  package is licensed with an MIT license:
+
+Copyright (c) 2008 Designing Patterns
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+== SHARE AND ENJOY!