procd init scripts

A procd init script is similiar to an old init script, but with a few differences:

• procd expects services to start as if they were to run in the foreground, but of course procd runs them the background.
• Different shebang line: #!/bin/sh /etc/rc.common
• procd expects that shell variable (not environment variable) initscript is set to the path of the script that invoked it
• Explicitly use procd USE_PROCD=1

Example:

#!/bin/sh /etc/rc.common
 
USE_PROCD=1

Init script has to handle two main tasks:

1. Define current configuration (state) for service instance(s)
2. Specify when (and optionally how) to reconfigure service

Defining configuration is handled in the start_service(). For each instance to be run it has to specify service command and all its parameters. All that info is stored internally by procd. On a single change (compared to the last used configuration) procd restarts a service.

Init script has to specify all possible procd events that may require service reconfiguration. Defining all triggers is done in the service_triggers() using procd_add_*_trigger helpers.

Optionally init script may handle service reconfiguration process on its own. It's useful for services that don't require complete restart to use new configuration. It can be handled by specifying custom reload_service() which prevents start_service() from being called and so stops procd from restarting service.

The purpose of start_service() (see next section to see when it's called) is to define instance(s) with:

1. Command to execute to start service
2. Information on what to observe for changes (e.g. files or devices) - optional
3. Settings that procd should use (e.g. auto respawning, logging stdout, user to use) - optional

The above information is stored by procd as a service instance state. On every relevant system change (e.g. config change), start_service() is called by designed triggers. If it generates any different state (e.g. command will change) than the previous one, procd will detect it and restart the service.

Defining service instance details is handled by setting parameters. Some values are set directly in the start_service() (like command) while some are determined by procd (like file and file hash). There are two helpers for setting parameters:

1. procd_set_param()
2. procd_append_param()

The below example lists supported parameters and describes them. For implementation details see the procd.sh.

start_service() {
         procd_open_instance [instance_name]
         procd_set_param command /sbin/your_service_daemon -b -a --foo # service executable that has to run in **foreground**.
         procd_append_param command -bar 42 # append command parameters
 
         # respawn automatically if something died, be careful if you have an alternative process supervisor
         # if process exits sooner than respawn_threshold, it is considered crashed and after 5 retries the service is stopped
         # if process finishes later than respawn_threshold, it is restarted unconditionally, regardless of error code
         # notice that this is literal respawning of the process, not in a respawn-on-failure sense
         procd_set_param respawn ${respawn_threshold:-3600} ${respawn_timeout:-5} ${respawn_retry:-5}
 
         procd_set_param env SOME_VARIABLE=funtimes  # pass environment variables to your process
         procd_set_param limits core="unlimited"  # If you need to set ulimit for your process
         procd_set_param file /var/etc/your_service.conf # /etc/init.d/your_service reload will restart the daemon when these files have changed
         procd_set_param netdev dev # likewise, but for when dev's ifindex changes.
         procd_set_param data name=value ... # likewise, but for when this data changes.
         procd_set_param stdout 1 # forward stdout of the command to logd
         procd_set_param stderr 1 # same for stderr
         procd_set_param user nobody # run service as user nobody
         procd_set_param pidfile /var/run/somefile.pid # write a pid file on instance start and remove it on stop
         procd_set_param term_timeout 60 # wait before sending SIGKILL
         procd_close_instance
}

stop_service() is only needed when you need special things to stop your service. stop_service() is called before procd killed the service.

If you want to add a check after procd has sent the terminate signal (e.g. wait for the process to be really gone), you can define an extra function service_stopped().

WARNING: initscripts will run while building OpenWrt images (when installing packages in what will become a ROM image) in the host system (right now, for actions “enable” and “disable”). They must not fail, or have undesired side-effects in that situation. When being run by the build system, environment variable ${IPKG_INSTROOT} will be set to the working directory being used. On the “target system”, that environment variable will be empty/unset. Refer to “/lib/functions.sh” and also to “/etc/rc.common” in package “base-files” for the nasty details.

While start_service() takes care of setting service instances states and submitting them to the procd (for a potential service restart), it has to be explicitly called to do so. In most cases it should happen on some related change.

That's where service_triggers() comes in handy and allows specifying triggers. Most system important changes result in generating events that service_triggers() can use for triggering various actions. There are multiple procd_add_*_trigger() helpers for that purpose.

Every configurable service has to specify what system changes should result in its reconfiguration. Those events should be defined in the service_triggers() using available helpers. When related procd service event occurs it will result in executing /etc/init.d/<foo> reload.

Example:

service_triggers()
{
        procd_add_reload_trigger "<uci-file-name>" "<second-uci-file>"
        procd_add_reload_interface_trigger <interface>
        procd_add_reload_mount_trigger <path> [<path> ...]
}

See use cases of procd_add_interface_trigger, procd_add_reload_trigger, procd_add_reload_mount_trigger in the OpenWrt packages repository.

In older versions of OpenWrt, a system called “ucitrack” attempted to track UCI config files, and the processes that depended on each of them, and would restart them all as needed. This too, is replaced with ubus/procd, and expanded to allow notifying services when network interfaces change.

Sometimes service state may depend on information that doesn't have any events related. This may happen e.g. with service native configuration files that don't get build using UCI config.

In such cases procd should be told to use relevant config file using procd_set_param file /etc/foo.conf. After every config file modification /etc/init.d/foo reload should be called manually.

By default (without reload_service() specified) calling /etc/init.d/<foo> reload results in running service_start() and procd comparing states. In some cases a more complete control over reload action may be needed thought.

If some service requires a restart when reload is called, it can be implemented as follows:

reload_service()
{
        echo "Explicitly restarting service, are you sure you need this?"
        stop
        start
}

j

Some services may support reloading configuration without a complete restart. It's usually implemented using `SIGHUP` or similar signal.

OpenWrt comes with a procd_send_signal() helper that doesn't require passing PID directly. Example:

reload_service() {
         procd_send_signal service_name [instance_name] [signal]
}

The signal argument is SIGHUP by default and must be specified by NAME. You can get available signals using kill -l.

The service_name is the basename of the init.d script, e.g. yourapp for the /etc/init.d/yourapp.

The instance_name allows specifying custom instance name in case it was used like procd_open_instance [instance_name]. If instance_name is unspecified, or '*' then the signal will be delivered to all instances of the service.

Note You can also send signals to named procd services from outside initscripts. Simply load the procd functions and send the signal as before.

#!/bin/sh
. /lib/functions/procd.sh
procd_send_signal service_name [instance_name] [signal]

procd can isolate services using various Linux features typically used for (slim-)containers: chroot and namespaces (and limits, seccomp, capabilities as well as setting PR_SET_NO_NEW_PRIVS, see Service Parameters).

See use cases of procd_add_jail.

Set PROCD_DEBUG=1 to see debugging information when starting or stopping a procd init script. Also, INIT_TRACE=1 /etc/init.d/mything $action Where $action is start/stop etc.

• r39617 firewall3
• r40635 radsecproxy
• r40674 xupnpd
• r40785 shairport
• r40997 igmpproxy
• Create a sample procd init script

The following table contains a listing of the possible values to procd_set_param() and a description of their effects. List values are passed space-separated, e.g. procd_set_param env HOME=/root ENVIRONMENT=production FOO=“bar baz”. String values are implicitely concatenated, so procd_set_param error An error occurred is equivalent to procd_set_param error “An error occurred”.