35c69be1a74fcfb3f200f864d5d15adcf195c691
[d-i/debian-installer.git] / doc / devel / internals / available-hooks.xml
1 <appendix id="ap-hooks">
2 <title>Available hooks</title>
3
4 <para>
5
6 This appendix given an overview of hooks available for debian-installer
7 modules and extensions. See also <xref linkend="hooks"/>.
8
9 </para><para>
10
11 This overview may not be fully complete.
12
13 </para>
14
15  <sect1>
16  <title>run-parts type hooks</title>
17
18 <para>
19
20 This type of hook consists of a directory in which any component can drop
21 a script that's to be executed at a specific point of the installation
22 procedure. The component responsible for the hook will simply execute any
23 scripts that are present at that time. Scripts are executed in sequence
24 and since the order of execution is often important, they are usually
25 prefixed with a sequence number.
26
27 </para><para>
28
29 Note that currently in most cases the component executing run-parts scripts
30 do not fail or show an error if a called script returns an error.
31
32 </para>
33
34   <sect2 id="ap-hooks-boot">
35   <title>System boot</title>
36
37 <para>
38
39 Scripts that are executed as part of the boot process of Debian Installer.
40 Various scripts in these directories are architecture-specific.
41 See also <xref linkend="di-boot"/>.
42
43 </para>
44
45 <variablelist>
46 <varlistentry>
47
48 <term>/lib/debian-installer-startup.d/* [rootskel]</term>
49 <listitem><para>
50    Early boot scripts. Special feature is that scripts get called if they
51    are executable, and get sourced if they are not.
52 </para></listitem>
53
54 </varlistentry><varlistentry>
55
56 <term>/etc/rcS.d/S[0-9][0-9]* [rootskel]</term>
57 <listitem><para>
58     Additional early boot scripts; executed or sourced just after the scripts
59     in <filename>/lib/debian-installer-startup.d</filename>.
60 </para></listitem>
61
62 </varlistentry><varlistentry>
63
64 <term>/lib/debian-installer.d/* [rootskel]</term>
65 <listitem><para>
66    Initialization and startup of the D-I user interface. These scripts always
67    get sourced.
68 </para><para>
69    These scripts will be run again if the main installer process dies for
70    some reason.
71 </para></listitem>
72
73 </varlistentry>
74 </variablelist>
75
76   </sect2>
77
78   <sect2 id="ap-hooks-general">
79   <title>General purpose run-parts hooks</title>
80
81 <para>
82
83 This section lists general purpose run-parts directories where other
84 components commonly drop scripts in order to have actions executed at
85 that stage of the installation. They are listed roughly in the order
86 in which they are executed during a standard installation.
87
88 </para>
89
90 <variablelist>
91 <varlistentry>
92
93 <term>/usr/lib/base-installer.d/* [base-installer]</term>
94 <listitem><para>
95     The files in this directory are executed after the system has been
96     bootstrapped (generally by debootstrap), but before the system is used
97     in any way. It is intended to be used for very basic configuration of
98     the target system. APT has not yet been configured at this point.
99 </para></listitem>
100
101 </varlistentry><varlistentry>
102
103 <term>/usr/lib/post-base-installer.d/* [base-installer]</term>
104 <listitem><para>
105     The files in this directory are executed after basic configuration of
106     APT and just before kernel selection and installation.
107 </para></listitem>
108
109 </varlistentry><varlistentry>
110
111 <term>/usr/lib/pre-pkgsel.d/* [pkgsel]</term>
112 <listitem><para>
113     The files in this directory are executed before tasksel is called in
114     the <filename>/target</filename> environment. Example usage: install
115     custom tasks (<classname>tasksel-data</classname>) from a source added
116     during <classname>apt-setup</classname>.
117 </para><para>
118     Directly accessing the installation CD and thus installing udebs is not
119     possible in these scripts (but should also not be needed).
120 </para></listitem>
121
122 </varlistentry><varlistentry>
123
124 <term>/usr/lib/finish-install.d/* [finish-install]</term>
125 <listitem><para>
126     The files in this directory are executed at the end of the installation.
127 </para></listitem>
128
129 </varlistentry>
130 </variablelist>
131
132   </sect2>
133
134   <sect2 id="ap-hooks-special">
135   <title>Special purpose run-parts hooks</title>
136
137 <para>
138
139 This section lists run-parts directories that are less likely to be used
140 by other components or for customization, although it is still possible
141 to do so.
142
143 </para>
144
145 <variablelist>
146 <varlistentry>
147
148 <term>/lib/main-menu.d/* [main-menu]</term>
149 <!--
150 <listitem><para>
151    FIXME
152 </para></listitem>
153 -->
154
155 </varlistentry><varlistentry>
156
157 <term>/lib/rescue.d/* [rescue]</term>
158 <!--
159 <listitem><para>
160    FIXME
161 </para></listitem>
162 -->
163
164 </varlistentry><varlistentry>
165
166 <term>/usr/lib/apt-setup/generators/* [apt-setup]</term>
167 <listitem><para>
168    Contains scripts responsible for generating entries in the
169    <filename>/etc/apt/sources.list</filename> on the target system.
170 </para></listitem>
171
172 </varlistentry>
173 </variablelist>
174
175   </sect2>
176
177   <sect2>
178   <title>Partitioning &mdash; deprecated components</title>
179
180 <para>
181
182 The hooks listed in this section are from udebs that are only still
183 being used for the mips architecture. All other architectures use
184 <classname>partman</classname> instead.
185
186 </para>
187
188 <variablelist>
189 <varlistentry>
190
191 <term>/var/lib/partconf/fstab.d/* [partconf?]</term>
192 <listitem><para>
193     partconf and mkfstab read all files in this directory and append
194     the lines (with or without modification) to the generated
195     /target/etc/fstab.
196 </para></listitem>
197
198 </varlistentry><varlistentry>
199
200 <term>/var/lib/partconf/block.d/* [partconf?]</term>
201 <listitem><para>
202     partconf executes for each partition every script in this
203     directory, so some udebs can place scripts here, and then block
204     the output of some partitions; very useful for raid/lvm support.
205     (planned to be included by Thorsten Sauter)
206 </para></listitem>
207
208 </varlistentry><varlistentry>
209
210 <term>/usr/share/partitioner/${ARCH}.sh</term>
211 <term>/usr/share/partitioner/common.sh [partitioner?]</term>
212 <listitem><para>
213     partitioner first tries to call the shell script for the current
214     architecture, and if this script doesn't exist it runs common.sh
215     with the selection harddisk as argument. The script can then do
216     whatever is needed to partition a harddisk on this arch (e.g.
217     running fdisk (text) or cfdisk (slang)).
218 </para></listitem>
219
220 </varlistentry>
221 </variablelist>
222
223   </sect2>
224  </sect1>
225
226  <sect1>
227  <title>Other hooks</title>
228
229 <para>
230
231 The hooks in this section do not contain scripts, but are single files or
232 a directory containing files that are read by a certain component or utility.
233 Some of these hooks can be used for customization, but others should only be
234 modified by using the correct utilities.
235
236 </para>
237
238   <sect2>
239   <title>Hooks available for customization</title>
240
241 <variablelist>
242 <varlistentry>
243
244 <term>/cdrom/.disk/udeb_include</term>
245 <term>/cdrom/.disk/udeb_exclude [anna]</term>
246 <listitem><para>
247     List of packages (udebs) to install into or exclude from the d-i
248     ramdisk.
249 </para></listitem>
250
251 </varlistentry><varlistentry>
252
253 <term>/cdrom/.disk/base_include</term>
254 <term>/cdrom/.disk/base_exclude [base-installer]</term>
255 <listitem><para>
256     The contents of these files are taken as lists of packages to
257     install into or exclude from the target area.
258 </para></listitem>
259
260 </varlistentry>
261 </variablelist>
262
263   </sect2>
264
265   <sect2>
266   <title>Hooks reserved for internal use</title>
267
268 <variablelist>
269 <varlistentry>
270
271 <term>/var/lib/anna-install/queue</term>
272 <term>/var/lib/apt-install/queue [di-utils]</term>
273 <listitem><para>
274     Used by <classname>anna-install</classname> and
275     <classname>apt-install</classname> respectively to queue udebs or
276     packages for later installation.
277 </para></listitem>
278
279 </varlistentry><varlistentry>
280
281 <term>/run/udev/firmware-missing [udev,hw-detect]</term>
282 <listitem><para>
283     Used to register for which kernel modules udev was unable to load
284     firmware.
285 </para></listitem>
286
287 </varlistentry>
288 </variablelist>
289
290   </sect2>
291  </sect1>
292 </appendix>