docs: import usermanual from org.openembedded.documentation.
[openembedded.git] / docs / usermanual / reference / class_update-rc.d.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <section id="update-rc-d_class" xreflabel="update-rc.d class">
3   <title>update-rc.d class</title>
4
5   <para>Services which need to be started during boot need to be registered
6   using the update-rc.d command. These services are required to have an init
7   script which is installed into <command>/etc/init.d</command> that can be
8   used to start and stop the service.</para>
9
10   <para>The following examples show a service being manually stopped and
11   started using it's init script:<screen>root@titan:/etc# /etc/init.d/syslog stop
12 Stopping syslogd/klogd: stopped syslogd (pid 1551).
13 stopped klogd (pid 1553).
14 done
15 root@titan:/etc# /etc/init.d/syslog start
16 Starting syslogd/klogd: done
17 root@titan:/etc#</screen>The update-rc.d class takes care of the following
18   automatically:</para>
19
20   <orderedlist>
21     <listitem>
22       <para>Registers the service with the system during postinst so it will
23       be automatically started on boot;</para>
24     </listitem>
25
26     <listitem>
27       <para>Stops the service during prerm so it will no longer be running
28       after being removed;</para>
29     </listitem>
30
31     <listitem>
32       <para>Unregisters the service during prerm so there will be no attempts
33       to start the removed service during boot;</para>
34     </listitem>
35
36     <listitem>
37       <para>Adds a build and run time dependency on the update-rc.d package
38       which it uses to register and unregister the services.</para>
39     </listitem>
40   </orderedlist>
41
42   <para>Usage is very simple, as shown by this example from dropbear:<screen>INITSCRIPT_NAME = "dropbear"
43 INITSCRIPT_PARAMS = "defaults 10"
44
45 inherit autotools update-rc.d</screen></para>
46
47   <para>where the variables are:</para>
48
49   <variablelist>
50     <varlistentry>
51       <term>INITSCRIPT_NAME</term>
52
53       <listitem>
54         <para>The name of the init script, which the package will have
55         installed into /etc/init.d</para>
56       </listitem>
57     </varlistentry>
58
59     <varlistentry>
60       <term>INITSCRIPT_PARAMS</term>
61
62       <listitem>
63         <para>The parameters to pass to the update-rc.d call during
64         installation. Typically this will be the work default followed by
65         either single number or a pair of numbers representing the start/stop
66         sequence number (both are set to the same if only one number is
67         supplied.)</para>
68       </listitem>
69     </varlistentry>
70   </variablelist>
71
72   <para>The help from update-rc.d shows show the required parameters:<screen>root@titan:/etc# update-rc.d -h
73 usage: update-rc.d [-n] [-f] [-r &lt;root&gt;] &lt;basename&gt; remove
74        update-rc.d [-n] [-r &lt;root&gt;] [-s] &lt;basename&gt; defaults [NN | sNN kNN]
75        update-rc.d [-n] [-r &lt;root&gt;] [-s] &lt;basename&gt; start|stop NN runlvl [runlvl] [...] .
76                 -n: not really
77                 -f: force
78                 -r: alternate root path (default is /)
79                 -s: invoke start methods if appropriate to current runlevel
80 root@titan:/etc#</screen>The start and stop sequence numbers need to ensure
81   that the the service is started at the appropriate time relative to other
82   services, such as waiting for any service that it depends on before starting
83   (networking for example). Unless the service is a system or security related
84   service it's better to be started as late as possible.</para>
85
86   <section>
87     <title>Multiple update-rc.d packages</title>
88
89     <para>Defining multiple init scripts within the one recipe is also
90     supported. Note that each init script must be in it's own package. The
91     following example is from the quagga recipe:<screen># Main init script starts all deamons
92 # Seperate init script for watchquagga
93 INITSCRIPT_PACKAGES                 = "${PN} ${PN}-watchquagga"
94 INITSCRIPT_NAME_${PN}               = "quagga"
95 INITSCRIPT_PARAMS_${PN}             = "defaults 15 85"
96 INITSCRIPT_NAME_${PN}-watchquagga   = "watchquagga"
97 INITSCRIPT_PARAMS_${PN}-watchquagga = "defaults 90 10"
98
99 inherit autotools update-rc.d</screen> The variables that need to be declared
100     are:</para>
101
102     <variablelist>
103       <varlistentry>
104         <term>INITSCRIPT_PACKAGES</term>
105
106         <listitem>
107           <para>The names of each package which includes an init
108           script.</para>
109         </listitem>
110       </varlistentry>
111
112       <varlistentry>
113         <term>INITSCRIPT_NAME_x</term>
114
115         <listitem>
116           <para>The same meaning as INITSCRIPT_NAME, but for the package x.
117           This would be repeated for each package that includes an init
118           script.</para>
119         </listitem>
120       </varlistentry>
121
122       <varlistentry>
123         <term>INITSCRIPT_PARAMS_x</term>
124
125         <listitem>
126           <para>The same meaning as INITSCRIPT_PARAMS, but for the package x.
127           This would be repeated for each package that includes an init
128           script.</para>
129         </listitem>
130       </varlistentry>
131     </variablelist>
132   </section>
133 </section>