seeking "Brick #1" on the Upstart yellow-brick-road

Scott James Remnant scott at netsplit.com
Tue Feb 9 10:27:29 GMT 2010


Obviously the biggest problem with writing documentation as somebody who
is familiar with a system, or indeed as somebody who designed it and
wrote it in the first place, is that you forget what people *don't* know
about it.

The best way to help is to tell us what you don't know, and as we figure
out how to answer those questions, we can also work out how to include
the answer in the documentation so you never need to ask.

I'll try to help here.


On Mon, 2010-02-08 at 17:54 -0600, Saint DanBert wrote:

> ** man init tells me about 'upstart' and /etc/init.conf and /etc/init/*.conf
> ** man upstart and man 7 upstart takes me to the same page. Neither page tells
> me in direct language that the upstart implementation of 'init' provides a new
> program to replace the System-V 'init' with the same name.
> 
This is a tricky one.  The Upstart manual pages should try to document
the system without reference (where possible) to System V, it shouldn't
be necessary to learn the previous system to learn the new one.

Consider most new users who've never used System V.

There is coverage of the compatibility between them in the runlevel(7)
manual page, which is referenced from init(8):

   System V compatibility
       The  Upstart  init(8)  daemon  does not keep track of runlevels itself,
       instead they are implemented entirely  by  its  userspace  tools.   The
       event emitted to signify a change of runlevel is the runlevel(7) event.
       For more information see its manual page.

How could this text be improved do you think?

> ** SURPRISE!! attempts to man init.conf say "noting found"
> ** DOUBLE SURPRISE!!  attempts to  less /etc/init.conf say "no such file"
> ** TRIPLE SURPRISE!!  attempts to locate init.conf   dutifully finds
> rc-sysinit.conf from the upstart tar-ball. Otherwise, "no such file".
> Is this an error in the man page or is my installation missing files?
> How would I know? Where do I go to find out?  [grin -- I'm writing this.]
> ** what do I find in /etc/init/*.conf -- again, nothing named 'init.conf'
> By The Way, there is nothing called README or similar either.
> 
This file is not used, it's probably confusing that the manual page
mentions it ;-)

Did you see the following paragraph at the top?

       Processes managed by init are known as jobs and are defined by files in
       the  /etc/init  directory.  See init(5) for more details on configuring
       Upstart.

man 5 init would have yielded the manual page you were looking for.  I
improved this text in 0.6.5 in a hope more people would follow it -
sounds like it didn't work for you?

I also made sure that the page shows up in "man -k upstart" output:

dh_installinit (1)   - install upstart jobs or init scripts into package buil...
init (5)             - Upstart init daemon job configuration
init (8)             - Upstart process management daemon
upstart (7)          - Upstart process management daemon
upstart-udev-bridge (8) - Bridge between Upstart and udev


> So I fetched the upstart-0.6.3 tar ball from http://upstart.ubuntu.com/. In
> viewing various README and accompanying text files, I find lots of build and job
> and task details but almost nothing about HOW DOES IT WORK...?...?...?...?...?
> 
This is covered in "Events" in the init manual page, I hope.

> Q4 -- are there parameters to the upstart edition of init at the command line?
> Q5a -- specifically, are there logging or debug or event-trace options ?
> Q5b -- how do I enable any logging or debug or event-trace options ?
> (You don't learn anything from 'man init'.)
> 
Huh?  Again, from the init manual page:

OPTIONS
       Options are passed to init(8) by placing them on  the  kernel  command-
       line.

       --verbose
              Outputs verbose messages about job state changes and event emis‐
              sions to the system console or log, useful for debugging boot.

> C. The upstart "pin ball wizard" begins to dance in response to events
> Q6 -- some events are hardware and driver specific, right?
> Q7 -- some events come from the kernel, right?
> Q8 -- some events come from other events, right?
> Q9 -- Having stated the obvious, how do I know which of these are (a) possible,
> and (b) happening on my specific hardware and kernel?
> Q10a -- where is configuration of the origins for this flood of events?
> 
There are no limits to the source of events.

I've generally suggested that events be documented with manual pages in
section 7, e.g.

all-swaps (7)        - event signalling that all swap partitions have been ac...
control-alt-delete (7) - event signalling console press of Control-Alt-Delete
filesystem (7)       - event signalling that filesystems have been mounted
keyboard-request (7) - event signalling console press of Alt-UpArrow
local-filesystems (7) - event signalling that local filesystems have been mou...
mounted (7)          - event signalling that a filesystem has been mounted
mounting (7)         - event signalling that a filesystem is mounting
power-status-changed (7) - event signalling change of power status
remote-filesystems (7) - event signalling that remote filesystems have been m...
runlevel (7)         - event signalling change of system runlevel
started (7)          - event signalling that a job is running
starting (7)         - event signalling that a job is starting
startup (7)          - event signalling system startup
stopped (7)          - event signalling that a job has stopped
stopping (7)         - event signalling that a job is stopping
virtual-filesystems (7) - event signalling that virtual filesystems have been...

Scott
-- 
Have you ever, ever felt like this?
Had strange things happen?  Are you going round the twist?
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/upstart-devel/attachments/20100209/7e941346/attachment-0001.pgp 


More information about the upstart-devel mailing list