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

[Casey Dahlin]

On Mon, Feb 08, 2010 at 05:54:23PM -0600, Saint DanBert wrote:
> Folks,
>    I really REALLY want to help with upstart documentation, but I'm dashed if I
> can find the first brick on the yellow-brick-road. I feel sure that somewhere in
> the alphabetical list of details volume-G there is a "Getting Started" page and
> that I'm too much of a noob to see it or find it.
> 

Its true, and common these days really. Upstart is better then a lot of
projects, sad to say.

Some of it is historic. Scott has been quite militant about Upstart's status as
a "pre-1.0" project in the past, and has thus discouraged documentation on the
grounds that it would prevent changing the things that were documented. Every
major release of upstart has violently and fundimentally changed its operating
principle.

> ** man init tells me about 'upstart' and /etc/init.conf and /etc/init/*.conf

There's no /etc/init.conf because there's nothing to go in it :) Its just sort
of reserved.

> 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...?...?...?...?...?
> 

Try Scott's blog. http://netsplit.com . Fun, huh? Incomplete though.

> Some thoughts, but I'd really like to find the un-garbled and un-varnished word.
> (Yes, I can mostly read the code, but is that my only choice?)
> 
> A.  I create some files on disk in the required places

Job definition files.

> Q1 -- what are those places?

All in /etc/init/

> B. Power on ... la, la, GRUB2, la,  la ... 'init' runs and it is the upstart
> edition because that is the binary found through the boot loader processing.
> Q4 -- are there parameters to the upstart edition of init at the command line?

Not exactly. You can specify options to the init process with init=/sbin/init
--some-option (this has always been true). man 5 init covers candidates, but
--debug is the most commmon.

> Q5a -- specifically, are there logging or debug or event-trace options ?

see above.

> Q5b -- how do I enable any logging or debug or event-trace options ?
> (You don't learn anything from 'man init'.)
> 

see above.

> C. The upstart "pin ball wizard" begins to dance in response to events
> Q6 -- some events are hardware and driver specific, right?

Sorta-kinda-not really....

> Q7 -- some events come from the kernel, right?

not directly, no.

> Q8 -- some events come from other events, right?

no.

> 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?
> (If I understand, it is /etc/init/*.conf that configures what happens in
> response or reaction to any given event, right?)

Yes.

> Q10b -- if a driver/module throws events for upstart, is there coordination so
> that driver events don't interfere among themselves?
> Q10c -- can I create or define my own driver level events or is there some sort
> of "clearing house"?
> Q10d -- repeat 10b and 10c for kernel internel events
> Q10e -- repeat 10b and 10c for any other event creators
> 

Ok, events come from two places:

1) From within upstart. For example, when upstart runs something, it creates
starting/started/stopping/stopped events.
2) By telling upstart to emit an event. The easiest way is $ initctl emit
any-name-you-like SOME_ARG=SOME_VALUE SOME_OTHER_ARG=SOMETHING_ELSE

Under the surface initctl emit acts on com.ubuntu.Upstart over DBus (might be
worth poking that with d-feet if you want to know how upstart works).

Most of the driver/kernel stuff is just udev actions which run initctl.

> D. One upstart response causes ACPI and UDEV and HAL(deprecated?) and friends to
> begin their own dances.

All that happens when events are emitted is jobs change goal. By jobs I mean
things defined in /etc/init/

> Q11 -- One pin-ball machine launches a second pin-ball machine... (visions of a
> huge room filled with ping-pong balls and mouse traps.)
> 
> E. Somewhere all of the above interacts with X11 ... and a miracle happens
> (except it does not happen on my tablet)
> Q12 -- how do I see (a) what is happening, and (b) what went wrong, and (c)
> share what I see with others who might help fix things?
> 

Try that init argument mentioned above. Its quite noisy.

> F. Things happen on my laptop [eg, low battery or battery charged, etc] and I
> see a desktop [gnome] pop-up announcing some happening.
> (there is no Q13)
> Q14 --  This is not upstart but some form of "notify" widget that is part of the
> desktop suite and extensions, right?

Yes. None of that has anything to do with Upstart.

--CJD