This document describes guidelines for writing init-scripts for r2d2.

Please note that the only real requirement of r2d2 are scripts which
take "start" or "stop" as an argument. This is what most people think
is SysV-init compatibility. However, r2d2 enables you to write cleaner
and more flexible scripts than usal and that is explained in the following.


Rule 1
	If you are just about to start or stop a daemon, go into the
	sub-directory "daemon" and make a symbolic "ctrl_daemon" script.
	To set the parameters for your script, add a line to
	/etc/ctrl_daemon.conf. It's less work for you and the chance to
	get things right are higher. Example:

		cd /etc/r2d2/daemons
		ln -s ctrl_daemon  telnetd
		echo "telnet blahblahblabh" >> /etc/ctrl_daemon.conf

Rule 2
	If you can't make use of the generic script then don't start
	more than one daemon per script. 


Rule 3
	Don't use "|| exit 0" or "&& exit 0" if something fails.
	It is totally against common practice under Unix, because
	it does not even write an error message on the screen.

	Example: "test -x /usr/sbin/DAEMON || exit 0" is used by
	some distributions to exit the script if the daemon to
	be started is not there. A system administrator executing

		/etc/r2d2/xdm start

	may not expect that the script dies silently without
	starting xdm. As already said, this is against common
	practice under Unix, where usally a program is quiet as
	if it successfully. Example: "rm".

	There is a reason for distribution maintainers to exit
	in above situation. They want to remove the executable
	of a software package (to save disk-space?) without
	touching the configuration file. But with the traditional
	init-configuration via links, they cannot comment out the
	r2d2-script and thus have to exit the script. Of course
	shell-scripts are not configuration files and  r2d2 enables
	you to comment out a script in a real configuration file 
	(/etc/r2d2/runlevel.conf) anyway.

Rule 4
	Keep settings out of r2d2-scripts if possible. The scripts
	become truely upgradeble by doing this.

	Example: many distributions hard-code the IP-addresses and
	routing table into shell-scripts. r2d2 ships with two
	scripts which read configuration files instead. See 
	etc/r2d2/ifconfig and etc/r2d2/route

	It is generally very easy to read a configuration file from
	a script. The basic code is

		while read P1 P2 P3 P4  #four parameters
		do
		    UTILITY_NAME  -a $P1  -b $P2  -c $P3  -d $P4
		done < /etc/CONFIGURATION_FILE

	The while-loop is fed from the file named after "done" and
	"read" takes one line after another and assigns the words
	found to P1-P4. You can use the variable IFS to specify
	a word seperator other than the default whitespace.

        Choose an already existing format for a config file, not
	a new one. Candidates:

                Tabular format like in /etc/fstab or /etc/passwd
                Simple assignments like in /etc/hardware/isdn_dev.conf

        Avoid the STANZA format, it is very hard to parse from
        shell-scripts. Don't mix formats in one configuration file.

	Allow the setting of default parameters in your config file.

Rule 5
	Don't use "grep" to read configuration files. It's simply
	not nessassary to fork another program and it cluters up
	the code of the script.

Rule 6
	Try not to source in configuration files. Pass simple parameters 
	as arguments to the scripts in runlevel.conf.

Rule 7
	An if-statement of the form

		if [ $run_xdm = 1 ]
		then
		    start-stop-daemon --start --exec /usr/bin/X11/xdm
		fi

	is superflous because the control over starting or stopping
	a service can already be done by commenting it out in the
	configuration file /etc/runlevel.conf
	Even if not using r2d2 this statement is not necassary because
	you can remove the links to control the execution of the script.
	If that is too complicated then you seem to know why you're using
	r2d2.

	BTW, if you feel the desire to run test on evironment variables,
	please quote them. The above test should read [ "$run_xdm" = 1 ].

Rule 8
	Don't use the following code to execute a program

		[ -x /sbin/update ] && update

	_If_ you test for /sbin/update, you should execute exactly
	this file or the test makes no sense. _But_ this is another
	example of "fails silently" and against any Unix convention.
	If /sbin/update is not there, let the script bark around.
	It's vital.

#Rule 9
#	Be verbose. Use the code
#
#		[ -n "$BE_VERBOSE" ] && echo "MESSAGE"

