PROPOSAL: init file actions (draft 2)

[Daniel Quinlan <quinlan@transmeta.com>]

Draft 2 of the proposal for what arguments should be accepted by init
files and how init files should behave.  It is originally based on the
Debian policy manual and the "status" option originally came from Red
Hat.

Major changes since the last draft:

  - specification of the init file exit status (suggestion from
    Rob Millner)
  - "restart" just starts the service if it is not already running
    (answering question from Anthony Towns)
  - try to work in face of unusual environment variables
  - added standard output format

A few open questions:

 - If a warning is issued, should the return status be zero?
 - Warn on certain situations (like running "restart" on a service
   already stopped or not running)?
 - Should "reload" be optional?

Please let me know if you have any comments or concerns.

------- start of cut text --------------
Init files should accept one argument, saying what to do:

start
     start the service,

stop
     stop the service,

restart
     stop and restart the service if the service is already running,
     otherwise start the service

reload
     cause the configuration of the service to be reloaded without
     actually stopping and restarting the service,

force-reload
     cause the configuration to be reloaded if the service supports
     this, otherwise restart the service.

status
     print the current status of the service

The start, stop, restart, force-reload, and status options must be
supported by all init files, the reload option is optional.

Init files should ensure that they will behave sensibly if invoked
with start when the service is already running, or with stop when it
isn't, and that they don't kill unfortunately-named user processes. The
best way to achieve this is usually to use start-stop-daemon [1].

If a service reloads its configuration automatically (as in the case
of cron, for example), the reload option of the init file should
behave as if the configuration has been reloaded successfully.

These executable files should not fail obscurely when the configuration
files remain but the package has been removed, as the default in [the
packaging system] is to leave configuration files on the system after
the package has been removed.  Only when it is executed with the
[purge] option will [the packaging system] remove configuration files.
Therefore, you should include a test statement at the top of the file,
like this:

              test -f program-executed-later-in-file || exit 0

or take the equivalent action if the init file is not a shell script.

Init files should return an exit status of zero if the action
described by the argument has been successful.  Otherwise, the exit
status should be non-zero.  In addition to straightforward success,
the following situations are also to be considered successful:

  - reporting a problem with the "status" option
  - restarting a service (instead of reloading it) with the
    "force-reload" argument
  - running "start" on a service already running
  - running "stop" on a service already stopped or not running
  - running "restart" on a service already stopped or not running

In the following situations (this is not an exhaustive list), the init
file should fail, print an error, and return a non-zero exit status:

  - unknown arguments (additional non-standard arguments may be
    added to init scripts, but scripts should not try to accept
    any argument)
  - more than one argument (of any type)
  - user with insufficient privileges (the "status" command should
    work for most users, though)

The output format for any error messages and the "status" command is
defined as follows:

    <script-name>: <message>[: <optional detail>]
    <optional text>

For the "status" command:

    <message> => "running" | "stopped" | "dead"

For error messages:

    <message> => "error" | "warning"

All error messages should be printed on standard error.  All status
messages should be printed on standard output.

Init files should try to account for unusual environment variable
settings (such as PATH, USER, LOGNAME, etc.) and continue to work if
reasonable.

[1] assuming that start-stop-daemon or a similar program is included
    in the LSB
------- end -------------------------