usage stanza

[James Hunt]

On 24/10/11 16:36, Petr Lautrbach wrote:
> Hello,
> 
> I would like to add to upstart new stanza called 'usage' with
> following syntax:
> 
> usage <usage message>
> 
> It's intended to help administrator to better understand how to control
> jobs which depends on various variables, e.g:
> 
> let's have tty job with exec stanza:
> 
> exec /sbin/mingetty $TTY
> 
> 
> Now, if I try to start, stop or show status of this job I see:
> # status tty
> status: Unknown parameter: TTY
> 
> So I have to open /etc/init/tty.conf and check what does it mean.
> With usage stanza like this:
> usage 'tty TTY=/dev/ttyX  - where X is console id'
> 
> I will see:
> # status tty
> status: Unknown parameter: TTY
> usage: tty TTY=/dev/ttyX  - where X is console id
> 
> 
> There is attached patch which is functional proposal of this feature.
> 
> Thanks,
> 
> Petr
> 
> 
> 
Hi Petr,

This looks like a useful feature. I think it would be beneficial though to also have an "initctl
usage <job>" (or maybe "initctl info <job>" [*] which could eventually also include 'description',
'author' and 'version'?) command so that users can request the usage statement before any errors occur.

As a convenience to users, job_class_get_instance() should probably prepend 'usage: <job> ' so that
your .conf file could simply specify:

	usage 'TTY=/dev/ttyX  - where X is console id'

And the returned message would become:

	'usage: tty TTY=/dev/ttyX  - where X is console id'

Also, it's worth noting that although this feature handles the case where jobs specify the
'instance' keyword, it doesn't handle the case where a job does not specify 'instance' but does
alter its behaviour based on particular environment variables (or values in /proc/cmdline say). Most
jobs that do modify their behaviour on Ubuntu atleast are not designed to be started by users
manually so I think we can ignore those (the exception on Ubuntu is apport.conf).

There are a couple of compiler errors (actually warnings) that need to be fixed when you configure
like this:

http://upstart.ubuntu.com/cookbook/#enable-full-compiler-warnings

Kind regards,

--
James Hunt

[*] - we do also have the 'initctl show-config' command of course, but that currently only shows
non-free text stanza information. Added to which if we change that command, we may need to update
initctl2dot.py which parses its output.

____________________________________
http://upstart.ubuntu.com/cookbook
http://upstart.ubuntu.com/cookbook/upstart_cookbook.pdf