NEWS

0.5.0  2008-07-29  "One of those deaf-mutes"

	* The relationship between job definitions and their running
          instances has been overhauled completely.  Jobs may have
          zero or more instances, each one uniquely identified by
          their instance name which is set by expanding the argument
          to the "instance" stanza against the instance's environment.

	  For example, a job with "instance $TTY" in its definition
	  will have new instances created when started with TTY=tty1
	  and TTY=tty2, but starting again with TTY=tty1 will fail if
	  that instance is already running.

	* The default job configuration remains to be a singleton,
          however this is now accomplished simply by having the
          default for the instance stanza set to a static string.

	* Job events now include the instance name in a new $INSTANCE
          variable, and will always have $UPSTART_INSTANCE set in the
          environment of their processes.

	* Jobs may export environment from themselves into the job
          events using the new "export" stanza.

	* Events no longer have both arguments and environment,
          instead the order the environment is specified in is
          remembered and is used when matching.

	* The "start on" and "stop on" stanzas may now only be
          specified once, multiple events should be joined with the
          new "or" operator.  A new "and" operator exists as well, and
          parentheses are permitted, allowing arbitrarily complicated
          expression matches.

	* All environment from the matched start events is placed in
          the job, with the list of matched events placed in the
          $UPSTART_EVENTS variable, replacing the previous singular
          $UPSTART_EVENT variable.

	* The matches for the "stop on" stanza may refer to variables
          from the job environment, which comes from the "start on"
          stanza.

	  For example:
	      start on started apache or started httpd
	      stop on stopping $JOB

	* Job environment from the start command or events is
          available to all scripts, including "pre-stop" and "post-stop".

	* Environment from the matched stop events is only available
          to the "pre-stop" script, with the list of matched events
          placed in the $UPSTART_STOP_EVENTS variable so that the list
          of events that started the job is still available.

	* Environment is no longer lost after a respawn.

	* Environment from the kernel or initramfs may be included in
          a job by use of the "env NAME" stanza without a value set.

	* The "started" event is no longer emitted if the pre-stop
          script restarts the job, since the "stopping" event was
          never emitted.

	* By default, jobs now have the most suitable settings for
	  a daemon process that would match what they would have had
	  by calling daemon(). In particular, this means that the
	  previous "service" stanza is now the default and tasks need
	  to specify a "task" stanza.  It also means that if the job
	  really wishes to be a session leader (e.g. getty), it must
	  specify the new "session leader" stanza.

	* Processes that fork once may be supervised with the new
          "expect fork" stanza, processes that fork twice (most
          daemons) may be supervised with the new "expect daemon"
          stanza and processes that do not fork may signal readiness
          by SIGSTOP with the new "expect stop" stanza.

	* The "pid file", "pid timeout" and "daemon" stanzas have been
          removed in favour of the new functionality.

	* "respawn" now works for tasks, this will repeat the task
          until it finishes with a zero exit status or any other
          specified by "normal exit".

	* "respawn limit" now only affects automatic respawns, not
          those done by command.

	* If the main process fails to start due to exec() error, or
          other process setup error, it will not be respawned.

	* "respawn limit" may be "unlimited".

	* The "stalled" event has been removed.

	* "logd" was not maintained, and did not function correctly,
          so has been removed from the source.  The "console logged"
          stanza has also been removed.

	* New "oom" stanza allows adjustment of the OOM killer
          priority of the process and may be "never" to inhibit it.

	* The configuration directory has now changed to
          /etc/init/jobs.d

	* Configuration is still reloaded with inotify, but may be
          forced by sending init a HUP signal.

	* Support for the STOP, CONT and TERM signals has been
          removed.

	* libupstart and the native IPC mechanism has been removed,
          communication is now via D-Bus which is a new dependency.

	* The dependency on D-Bus introduces build-dependencies on
          pkg-config and Python.

	* The minimal recommended kernel version is now 2.6.24

	* The compat directory has been removed, the utilities are now
          considered part of Upstart.

	* initctl commands do not support --no-wait yet

	* initctl status with no arguments now shows all jobs.

	* initctl events no longer exists

0.3.9  2007-10-11  "Highway to the Danger Zone"

	* Fixed crasher caused by starting a job with a no-arguments event.

	* Initialisation order changed so that the control socket is opened
	  and configuration parsed after inherited file descriptors are closed
	  and the console opened.  Otherwise if we inherit fewer than the
	  standard three file descriptors (e.g. from OpenVZ) we closed our
	  own control socket, etc.  (Bug: #87173)

	* Kill all processes in a supervised process's process group so that
	  we catch looping or sleeping processes that a shell is waiting
	  for.  (Bug: #121733)

	* Missing inotify support detected correctly and warning suppressed.

	* Stanza names in configuration may no longer be placed inside quotes.

	* Fix dangling halt and poweroff symlinks when Upstart compiled
	  without --enable-compat=sysv.  (Bug: #93356)

	* Fix that --with-included-gettext did not include libintl.a
	  as it should have.  (Bug: #117848)

	* Updated hacking requirements to Automake 1.10 and Gettext 0.16.1
	  since this version of Automake makes it easier for package
	  maintainers because it causes us to ship libtool.m4 ourselves.

0.3.8  2007-03-11  "I had a little drink about an hour ago"

	* Fix an assertion error that occurred whenever a stop event for an
	  instance job was emitted.

	* Correct a bug where calling "stop" from a job without arguments
	  would stop the running job, and attempt to block until it was
	  stopped.  This can obviously never happen since it won't stop until
	  stop unblocks.

	* Add "version" and "log-priority" commands to initctl.

0.3.7  2007-03-09  "Lines of communication"

	* The "normalexit" stanza has been changed to "normal exit".

	* The "respawn COMMAND" short-cut for specifying both "respawn" and
	  "exec" in the same stanza has been removed.  Jobs that previously
	  used syntax such as:

		respawn /sbin/getty 38400 tty1

	  Should be changed to use:

		exec /sbin/getty 38400 tty1
		respawn

	  While the shortcut saved a little typing, it caused confusion and
	  hid the fact that "exec" and "script" were both options for
	  respawning services.

	* The "on EVENT" stanza has been removed, change your jobs to use
	  the identical "start on EVENT" instead.  This is because the "on"
	  stanza may be useful for other things in future.

	* Stanzas in job definitions may no longer be surrounded by single
	  or double quotes, allowing them to be turned into ordinary
	  tokens by quoting them.

	* Configuration of running jobs is no longer immediately changed
	  when the definition is changed on disk; the job must be stopped
	  first.  If the job is an instance job, all instances must be
	  stopped before an instance of the changed job definition will be
	  started.

	  This ensures that the post-stop process run when the job is stopped
	  matches the pre-start process run when it was started, and for
	  instance jobs ensures that any locking between them is identical.

	  Jobs marked for deletion, or jobs that have not yet replaced
	  another, will not ordinarily show up in the output of initctl
	  "status" or "list" unless addressed by id.  They cannot be
	  started or stopped, even when addressed by id.

	* Job definitions may safely omit "exec"/"script"; the job will stay
	  in the running state with no process until it is stopped manually
	  or by an event.

	  This allows a service to define hardware configuration; for example
	  the mixer service could restore the ALSA mixer in its pre-start
	  script and save the mixer state in its stop script.  "start mixer"
	  would restore the state, "status mixer" would show it was running
	  and "stop mixer" would save the state again and presumably mute it.

	* Sending the SIGPWR signal to init will emit the power-status-changed
	  event.  A simple job can hook this event, check the /etc/powerstatus
	  file and take further action.

	* As well as their name, all jobs now also have a unique id exported
	  in the UPSTART_JOB_ID environment variable and viewable with initctl
	  by using the "--show-ids" option to "status" or "list".

	  The unique id is changed whenever the job is reloaded from disk, or
	  whenever a new instance is started.  "start" and "stop" now default
	  to UPSTART_JOB_ID if no arguments are given (falling back to
	  UPSTART_JOB if that is not present either).  This means they act on
	  the current instance of the job, rather than spawning a new instance
	  or stopping all instances.

	  "start", "status" and "stop" also accept a new "--by-id" option
	  which makes them expect job ids as arguments instead of job names.

	* The initctl "status" and "list" commands group instances of
	  instance jobs together in their output, rather than repeating them
	  without further clarification.  E.g.:

		foo (instance)
		    (start) starting
		    (start) running, process 1000
		    (stop) post-stop, process 1050

	  The "stop" command will stop all instances when given the name of
	  an instance job; individual instances can be stopped using "--by-id"
	  after obtaining the id from "status --show-ids".

	* Wildcard patterns of job names to be listed can be given as an
	  argument to the initctl "list" command.

	* Starting and stopping jobs with initctl will now block until the
	  job reaches its goal state, outputting all status changes and
	  process ids until the goal is reached and will also output an error
	  and exit with a non-zero status if the job fails.

	  Remember that jobs default to being tasks, so "start" will actually
	  block until the job finishes and returns back to "(stop) waiting".
	  Use the "service" or "respawn" stanza to turn them into services to
	  that they only block until the "(start) running" state is reached.

0.3.5  2007-02-10  "Wear flowers in your hair"

	* Serialisation of job state between upstart processes is disabled;
	  though upstart will still re-exec itself when sent the TERM
	  signal, the new copy will not have any of the state of the old.
	  This will be restored in a later release.

	* WARNING: if you have any job declared "console owner" which is
	  run by the "stalled" event, comment out the "start on" stanza
	  before sending the TERM signal -- otherwise the newly started
	  process will start that job, which will kill your running X
	  server.

	* logd and the "console logged" (default) option are currently
	  disabled, pending large-scale changes to the way that this
	  works.

	* Job scripts have been renamed; "start" to "pre-start" and
	  "stop" to "pre-stop".

	* A new "post-start" script has been added, it's run after the
	  main process has been started and the "started" event is not
	  emitted until it finished.

	* A new "pre-stop" script has also been added, it's run when a
	  request or event comes in to stop a job, before the "stopping"
	  event is emitted and before the job is killed.  If this restarts
	  the job, it will not be stopped.

	* Job processes now have an UPSTART_JOB environment variable
	  containing the name of the job.

	* initctl start, stop and status will default to using UPSTART_JOB
	  if no arguments are given.  Therefore you can just put "stop"
	  or "start" into a job script.

	* Where a job was started or stopped by an event, the processes
	  now have an UPSTART_EVENT environment variable containing the
	  name of the event.

	* Events may now have arguments and environment variables attached,
	  these can be specified with initctl, e.g.

	  # initctl emit network-interface-up eth0 -eADDR=00:11:22:33:44:55:66

	* These arguments can be matched in the job by placing them after
	  the event name for the "start on" or "stop on" stanzas:

	  start on network-interface-up eth*

	  Additional arguments in the event are assumed to match if not
	  specified in the job definition, and wildcards may be used within
	  the job definition as shown above.

	* The arguments are also passed to the script of any job started or
	  stopped by this event as positional arguments, and the environment
	  variables are placed into the environment of the job.

	* The set of events emitted due to a job state change have been
	  completely changed.  The new events are as follows:

	  started: this is emitted once the job is running and ready, and
	  receives the job name as an argument.

	  stopped: this is emitted once the job has been fully stopped.  As
	  well as the job name, if the job terminated normally it will have
	  the "ok" argument; otherwise it will have the "failed" argument
	  followed by the name of the script that failed ("running" for the
	  main job) and either an EXIT_STATUS or EXIT_SIGNAL environemtn
	  variable indicating why it failed.

	  starting: this is emitted before the job is started (before even
	  the pre-start script is run).  Arguments are as "started".  The
	  job will not be started until this event has finished.

	  stopping: this is emitted before the job is stopped (but after the
	  pre-stop script is run).  Arguments are as "stopped".  The job will
	  not be stopped until this event has finished.

	  These events can be usefully combined as follows.

	  If the "hal" job requires "dbus" to be running, and "hal" must be
	  stopped before "dbus" may stop:

	  start on started dbus
	  stop on stopping dbus

	  If the "tomcat" job believes that it must be running before "apache"
	  can run, and should not be stopped until "apache" has been stopped:

	  start on starting apache
	  stop on stopped apache

	* The event named for the job has been completely removed; thus
	  jobs and events no longer share a namespace.

	* Jobs have goals to reach; for a task (the default), the goal is
	  to go from stopped, to started and back to stopped again.  This
	  means that when used for the "starting" or "stopping" event, the
	  entire task has to complete before the referenced job can actually
	  be started or stopped.

	  Services will normally only want the goal to be to go from stopped
	  to started; thus when used in "starting" in the example above, the
	  referenced job can be started once the service has been started
	  (and not stopped again).  A service is defined by specifying either
	  "respawn" or "service" in the definition.

	* The list of exit codes that determine whether the main process
	  failed or succeeded can be specified by the "normalexit"
	  configuration stanza.  The arguments to this stanza can be exit
	  codes or signal names, e.g.

	  normalexit 1 99 100 INT QUIT

	  Zero is implied in the list, unless the job is marked "respawn"
	  since for those jobs, this is the list of exit codes and signals
	  that cause the job to be not respawned.

	* There is no longer a respawning state, or "respawn script".  Jobs
	  will instead be stopped and started through the same scripts.

	* Jobs marked with the "instance" stanza can be started multiple
	  times; each time they are started, a new instance is created.

	* If any job whose goal is changed by an event fail to reach their
	  new goal, a further "EVENT-NAME/failed" event will be emitted once
	  the event has finished being handled.

	  This can be used to emit, for example, a "path-unmounting" event
	  and to not proceed to "path-unmounted" unless it succeeds.

	* initctl emit will block until the event has been handled; it will
	  also output job status information for any job changed by the event
	  and terminate with an exit status of 1 if any of those jobs failed
	  to reach their new goal.

	* The set of events emitted by the "telinit" compatibility command
	  have been changed.  It now only emits a single "runlevel" event,
	  and supplies the new runlevel as an argument to it.

	  You should change job files that use:

	      start on runlevel-2

	  to use the following:

	      start on runlevel 2

	  This means also that "stop on runlevel" would stop the job on
	  any runlevel change.

	* Neither the "telinit" nor "shutdown" commands now emit a
	  "shutdown" event, in fact, this event has been removed altogether.
	  "shutdown" now simply emits the appropriate runlevel event;
	  the -H and -P arguments set the INIT_HALT variable in the
	  environment of that event, just as it does in sysvinit.

	* Normal output from initctl, etc. is no longer prefixed "initctl:"

	* The "ctrlaltdel" event has been renamed to "control-alt-delete".

0.3.2  2007-02-06  "Could anybody have tampered with your luggage?"

	* Fix leak of inotify file descriptor that could allow any process
	  on the system to remove upstart's watch on its configuration
	  directory.

	* New "emits" configuration stanza, used to list events that are
	  emitted by the job itself.  Intended for use by front-ends to
	  draw event graphs and the like.

	* Dropped "depends" configuration stanza and all related code.
	  This will be replaced by the complex state mechanism.

	* Rewritten IPC code to be significantly simpler, with the goal of
	  having a stable interface once we hit the end of this milestone
	  series.

	* Rewritten configuration parser and inotify watch infrastructure
	  to be more maintainable in future.

	* Now supports systems where inotify is disabled.

	* Duplicate configuration stanzas are no longer permitted.

	* Bug fixes, especially concerning malloc failure.

0.3.1  2006-12-13  "The Gathering"

	* Compilation fixes

	* Bug fixes.

	* Massive improvement to test framework, which should make it much
	  easier to test new features.

0.3.0  2006-10-17

	* Reverted logd behaviour from previous version, it's up to the
	  init scripts to send messages to the console if they wish.

	* Compatibility programs must now be explicitly enabled by using
	  ./configure --enable-compat=sysv

	* "shutdown" and "reboot" are now considered System V compatibility
	  programs, as they emulate the behaviour of those.  Dropped some
	  added options to make them fit.

	* All programs given improved --help text.

	* "initctl" rewritten, any sub-command can be run directly by
	  making it a symlink to "initctl" itself.

	* "start", "stop" and "status" are now just symlinks to "initctl";
	  not a separate binary.

0.2.7  2006-09-20

	* logd writes received messages to the console unless "quiet" is
	  on the kernel command-line

	* runaway jobs are now caught when they start, rather than respawn,
	  so stop/start loops are caught

	* Include inotify support for compiling under glibc 2.3

0.2.6  2006-09-13

	* Fix major bug on architectures with 64-bit kernel and 32-bit
	  user-land caused by an inconsitency between the behaviour of
	  kernel's compat_sys_waitid() vs. sys_waitid() functions.

	* "halt" now only calls "shutdown -h now"

0.2.5  2006-09-09

	* "control-alt-delete" event name changed to "ctrlaltdel".

	* "initctl shutdown EVENT" added that performs the same job as
	  "shutdown" but without all the usual warnings, timings, etc.

	* "logd" has now been written, if installed this is started by init
	  before sending the "startup" call and all jobs with "console logged"
	  (the default) will have their output sent to this daemon.  It
	  currently just logs to /var/log/boot.

	* "shutdown -k" implemented.

	* The "shutdown" utility has been changed to generate "system-halt"
	  for "-H", "power-off" for "-P" and just "halt" if only "-h" given.

	* If "shutdown" is run when running under sysvinit, it will now
	  send the appropriate /dev/initctl message to allow upgrades.

	* "telinit S" implemented.

	* Instead of trying to start or stop jobs, "telinit" now just sends
	  "runlevel-X" events.

	* The "telinit" utility now ensures a "shutdown" event is sent
	  before switching to runlevel 0, 1 or 6.

	* If "telinit" is installed and init is called by the super-user,
	  "telinit" is invoked instead.

	* Basic manual pages included.

0.2.1  2006-09-01

	* Compilation fixes

0.2.0  2006-09-01

	* "shutdown", "reboot", "halt" and "poweroff" utilities provided
	  that match their traditional equivalents.

	* "start", "stop" and "status" utilities provided to start, stop
	  and query the status of jobs respectively.

	* "runlevel" and "telinit" utilities provided for compatibility.

	* "initctl list" will list active jobs.

	* Events vastly simplified to just simple strings.

	* Jobs now generate "jobname/start", "jobname/started",
	  "jobname/stop" and "jobname/stopped" events as they go through
	  state transitions.

	* Services generate a "jobname" event when they are running.

	* Tasks generate a "jobname" event when they have finished.

	* The "shutdown" utility will generate a "shutdown" event followed
	  by one of "maintenance", "reboot", "halt" or "poweroff" or any
	  admin-specified event.

	* "stalled" event generated when no jobs are running or queued.

	* "control-alt-delete" event generated when that key combination
	  is pressed

	* "kbdrequest" event generated when Alt-UpArrow is pressed

	* Runaway respawning services will now be caught.

	* init will re-exec on receipt of the SIGUSR1 signal.

0.1.1  2006-08-25

	* Minor bug fixes.

0.1.0  2006-08-24
 
	* Initial public release.