whenjobs initial version.

[whenjobs.git] / daemon / whenjobsd.pod

diff --git a/daemon/whenjobsd.pod b/daemon/whenjobsd.pod
new file mode 100644 (file)
index 0000000..938358b
--- /dev/null
+++ b/daemon/whenjobsd.pod
@@ -0,0 +1,130 @@
+=encoding utf8
+
+=head1 NAME
+
+whenjobsd - whenjobs per-user daemon
+
+=head1 SYNOPSIS
+
+ whenjobsd
+
+To start the daemon as a user, do:
+
+ whenjobs --daemon-start
+
+To start the daemon as root (eg. from C</etc/rc.local>) for a
+particular user called C<username> do:
+
+ su username -c /usr/sbin/whenjobsd
+
+=head1 DESCRIPTION
+
+C<whenjobsd> is the daemon that runs whenjobs.  Normally users do not
+need to run this program directly.  You can start and stop the daemon
+using the L<whenjobs(1)> tool:
+
+ whenjobs --daemon-start
+ whenjobs --daemon-stop
+ whenjobs --daemon-status
+ whenjobs --daemon-restart
+
+All documentation on the whenjobs cron replacement system can be found
+in the L<whenjobs(1)> man page.  This man page documents the daemon
+only.
+
+Unlike cron, each user that wants to use whenjobs runs their own
+whenjobsd.  They operate completely separately.
+
+The daemon sends log messages to syslog using the "cron" facility.
+Where these end up depends on the configuration of your syslog system,
+which can vary from Linux distro to Linux distro.  Typically the file
+to look at might be one of:
+
+ /var/log/cron
+ /var/log/syslog
+ /var/log/messages
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-d>
+
+Enable extra debugging messages.  These are sent to syslog.
+
+=item B<-f>
+
+Don't fork into the background.
+
+=item B<-V>
+
+=item B<--version>
+
+Display the name and version of the program and exit.
+
+=item B<-help>
+
+=item B<--help>
+
+Display brief usage and exit.
+
+=back
+
+=head1 FILES
+
+=over 4
+
+=item C<$HOME/.whenjobs/daemon_pid>
+
+This contains the process ID of the daemon.  The daemon also holds an
+advisory (L<flock(2)>-style) exclusive lock on this file while it is
+running.
+
+=item C<$HOME/.whenjobs/jobs.cmo>
+
+This is the compiled jobs specification which the daemon loads on
+start up, or reloads when instructed to by the L<whenjobs(1)> tool.
+
+=item C<$HOME/.whenjobs/socket>
+
+The daemon creates this socket and listens for incoming connections
+from the L<whenjobs(1)> tool.
+
+=back
+
+=head1 ENVIRONMENT VARIABLES
+
+=over 4
+
+=item C<$HOME>
+
+The user's home directory.  This directory must exist and must be
+owned by the same user as the daemon.
+
+=back
+
+=head1 SEE ALSO
+
+L<whenjobs(1)>
+
+=head1 AUTHOR
+
+Richard W.M. Jones L<http://people.redhat.com/~rjones/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2012 Red Hat Inc.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.