usage stanza

[Petr Lautrbach]

On 10/26/2011 10:29 AM, James Hunt wrote:
> 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
>>
...
> 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.
>

'initctl usage' is something what came to my mind too, it's good idea and I'll add it.

> 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'

I would leave whole message on user, e.g. job which should not be run manually can set usage to:

usage "This job should not be run manually, if you need this see ..."

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

I'll fix that.


Thanks for you comments,

Petr
-- 
Petr Lautrbach, Red Hat, Inc.