wiki:Doc/Make_a_service
Last modified 7 years ago

Service format

First you need to decide what kind of service you want to make for now we support xml parser? and the .i format?.

For this document I will use the .i format as an example. When making .xml files remember that &>/dev/null isn't valid xml code, you need to wrap that in CDATA blocks.

A basic service

A VERY basic service might look like this:

service servicename {

script start = {

echo "Wow, it started!"

};

}

or faster:

service servicename {

exec start = echo Wow, it started!; exec stop = echo Wow, it stopped!;

}

servicename is a simple name for the service, it can be "test" if you have it in /etc/initng/test.i, but it should be put in a category. Like /etc/initng/daemon/test, in which case servicename should be daemon/test.

Anything in the start {} block will be executed, please remember that the exit code from start {} decides if the code was started properly or not. So if you put :

exit 1

under "echo" the service will fail to start.

system/bootmisc.i is a good place to see how to run your own basic scripts

A basic daemon

A VERY basic daemon might look like this:

daemon daemonname {

exec daemon = /bin/cat;

}

Important things to remember

  • Your script should depend on system/mountroot only if you need root only, that means not /var and no /usr. If you need /var and /usr depend on system/mountfs instead.
  • This is not sysvinit, if you dont depend on whatever mounts filesystems, chances are your script wont work.
  • "exec start = /bin/whatever;" is MUCH faster than "script start = { /bin/whatever };" as the first is directly launched, while the second has to launch bash to parse whats in the block.
  • Keep your script as simple as possible, indent nicely and keep in mind that other people will probably read it.
  • We should aim to be POSIX compatible
    • no &>/dev/null (use >/dev/null 2>&1 instead)
    • no if [[ "$a" = "$b" || "$c" = "$d" ]], use if [ "$a" = "$b" ] || [ "$c" = "$d" ] instead.
    • no ==, use =

Service keywords

start

Start block, can be either one command:

exec start = /bin/true;

or it can be handled by as a script:

script start = {

echo "This works!"

};

Note that the exitcode decides whether a service fails or not.

stop

Stop block, same as Documents_Documentation_Developer_Make_a_service?.

=Daemon keywords=

daemon

Daemon line, daemons must not quit (or it will be auto restarted), also see Documents_Documentation_Developer_Make_a_service?, Documents_Documentation_Developer_Make_a_service? and Documents_Documentation_Developer_Make_a_service?.

Example:

exec daemon = /usr/bin/dbus-daemon;

As with Documents_Documentation_Developer_Make_a_service? and stop, this can also be a script (not often used). If the script returns, initng will think the daemon has died (unless you're using Documents_Documentation_Developer_Make_a_service?), so it's generally best to use exec to start the daemon if you do this.

respawn

this decides if a daemon should be restarted when it dies. Default is on.

respawn = yes;

todo, does this work on start{} blocks or only on daemon?

pid_file

The name of a file from which initng retrieves the daemon's pid. Needed for daemons which fork and return - without correct use of this, initng would think the daemon had died and keep starting more and more copies.

Example:

exec daemon = /usr/sbin/smartd; exec_args daemon = -p /var/run/smartd.pid; pid_file = /var/run/smartd.pid;

Normally you should always try to make the daemon fork and set the pid_file entry. There are two cases when you don't want a daemon to fork:

1) It does not export a pid file. 2) You really need the output of the daemon and there is not other way of getting it.

Make the daemon not fork in this case and don't add an pid_file entry. Not even in the second case! It will make Initng fail. (FIXME - this is outdated now)

Note that in recent versions (0.5.1 and later) you can specify more than one pid_file entry, and initng will try them all.

forks

(New in 0.5.1)

Tells initng whether the daemon forks. Possible values:

  • yes - the daemon forks and returns
  • no - the daemon does not forks
  • noret - the daemon forks, but the parent process carries on running until the daemon exits

If you don't include a "forks" statement, the default is "yes" if you're using pid_file or pid_of, "no" otherwise. Setting "forks=yes" and not including a pid_file or pid_of will result in an error.

Daemon and Service keywords

need

Service needs service, and should be started after it.

need = system/initial;

use

Service uses service, IF the service is in "starting" state (for example if it's in a runlevel starting it) we depend on it.

use = daemon/mysql;

require_network

Service shouldn't be started until a network interface (other than lo) is up.

exec_path

(New in 0.5.1)

Specifies possible paths to the service or daemon. The arguments to the service or daemon (if any) are supplied in a corresponding exec_args

Example:

exec_path daemon = /usr/bin/gdm /usr/sbin/gdm; exec_args daemon = -nodaemon;

exec_args

(Syntax changed in 0.5.1; in previous versions, exec was used instead of exec_path)

Decides arguments to be sent to service or daemon, example:

exec_path start = /bin/echo; exec_args start = This Works!;

or:

exec_path stop = /bin/echo; exec_args stop = Service stopped !;

or :

exec_path daemon = /usr/bin/exim; exec_args daemon = -bd -q15m;

env

Sets an environmental variable Example:

env TEST = whoho;

env_file

Loads a file containing environment variables, if it exists. Environmental variables defined by this override any defined by env and env_file_required statements. Example:

env_file = /etc/conf.d/net;

env_file_required

Loads a file containing environment variables, and fails if it doesn't exist. Environmental variables defined by this override any defined by env statements. Example:

env_file_required = /etc/conf.d/net;

nice

This sets a process'es nice level, example:

nice = -4;

suid

This sets a process'es user id, example:

suid = user;

sgid

initng >0.4.0 - not 0.4.0 This sets a process'es group id, example:

sgid = group;

delay

does this work? todo

delay = 5;

chdir

Changes directory to the specified location before launching the process, e.g:

chdir = /home/user;

chroot

Chroot to the specified directory. Not currently used by any of the shipped .i files, so check it works before you use it.

stdout

Redirects the process's stdout to a file or device, examples:

stdout = /var/log/mydaemon.log;

stdout = /dev/null;

stderr

Like stdout, but redirects the process's stderr instead.

stdall

Redirects both stdout and stderr at the same time