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 _______________________________________________ pld-cvs-commit mailing list [email protected] http://lists.pld-linux.org/mailman/listinfo/pld-cvs-commit
