PROPOSAL: init file actions (draft 5)
Draft 5 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.
For the moment, I removed some of the numerical assignments for init
file exit codes.
Major changes since the last draft:
- reserve entire high bit of exit status
- reserve region for status action
Seems like a good idea, but not added:
- standard shell command "functions" for writing init scripts
To do:
- pin down when output/errors should/must be displayed if at all
(display != printf, it may be GUI or even only logged)
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
return (and optionally display) 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 codes:
code action meaning
---- ------ -------------------------------------------------------
0 all success (for "status", it means the program is running)
1 all unspecified error
2 status program dead, /var/lock lock file exists
3 status program stopped
4 status program dead, /var/run pid file exists
A-B - reserved for LSB (for status)
C all command line usage error
D all unimplemented feature (e.g., reload is not implemented)
E all permission denied
F all program not installed
G all configuration error
H-I - reserved for LSB use
J-K - reserved for distribution-specific use
L-127 - reserved for application-specific use
128-254 - high bit reserved ("got signal XYZ")
In a text environment, all error messages should be printed on
standard error. All status messages should be printed on standard
output. (This provision may be removed in a future draft.)
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: