PROPOSAL: init file actions (draft 3)
Draft 3 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:
Init files now rely on the init file exit status for status
reporting and error reporting rather than English text output
(suggestion from Alan Cox and Robert Millner).
One minor problem with not specifying the output message format is
that add-on packages from ISVs will not print messages out in the same
way a distribution's init files do. That's tolerable, I guess, but
I'd like it better if ISV packages could easily integrate (in even
this small way) into every distribution. Maybe we can find a way
around this.
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
Exit status for "status" command:
0: program is running
1: program is dead and /var/run pid file exists
2: program is dead and /var/lock lock file exists
3: program is stopped
4-100: reserved for future LSB use
100-149: reserved for distribution use
150-199: reserved for application use
200-254: reserved
Exit status for "start", "stop", "restart", "reload", and "force-reload":
In error conditions, the init file should fail, print an error, and
return one of the following non-zero exit status codes.
1: generic or unspecified error (current practice)
2: invalid or excess argument(s)
3: unimplemented feature (for example, "reload")
4: user had insufficient privilege
5: program is not installed
6: program is not configured
7-100: reserved for future LSB use
100-149: reserved for distribution use
150-199: reserved for application use
200-254: reserved
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 -------------------------
Reply to: