| Both sides previous revision Previous revision Next revision | Previous revision |
| docs:techref:initscripts [2019/09/02 15:33] – links fixed tmomas | docs:techref:initscripts [2020/12/23 07:03] (current) – detly |
|---|
| |
| ====== Init Scripts ====== | ====== Init Scripts ====== |
| [[wp>Init]] scripts configure the [[wp>Daemon_(computing)|daemons]] of the Linux system. Init scripts are run to start required processes as part of the [[docs:techref:process.boot|boot process]]. In OpenWrt init is implemented with init.d. The init process that calls the scripts at boot time is provided by [[docs:techref:process.boot#busybox_init|Busybox]]. This article explains how init.d scripts work and how to create them. Note that this is mostly equivalent to other init.d implementations and in-depth documentation can be found elsewhere. | [[wp>Init]] scripts configure the [[wp>Daemon_(computing)|daemons]] of the Linux system. Init scripts are run to start required processes as part of the [[docs:techref:process.boot|boot process]]. In OpenWrt init is implemented with init.d. The init process that calls the scripts at boot time is provided by [[docs:techref:process.boot#busybox_init|Busybox]]. This article explains how init.d scripts work and how to create them. Note that this is mostly equivalent to other init.d implementations and in-depth documentation can be found elsewhere. You could also take a look at the set of [[commit>?p=openwrt/openwrt.git;a=blob;f=package/base-files/files/etc/rc.common;hb=HEAD|shell functions in /etc/rc.common]] to see how the building blocks of the init scripts are implemented. |
| | |
| ===== Example Init Script ===== | ===== Example Init Script ===== |
| Init scripts are explained best by example. Suppose we have a daemon we want to handle by init.d. We create a file ''/etc/init.d/example'', which as a bare minimum looks as follows: | Init scripts are explained best by example. Suppose we have a daemon we want to handle by init.d. We create a file ''/etc/init.d/example'', which as a bare minimum looks as follows: |
| This init script is just a shell script. The first line is a [[wp>Shebang_(Unix)|shebang line]] that uses ''[[docs:guide-user:base-system:notuci.config#etcrc.common|/etc/rc.common]]'' as a wrapper to provide its main and default functionality and to check the script prior to execution. | This init script is just a shell script. The first line is a [[wp>Shebang_(Unix)|shebang line]] that uses ''[[docs:guide-user:base-system:notuci.config#etcrc.common|/etc/rc.common]]'' as a wrapper to provide its main and default functionality and to check the script prior to execution. |
| |
| :!: Look inside ''rc.common'' to understand its functionality. | :!: Look inside ''[[commit>?p=openwrt/openwrt.git;a=blob;f=package/base-files/files/etc/rc.common;hb=HEAD|rc.common]]'' to understand its functionality. |
| |
| By this ''rc.common'' template, the available commands for an init scripts are as follows: | By this ''rc.common'' template, the available commands for an init scripts are as follows: |
| :!: OpenWrt will run the initscript **in the host system during build** (currently using actions "enable" or "disable"), and it must correctly deal with that special case without undue side-effects. Refer to the "enable and disable" section below for more on this pitfall. | :!: OpenWrt will run the initscript **in the host system during build** (currently using actions "enable" or "disable"), and it must correctly deal with that special case without undue side-effects. Refer to the "enable and disable" section below for more on this pitfall. |
| |
| If you add a section like the one below: | ==== Other functions ==== |
| | |
| | The ''rc.common'' script defines other functions that you can override if you need to, eg: |
| | |
| | * ''boot()'' - called once each time the system starts up. By default this function calls ''start $@'', so if your service has a "one-off" component (eg. turn on some hardware) and an ongoing component (eg. use the hardware), you will almost certainly want to call ''start "$@"'' at the end of your own ''boot()'' function too. If there is no ongoing component, you can leave it out. |
| | * ''shutdown()'' - called once each time the system is shut down (whether for reboot or poweroff). Like the ''boot()'' function, this function calls ''stop'' by default (note no arguments), so if your service has an ongoing component like above, and a one-off shutdown command (eg. turn off some hardware), you will want to call ''stop'' first, and then your one-off command. |
| | |
| | These functions can be called by procd init scripts too. |
| | |
| | For example: |
| |
| ^ Code ^ | ^ Code ^ |
| |<code bash>boot() { | |<code> |
| echo boot | boot() { |
| # commands to run on boot | echo "Turning on extra comms device" |
| }</code>| | # This is a made up command to illustrate the point |
| | comms2_power --on |
| | start "$@" |
| | } |
| | |
| | start() { |
| | # Service that uses the device we turned on in boot() |
| | my_service |
| | } |
| | |
| | shutdown() { |
| | # The service is finished, so turn off the hardware |
| | stop |
| | echo "Turning off extra comms device" |
| | comms2_power --off |
| | } |
| | </code>| |
| |
| In that case these commands will be run on boot, instead of those in the ''start()'' section, which is normally run at boot when '' boot()'' is not defined. This is handy for things that need to be done on boot, but not every time the program it calls has to restart. | ==== Custom commands ==== |
| |
| You can add your own custom commands by using the EXTRA_COMMANDS variable, and provide help for those commands with the EXTRA_HELP variable, then adding sections for each of your custom commands: | You can add your own custom commands by using the EXTRA_COMMANDS variable, and provide help for those commands with the EXTRA_HELP variable, then adding sections for each of your custom commands: |