Differences between revisions 6 and 7
Revision 6 as of 2006-11-29 12:50:43
Size: 5507
Editor: scott
Comment: finish up spec
Revision 7 as of 2011-08-26 04:10:17
Size: 5507
Editor: localhost
Comment: converted to 1.6 markup
No differences found!

Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.

Summary

Events are currently simple strings without any further details. This specification proposes extended the event structure to contain arguments and environment variables, and how those are matched in and delivered to jobs.

Rationale

While the current event allows for simple things such as "control alt delete pressed" and "battery critical", it does not allow for events such as "block device hda1 added". This is greatly desirable to receive events from things like udev and ifupdown.

Use cases

  • Devices being added and removed from the system should emit generic events, with the name of the device and further information about it available.
  • For truly race-free processing, it would be ideal to place as much information in the event as possible (such as network card information). Otherwise the job would need to look the information up, and it may have changed from when the event was emitted.

Scope

The scope of this specification is limited to the content of the event structure, the matching of that structure and how we intend for that to be exposed to jobs. The actual implementation of associating jobs with events is described in the GoalChangeEvent specification.

Design

Names

  • The names of events will remain as they are now, a simple string.
    startup
    shutdown
  • We will continue to suggest that the '.' and '/' characters are reserved for namespacing.
    lsb.fhs-filesystem.mounted
    lsb.network.up
    ~scott/iaudio/connected
  • The event name is passed to scripts in the UPSTART_EVENT environment variable for any process.

    pre-start script
        [ $UPSTART_EVENT = "startup" ] || stop
    end script
  • Matching in the job definition is always exact.
    start on startup

Arguments

  • Events may have zero or more positional arguments, which are also simple strings.
    block-device-added hda
    path-mounted /usr hda
  • These may be matched in the job description, any non-specified arguments are assumed to match.
    start on block-device-added
    start on path-mounted /usr
  • Glob matching may be used.
    start on block-device-added hd*
  • The positional arguments are passed to the job's scripts as positional arguments.
    start on path-mounted
    script
        case "$1" in
        /var)
            remount_tmpfs
            ;;
        /usr)
            unlock_usr_jobs
            ;;
        esac
    end script
  • The arguments are not appended to binaries the job executes directly, scripts must be used for that.
    start on path-mounted
    script
        exec /some/binary "$@"
    end script
  • Arguments are passed on the initctl command-line.

    initctl emit block-device-added hda

Environment

  • Events may have zero or more named arguments, which are simple strings in both name and value.
    IF_NAME=eth0
    IF_ADDR=00:12:79:59:8D:38
  • They are placed in the environment of any process called.
    pre-start script
        [ $IF_NAME != lo ] || stop
    end script
  • Environment variables are passed as options to initctl..

    initctl emit network-device-added eth0 -D IFNAME=eth0 -D IFADDR=00:12:79:59:8D:38
  • There is some overlap with position arguments. The recommendation would be that positional arguments are used for important information that is frequently checked, and the environment for ancillary information that is sometimes useful.

Implementation

Code

Code changes are primarily limited to init/event.c and init/event.h.

The Event structure will be redefined as:

  • typedef struct event {
            NihList  entry;
    
            char    *name;
            char    *args[];
            char    *env[];
    } Event;

Both of these lists will be NULL-terminated as in other places in upstart.

The event_match function will be extended to compare arguments of both events, allowing arguments to be present in the first event that are not present in the second event. The configuration file parsing code will need to accept multiple arguments to the start on and stop on stanzas.

In order for the event name and environment to be exposed to the job processes, process_setup_environment in init/process.c will be extended to seed the appropriate variables from the job's goal change event (set as defined by GoalChangeEvent).

Arguments will be passed by modifying job_run_script in init/job.c to append the arguments to the script command run. Optionally we may also extend job_run_command so that if a shell is used, the arguments are also appended to that.

libupstart will be modified to include arguments and environment variables in the UPSTART_EVENT_QUEUE command.

emit_action in util/initctl.c will need to be modified to read further arguments and options from the command line, and seed the libupstart command appropriately.

Data preservation and migration

These changes are backwards compatible with the previous behaviour.


CategorySpec

EventStructure (last edited 2011-08-26 04:10:17 by localhost)