SVN: rc-scripts/branches/upstart_native/doc: . make-html upstart.txt

[jajcus]

Author: jajcus
Date: Fri May  7 08:39:04 2010
New Revision: 11393

Added:
   rc-scripts/branches/upstart_native/doc/upstart.txt   (contents, props changed)
Modified:
   rc-scripts/branches/upstart_native/doc/   (props changed)
   rc-scripts/branches/upstart_native/doc/make-html
Log:
- some documentation for using rc-scripts with upstart

Modified: rc-scripts/branches/upstart_native/doc/make-html
==============================================================================
--- rc-scripts/branches/upstart_native/doc/make-html	(original)
+++ rc-scripts/branches/upstart_native/doc/make-html	Fri May  7 08:39:04 2010
@@ -2,3 +2,4 @@
 
 jade -t sgml -d polski.dsl rc-scripts.docb
 #jade -t sgml -d polski.dsl test-ogonki.docb
+rst2html upstart.txt upstart.html

Added: rc-scripts/branches/upstart_native/doc/upstart.txt
==============================================================================
--- (empty file)
+++ rc-scripts/branches/upstart_native/doc/upstart.txt	Fri May  7 08:39:04 2010
@@ -0,0 +1,183 @@
+===================================
+Upstart event-based service startup
+===================================
+
+This version of rc-scripts support Upstart event-based service startup. This
+can co-exist with old-style startup scripts.
+
+Enabling/disabling event-base service startup
+---------------------------------------------
+
+Upstart event-based service startup may be disabled on boot time
+by using a ``pld.no-upstart`` kernel command-line option.
+
+An init script may be called with ``USE_UPSTART=no`` environment variable
+to disable special upstart-related processing – this way one may use
+``/etc/rc.d/init.d/$service start`` to start a service even if upstart job 
+for that service is present.
+
+``USE_UPSTART=no`` can also be places in ``/etc/sysconfig/system``
+configuration file.
+
+Available events
+----------------
+
+Ubuntu-compatible system events
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+all-swaps
+        when swaps from ``/etc/fstab`` are activated
+
+filesystem
+        when basic filesystem hierarchy (FHS) is mounted
+        NOTE: currently it doesn't wait for network filesystems!
+
+local-filesystems
+        when all local filesystems are mounted and initialized
+
+root-filesystem
+        when root filesystem is mounted r/w and initialized
+
+virtual-filesystems
+        when virtual filesystems (/proc, /sys, etc.) are mounted
+
+PLD-specifi system events:
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+pld.sysinit-done
+        when rc.sysinit finished its job
+
+pld.shutdown-started
+        when rc.shutdown starts
+
+pld.network-starting
+        just before network initialization is started
+
+pld.network-started
+        when network is initialized
+
+pld.network-stopping
+        just before network shutdown is started
+
+pld.network-stopped
+        when network configuration is shut down
+
+Jobs
+~~~~
+
+The standard Upstart events are available for job control:
+starting(7) started(7) stopping(7) stopped(7)  (see man pages)
+
+As relying on job name is not good enough when several alternative
+implementations of a service are available, the start*/stop* jobs
+may have extra 'SERVICE' variable attached. SERVICE variable contains
+the generic service name, which can be used like this::
+
+  start on started SERVICE=syslog
+
+Job events and enabling/disabling event-base service startup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please note that relying on events not raised by PLD service jobs
+or scripts (like 'startup') will make job ignore the 'pld.no-upstart'
+setting.
+
+
+Writing Upstart job descriptions
+--------------------------------
+
+Job description files in ``/etc/init`` are not only the recipes to start 
+a service, but also configuration files for that service. Keep that in mind
+when writing the ``*.conf`` files. No complicated logic, that can change from 
+a release to a release, should be implemented there, the script should be
+readable, basic configuration settings easy to find and no upstart-controlled
+settings (like resource limit)  reimplemented in the script or started daemon 
+arguments.
+
+The syntax of the ``/etc/init/*.conf`` files is described in the init(5) man
+page.
+
+Instead of using ``/etc/sysconfig/$service`` files put the service
+configuration directly into the ``*.conf`` file. When 'env' stanza is used for
+that, the value may be overridden when starting the job with initctl.
+
+Simple example, the job description for syslog-ng::
+
+  start on pld.network-started
+  stop on pld.shutdown-started
+  
+  env SERVICE=syslog
+  export SERVICE
+  
+  respawn
+  
+  console output
+  
+  exec /usr/sbin/syslog-ng -F -f /etc/syslog-ng/syslog-ng.conf
+
+
+Updating init scripts
+---------------------
+
+Parts of the system will still expect ``service $name`` or even, directly,
+``/etc/rc.d/init.d/$name`` scripts working. Also, LSB expects compatible
+init scripts in /etc/init.d. For this still to work, an upstart-controlled
+service is expected to have its ``/etc/rc.d/init.d/$name`` script also present. 
+It must also be named exactly as the main upstart job for the service.
+
+The script must be a bit modified (in comparison to the traditional init
+scripts) to make use of the upstart features.
+
+For the start/stop/status/reload commands to work the script should include a
+``upstart_controlled`` command placed before commands are handled (and after
+``/etc/rc.d/init.d/function`` was included). This command (shell alias actually) 
+will be ignored when upstart boot control is disabled or no upstart job is
+available for the service. Otherwise it will implement the basic LSB commands
+and exit.
+
+Sometimes some commands must be implemented in a special way (not all services
+may understand SIGHUP as a signal to reload their configuration) or extra
+commands are provided (like 'configtest'). In such case 'upstart_controlled'
+should be given a list of commands to implement. If the first argument of the
+script was not one of the listed commands, processing will continue past
+'upstart_controlled' call and the commands may be handled by the init script.
+
+The minimal init script, for a service which will be controlled by upstart
+only would be::
+
+  #!/bin/sh
+  
+  . /etc/rc.d/init.d/functions
+  
+  upstart_controlled
+  
+  echo "Service available only via upstart boot"
+  exit 3
+
+Minimal change to an existing PLD script to handle upstart control is to add::
+  
+  upstart_controlled
+
+before the usual::
+
+  RETVAL=0
+  # See how we were called.
+  case "$1" in
+    start)
+
+Sometimes other upstart jobs will rely on a service started by the traditional
+init script. In such case, the script should emit appropriate events.
+
+e.g.::
+
+	msg_starting "syslog-ng"
+	emit starting JOB=_ SERVICE=syslog
+	daemon /usr/sbin/syslog-ng -f /etc/syslog-ng/syslog-ng.conf $OPTIONS
+	emit started JOB=_ SERVICE=syslog
+	RETVAL=$?
+
+The ``emit`` function does nothing when upstart-controlled boot is disabled (not
+to trigger any upstart jobs), otherwise it calls ``/sbin/initctl emit`` ...
+
+--
+ vi: tw=78 ft=rst spell spl=en