doc: Upstart lacks documentation

Included a README that answers the most asked questions, and pointers to other docs. All the tools have manpages now.

Upstart is still a pretty big deal and the README (I am assuming that is /usr/share/doc/upstart/README.Debian.gz) and man pages are insufficient to understand how it works. The format for configuration files in /etc/event.d/ is not documented at all, for example.

I suggest including some of the information at http://upstart.ubuntu.com/getting-started.html in the man page.

Make this the Upstream "needs more docs" bug

Here's the HTML version of a proposed manpage that attempts to explain how runlevels work in Upstart.

Other documentation we should have:

 - general overview of the Upstart system
 - configuration file documentation
 - startup(7) and other key events

Attached the event man pages.

Still need a better overview in init(8) and config file documentation in init(5) - which these refer to

New overview and config documentation

This has been fixed in Upstart 0.6.0.

0.6.0 2009-07-09 "How appropriate, you fight like a cow"

 * The licence for Upstart has been changed back to version 2 of the
   GNU GPL.

 * D-Bus 1.2.15 is now required, this is the current GIT HEAD
   pending a 1.2.16 release.

 * Configuration paths have changed. Global configuration now
   resides in "/etc/init.conf" while jobs are now configured in
   "/etc/init"

 * Job configuration filenames must now end in ".conf"

 * Default configuration files are now supplied in the "conf"
   sub-directory of the source, and installed into "/etc/init".

   These match the Debian/Ubuntu sysvinit configuration so may
   require some tweaking for other distributions, but provide an
   excellent base.

   The old example-jobs tarballs are deprecated.

 * The D-Bus interface remains unstable, to reflect this the current
   interface name has changed to "com.ubuntu.Upstart0_6" and the
   name of the job and instance interfaces have changed to match.

 * The "EmitEvent" D-Bus method gains a wait argument, when given
   as TRUE (the recommended setting) the method call will be blocked
   until all effects of the event have finished. When FALSE the
   method call will return once the event has been queued.

 * The "Start", "Stop" and "Restart" D-Bus methods of jobs and
   instances gain a similar wait argument.

 * The Upstart D-Bus object now has "version" and "log_priority"
   properties. The former is to obtain the version of the init daemon,
   the latter allows you to obtain and change the logging priority.

 * Job D-Bus objects now have "name", "description", "author" and
   "version" properties to obtain the job name and the contents of
   the equivalent job file fields for the others.

 * Instance D-Bus objects now have "name", "goal", "state" and
   "processes" properties to obtain the instance name, goal, state
   and list of running processes and their pids respectively.

 * The default D-Bus security policy now permits use of the "Get"
   methods by all users, including obtaining values of properties.

 * initctl has been rewritten with functionality more along the
   lines of Upstart 0.3.x than before; since many distributions are
   still shipping 0.3.x the summary of changes for the tool reflects
   both changes from 0.3.x and 0.5.x

 * The global "-p"/"--pid" argument has been dropped, since
   communication is over D-Bus. New "--system" and "--dest" arguments
   have been added to force communication over the system bus, and
   specify the destination, instead of using the private socket (this
   is the default when run as non-root to permit "list" and "status"
   to work for ordinary users).

 * The "-i"/"--id" and "--show-ids" options to commands have been
   dropped since jobs no longer have ids.

 * Since instances may now have names, these will be displayed in
   brackets after the job name when one is present. The output of
   the goal and state are now expressed as "start/running" instead
   of "(start) running" to disambiguate.

 * initctl "start" and "stop" now only output the final state of
   the job, not inte...

This bug was fixed in the package upstart - 0.6.0-1

---------------
upstart (0.6.0-1) karmic; urgency=low

  * New upstream release ("How appropriate, you fight like a cow")
    - my customary changes list since pointless, it's basically a
      complete rewrite.
    - Handles /bin/sh symlink disappearing. LP: #65024.
    - Boot parameters may be passed to init scripts. LP: #74664.
    - reboot implies --force during shutdown. LP: #388738.
    - reboot no longer iterates /proc/ide. LP: #92685.
    - much improved documentation. LP: #60429, #72058, #388715.

  * Merge the various upstart packages into a single package, it makes
    little sense to have it all spread out.

 -- Scott James Remnant <email address hidden> Wed, 08 Jul 2009 23:12:03 +0100

(I like the idea of upstart, so please don't consider this as bashing!)

I'd like to see this bug re-opened, because there's still not sufficient documentation and some aspects of upstart indicate that it may be immature for a LTS release (IMHO).

Some items I'd like to see addressed:
- a graphing tool to help debug upstart events/jobs
(a tool to process all related files, turning out a dot file so graphviz can make a pretty graph would be great)
- a tool showing (a graph of) the sequence of events and jobs perfomed by upstart until that moment since startup
- better documentation, in the form of a complete discussion/tutorial of the (ideal) upstart system
- an upstart tutorial for sysadmins who are used to sysV init scripts

One of the things that caused me to doubt the readiness for LTS is the lines in mountall(8):
This is a temporary tool...
...you should not rely on its behaviour.

Another is the strange mixing of SysV initscripts with upstart jobs, it's seriously confusing! Lack of proper documentation in this situation doesn't help.

I notice quite a few unanswered upstart discussions on the forum:
http://ubuntuforums.org/showthread.php?t=1438501
http://ubuntuforums.org/showthread.php?t=1349053
http://ubuntuforums.org/showthread.php?t=1348131

are there so few people who can easily answer such queries?
If I were to run into trouble with upstart, where should I turn for help? it seems Canonical is one of the few places one can turn to for help, is this open source vendor lock-in?

Cheers

Simon

On Mon, 2010-04-12 at 13:52 +0000, Simon Oosthoek wrote:

> I'd like to see this bug re-opened, because there's still not sufficient
> documentation and some aspects of upstart indicate that it may be
> immature for a LTS release (IMHO).
>
If there are key areas of missing documentation that should be included
in the tarball, please open new bugs for each individual case - don't
just reopen this one.

New bugs are key here, because that will allow the tasks to be assigned
to different people who are good at that documentation.

This bug refers to the complete lack of *any* documentation - which is
clearly no longer true, there are detailed manual pages, README, etc.
now.

So I've marked this back as "Fix Released" - but please don't let that
deter you for opening new bugs for the specific missing documentation as
noted above <g>

> Some items I'd like to see addressed:
> - a graphing tool to help debug upstart events/jobs
> (a tool to process all related files, turning out a dot file so graphviz can make a pretty graph would be great)
>
This is covered by bug #203417

> - a tool showing (a graph of) the sequence of events and jobs perfomed by upstart until that moment since startup
>
This is partially covered by bug #388746, it's also worth noting that a
big planned feature for the next version is to maintain a journal of
Upstart's activities for debugging purposes - which would also be ideal
for this kind of graph!

> - better documentation, in the form of a complete discussion/tutorial of the (ideal) upstart system
>
Can't agree more; please open a bug for that - if you know of anyone who
can write something like that, it'd be appreciated. This is fairly
difficult to put into the traditional "man" format, and "info" doesn't
really seem appropriate either.

Perhaps a PDF or similar?

> - an upstart tutorial for sysadmins who are used to sysV init scripts
>
Likewise, a bug opened for this would be most welcome - and somebody to
write it. Suspect it has the same format possibilities as the one
above.

> One of the things that caused me to doubt the readiness for LTS is the lines in mountall(8):
> This is a temporary tool...
> ...you should not rely on its behaviour.
>
You misunderstand the meaning of LTS. LTS means we'll provide long-term
support for it - mountall can be supported in its current state.
However it's behaviour may change in maverick, and it'll vanish at some
point in the future.

Unfortunately in the case of the boot, we're making major changes every
six months as this is an area under rapid development and improvement.
Our only two options would be never to release any of our work (in which
case, we'd get no testing and not find the issues we've found) - or to
never release an LTS until it's finished.

We don't have two branches of Ubuntu.

> Another is the strange mixing of SysV initscripts with upstart jobs,
> it's seriously confusing! Lack of proper documentation in this situation
> doesn't help.
>
This is always going to be a feature of Upstart, since the LSB still
mandates init scripts for LSB compliant software. Until LSB is changed
to mandate Upstart jobs, and until the previous versions of LSB have
been obso...