rpms/upstart/devel events.5,NONE,1.1 upstart.spec,1.14,1.15

Sat Apr 5 00:49:38 UTC 2008

Author: notting

Update of /cvs/extras/rpms/upstart/devel
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv30557

Modified Files:
	upstart.spec 
Added Files:
	events.5 
Log Message:
add an 'events' manpage (#439245)

--- NEW FILE events.5 ---
.TH events 5 "April 2008" "Upstart"
.\"
.SH NAME
events \- format of event files used by the upstart init system
.\"
.SH DESCRIPTION
upstart works on the basis of \fBevent\fP files that describe jobs
that should be managed. This includes the particulars about what binary
or shell script code should executed while the job is running, and
which events can cause the job to be started or stopped.

Event files are stored in the \fI/etc/event.d\fP directory.
.\"
.SH SYNTAX

Event files can contain the following stanzaz.

.TP
.BI "exec  <command> <arguments>"
When the event is started by \fBinit\fR, execute the following arguments.

Example: exec /bin/dbus-daemon --system

.TP
.BI "script ..."
Like \fBexec\fR but instead of executing a single program, execute
the following shell code. \fBscript\fR sections are closed with a
\fBend script\fR marker.

Example:
.nf
	script
		rm -f /var/run/sshd.pid
		sshd
	end script
.ni

Only one of  \fBexec\fR and \fBscript\fR can be used at a time. If both
are bspecifed, \fBexec\fR takes priority.

.TP
.BI pre-start
Execute the command/script before actually starting the process.
\fBpre-start\fR can be invoked as \fBpre-start exec\fR or \fBpre-start script\fR
in the same way that a start action can be handled by either
\fBexec\fR or \fBscript\fR.

.TP
.BI post-start
Execute the command/script after starting the process.
The format is similar to \fBpre-start\fR.

.TP
.BI pre-stop
Execute the command/script before stopping the process.
The format is similar to \fBpre-start\fR.

.TP
.BI post-stop
Execute the command/script after stopping the process.
The format is similar to \fBpre-start\fR.

.TP
.BI "start on <event>"
Describes on what condition to start this job. Without this
section, the job can only be manually started with the
\fBinitctl(8)\fR command.

Examples:
.nf
	start on startup
	This starts immediately after boot.

	start on stopped rc3
	This starts when the 'rc3' event has stopped.
.ni

Events are matched via globbing. So a stanza of the form
.nf
	start on runlevel [2345]
.ni
would match any of runlevels 2, 3, 4, or 5.

.TP
.BI "stop on <event>"
Describes on what condition to stop this job. Without this
section, the job can only be manually stopped with the
\fBinitctl\fR command.

Examples:
.nf
	stop on runlevel 0
	This stops the job when runlevel 0 is entered.

	stop on stopping dbus ok
	This stops the job when the 'dbus' job is stopped.
.ni

Events are matched via globbing. So a stanza of the form
.nf
	stop on runlevel [!5]
.ni
would match any runlevel other than 5.

.TP
.BI daemon
Sets the daemon flag for the job. This means that the job will
fork in the background and that its PID needs to be obtained.

.TP
.BI respawn
This sets the daemon, service, and respawn falgs for the job.
The respawn flag means that the process will be restarted when
it ends.

.TP
.BI "respawn limit [count [timeout]]"
This configures respawn limits. Respawn limits only apply
if the \fBrespawn\fR flag is set for the job; setting a limit
does not automatically set respawning capability. If the
process is respawned more than  \fIcount\fR times within an
interval of \fItimeout\fR seconds, the job will be stopped
automatically, andn ot restarted. The limit defaults to 10
times within 5 seconds.

Example: respawn limit 10 120

This sets the limit for respawn to ten times within two
minutes, the historical behavior for System V init.

.TP
.BI service
\fBservice\fR means that the job has reached its goal when running.
\fBservice\fR is implied by the \fBrespawn\fR flag.

.TP
.BI instance
\fBinstance\fR means that the job starts new instances every time
it is started, even if there is another instance running. It
is the converse of \fBdaemon\fR.

.TP
.BI "kill timeout <time>"
Sets the time to wait between sending TERM and KILL signals to
\fItime\fR seconds.

.TP
.BI "normal exit <status>"
When used with \fBespawn\fR any exit codes denoted in \fIstatus\fR will
prevent a respawn of the process.

.TP
.BI "console {logged|output|owner|none}"
Describes what to do with the job's output. Valid values are:

.I logged
Redirect to logger. (the default setting)

.I output
Direct to the current stdout

.I owner
The process becomes the owner of the console, allowing it to
receive signals from the keyboard

.I none
Output is redirected to /dev/null

.TP
.BI "env <name>=<value>"
Sets an environment variable for the job.

Example: env LD_LIBRARY_PATH=/opt/app/lib

.TP
.BI "umask <umask>"
Sets the umask of the job to \fIumask\fR.

Example: umask 0755

.TP
.BI "nice <value>"
Sets the nice level of the job to \fIvalue\fR.

Example: nice 5

.TP
.BI "chroot <path>"
Changes the job's root directory to \fIpath\fR.

Example: chroot /var/empty

.TP
.BI "chdir <path>"
Changes the working directory of the job to \fIpath\fR.

Example: chdir /var/tmp

.TP
.BI "limit {as|core|cpu|data|fsize|memlock|msgqueue|nice|nofile|nproc|rss|rtprio|sigpending|stack} {unlimited|<value>}"
Changes the limit of the process to whatever is specfied.

Examples:
.nf
	limit nproc 10
	limit core unlimited
.ni

.TP
.BI "description <text>"
Describes the job. Not currently used by any \fBinit(8)\fR tools.

Example: descripton "This is a test job."

.TP
.BI "author <text>"
Author of the job. Not currently used by any \fBinit(8)\fR tools.
Example: author "Obi-wan Kennedy <bidy at whitehouse.gov>"

.TP
.BI "version <version>"
Version of the job. Not currently used by any \fBinit(8)\fR tools.
Example: version "0.0.0.0.1 test"

.TP
.BI "emits <signals>"
Describes signals emitted by the job. Not currently used by
any \fBinit(8)\fR tools. For more information on signals, see the
\fBinitctl(8)\fR man page and the \fBemit\fR option.

Example: emits spam egg ham
.\"
.SH FILES
.I /etc/event.d
The directory where event files are stored.
.\"
.SH SEE ALSO
.BR initctl (8)
.BR telinit (8)
.BR init (8)
.BR http://upstart.ubuntu.com/getting-started.html


Index: upstart.spec
===================================================================
RCS file: /cvs/extras/rpms/upstart/devel/upstart.spec,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- upstart.spec	3 Apr 2008 15:30:44 -0000	1.14
+++ upstart.spec	5 Apr 2008 00:49:00 -0000	1.15
@@ -1,12 +1,13 @@
 Name:           upstart
 Version:        0.3.9
-Release:        14%{?dist}
+Release:        15%{?dist}
 Summary:        An event-driven init system
 
 Group:          System Environment/Base
 License:        GPLv2+
 URL:            http://upstart.ubuntu.com
 Source0:        http://upstart.ubuntu.com/download/0.3/upstart-%{version}.tar.bz2
+Source1:	events.5
 Patch0:         upstart-gcc43.patch
 Patch1:         upstart-force-on-shutdown-reboot.patch
 Patch2:         upstart-tty-stack.patch
@@ -37,6 +38,9 @@
 rm -rf %{buildroot}
 make install DESTDIR=%{buildroot}
 
+mkdir -p %{buildroot}/%{_mandir}/man5
+install -m 644 %{SOURCE1} %{buildroot}/%{_mandir}/man5/events.5
+
 # libupstart and libnih aren't shipped
 rm -f %{buildroot}/%{_lib}/libupstart.*
 rm -f %{buildroot}/%{_lib}/libnih.*
@@ -75,6 +79,7 @@
 /sbin/status
 /sbin/stop
 /sbin/telinit
+%{_mandir}/man5/events.5.gz
 %{_mandir}/man8/halt.8.gz
 %{_mandir}/man8/init.8.gz
 %{_mandir}/man8/initctl.8.gz
@@ -89,6 +94,9 @@
 %{_mandir}/man8/telinit.8.gz
 
 %changelog
+* Fri Apr 04 2008 Bill Nottingham <notting at redhat.com> - 0.3.9-15
+- Add a events(5) manpage that describes event syntax
+
 * Thu Apr 03 2008 Casey Dahlin <cjdahlin at ncsu.edu> - 0.3.9-14
 - Change bug report email address to fedora-devel-list at redhat.com
 


