Debian Codegraph @

doc/man/debconf.7

raw
1 .TH DEBCONF 7
2 .SH NAME
3 debconf \- Debian package configuration system
4 .SH DESCRIPTION
5 Debconf is a configuration system for Debian packages. There is a
6 rarely-used command named debconf, documented in
7 .BR debconf (1)
8 .P
9 Debconf provides a consistent interface for configuring packages, allowing
10 you to choose from several user interface frontends. It supports
11 preconfiguring packages before they are installed, which allows large
12 installs and upgrades to ask you for all the necessary information up
13 front, and then go do the work while you do something else. It lets you,
14 if you're in a hurry, skip over less important questions and information
15 while installing a package (and revisit it later).
16 .SH "Preconfiguring packages"
17 Debconf can configure packages before they are even installed onto
18 your system. This is useful because it lets all the questions the
19 packages are going to ask be asked at the beginning of an install,
20 so the rest of the install can proceed while you are away getting
21 a cup of coffee.
22 .P
23 If you use apt (version 0.5 or above), and you have apt-utils installed,
24 each package apt installs will be automatically preconfigured. This is
25 controlled via
26 .I /etc/apt/apt.conf.d/70debconf
27 .P
28 Sometimes you might want to preconfigure a package
29 by hand, when you're not installing it with apt. You can use
30 .BR dpkg-preconfigure (8)
31 to do that, just pass it the filenames of the packages you
32 want to preconfigure. You will need apt-utils installed for that to work.
33 .SH Reconfiguring packages
34 Suppose you installed the package, and answered debconf's questions, but
35 now that you've used it awhile, you realize you want to go back and change
36 some of your answers. In the past, reinstalling a package was often the thing
37 to do when you got in this situation, but when you reinstall the package,
38 debconf seems to remember you have answered the questions, and doesn't ask
39 them again (this is a feature).
40 .P
41 Luckily, debconf makes it easy to reconfigure any package that uses it.
42 Suppose you want to reconfigure debconf itself. Just run, as root:
43 dpkg-reconfigure debconf
44 .P
45 This will ask all the questions you saw when debconf was first installed.
46 It may ask you other questions as well, since it asks even low priority
47 questions that may have been skipped when the package was installed.
48 You can use it on any other package that uses debconf, as well.
49 .SH Frontends
50 One of debconf's unique features is that the interface it presents to
51 you is only one of many, that can be swapped in at will. There are many
52 debconf frontends available:
53 .TP
54 .B dialog
55 The default frontend, this uses the
56 .BR whiptail (1)
57 or
58 .BR dialog (1)
59 programs to display questions to you. It works in text mode.
60 .TP
61 .B readline
62 .RS
63 The most traditional frontend, this looks quite similar
64 to how Debian configuration always has been: a series of
65 questions, printed out at the console using plain text, and
66 prompts done using the readline library. It even supports tab
67 completion. The libterm-readline-gnu-perl package is strongly
68 recommended if you chose to use this frontend; the default
69 readline module does not support prompting with default values.
70 At the minimum, you'll need the perl-modules package installed
71 to use this frontend.
72 .P
73 This frontend has some special hotkeys. Pageup (or ctrl-u)
74 will go back to the previous question (if that is supported
75 by the package that is using debconf), and pagedown (or
76 ctrl-v) will skip forward to the next question.
77 .P
78 This is the best frontend for remote admin work over a slow
79 connection, or for those who are comfortable with unix.
80 .RE
81 .TP
82 .B noninteractive
83 This is the anti-frontend. It never interacts with you at all, and makes
84 the default answers be used for all questions. It might mail error messages
85 to root, but that's it; otherwise it is completely silent and unobtrusive,
86 a perfect frontend for automatic installs. If you are using this
87 front-end, and require non-default answers to questions, you will need to
88 preseed the debconf database; see the section below on Unattended
89 Package Installation for more details.
90 .TP
91 .B gnome
92 This is a modern X GUI using the gtk and gnome libraries. Of course, it
93 requires a valid DISPLAY to work; debconf will fall back to other frontends
94 if it can't work. Note that this frontend requires you have the
95 libgtk3-perl package installed.
96 .TP
97 .B kde
98 This frontend provides a modern X GUI based on the KDE Platform. You of course
99 need a DISPLAY to use this frontend and you must install debconf-kde-helper
100 package. The frontend will fall back to dialog if some of the prerequisites are
101 not met.
102 .TP
103 .B editor
104 This is for those fanatics who have to do everything in a
105 text editor. It runs your editor on a file that looks
106 something like a typical unix config file, and you edit the
107 file to communicate with debconf. Debconf's author prefers
108 to not comment regarding the circumstances that led to this
109 frontend being written.
110 .TP
111 .B web
112 .RS
113 This frontend acts as a web server, that you connect to
114 with your web browser, to browse the questions and answer them.
115 It has a lot of promise, but is a little rough so far.
116 When this frontend starts up, it will print out the location
117 you should point your web browser to. You have to run the web
118 browser on the same machine you are configuring, for security
119 reasons.
120 .P
121 Do keep in mind that this is not a very secure frontend.
122 Anyone who has access to the computer being configured
123 can currently access the web server and configure things
124 while this frontend is running. So this is more of a
125 proof of concept than anything.
126 .RE
127 .P
128 You can change the default frontend debconf uses by reconfiguring
129 debconf. On the other hand, if you just want to change the frontend
130 for a minute, you can set the DEBIAN_FRONTEND environment variable to
131 the name of the frontend to use. For example:
132 DEBIAN_FRONTEND=readline apt-get install slrn
133 .P
134 The
135 .BR dpkg-reconfigure (8)
136 and
137 .BR dpkg-preconfigure (8)
138 commands also let you pass
139 .I --frontend=
140 to them, followed by the frontend you want them to use.
141 .P
142 Note that not all frontends will work in all circumstances. If a frontend
143 fails to start up for some reason, debconf will print out a message
144 explaining why, and fall back to the next-most similar frontend.
145 .SH Priorities
146 Another nice feature of debconf is that the questions it asks you are
147 prioritized. If you don't want to be bothered about every little thing,
148 you can set up debconf to only ask you the most important questions.
149 On the other hand, if you are a control freak, you can make it show
150 you all questions. Each question has a priority. In increasing order of
151 importance:
152 .TP
153 .B low
154 Very trivial questions that have defaults that will work in the vast majority
155 of cases.
156 .TP
157 .B medium
158 Normal questions that have reasonable defaults.
159 .TP
160 .B high
161 Questions that don't have a reasonable default.
162 .TP
163 .B critical
164 Questions that you really, really need to see (or else).
165 .P
166 Only questions with a priority equal to or greater than the priority you
167 choose will be shown to you. You can set the priority value by
168 reconfiguring debconf, or temporarily by passing
169 .I --priority=
170 followed by the value to the
171 .BR dpkg-reconfigure (8)
172 and
173 .BR dpkg-preconfigure (8)
174 commands, or by setting the DEBIAN_PRIORITY environment variable.
175 .SH Backend Database
176 Debconf uses a rather flexible and potentially complicated backend
177 database for storing data such as the answers to questions. The file
178 .B /etc/debconf.conf
179 is used to configure this database. If you need to set up something
180 complicated, like make debconf read a remote database to get defaults,
181 with local overrides, read the
182 .BR debconf.conf (5)
183 man page for all the gory details. Generally,
184 the backend database is located in
185 .B /var/cache/debconf/
186 .
187 .SH Unattended Package Installation
188 If you have many machines to manage you will sometimes find yourself in the
189 position of needing to perform an unattended installation or upgrade of
190 packages on many systems, when the default answers to some configuration
191 questions are not acceptable. There are many ways to approach this; all
192 involve setting up a database and making debconf use it to get the answers
193 you want.
194 .P
195 You should really read
196 .BR debconf.conf (5)
197 before this section, as you need to understand how debconf's databases work.
198 .P
199 The easiest way to set up the database is to install the packages on one
200 machine and answer their questions as usual. Or you might just use
201 .BR dpkg-preconfigure (8)
202 to configure a set of packages without actually installing them. Or you
203 might even decide to write a plain text debconf database by hand or
204 something.
205 .P
206 Once you have the database, you need to figure out how to make
207 the remote systems use it. This depends of course on the configuration of
208 those systems and what database types they are set up to use.
209 .P
210 If you are using the LDAP debconf database, an entire network of debian
211 machines can also have any or all package installation questions answered
212 automatically by a single LDAP server.
213 .P
214 But perhaps you're using something a little bit easier to set up like, say,
215 the default debconf database configuration, or you just don't want your
216 remote systems to use LDAP all the time. In this case the best approach is
217 to temporarily configure the remote systems to stack your database
218 underneath their own existing databases, so they pull default values out of
219 it. Debconf offers two environment variables, DEBCONF_DB_FALLBACK and
220 DEBCONF_DB_OVERRIDE, to make it easy to do this on the fly. Here is a sample
221 use:
222 .P
223 cat /var/cache/debconf/config.dat | \\
224 ssh root@target "DEBIAN_FRONTEND=noninteractive \\
225 DEBCONF_DB_FALLBACK=Pipe apt-get upgrade"
226 .P
227 This makes the debconf on the remote host read in the data that is piped
228 across the ssh connection and interpret it as a plain text format debconf
229 database. It then uses that database as a fallback database -- a
230 read-only database that is queried for answers to questions if the system's
231 main debconf database lacks answers.
232 .P
233 Here's another way to use the DEBCONF_DB_FALLBACK environment variable:
234 .P
235 ssh -R 389:ldap:389 root@target \\
236 "DEBCONF_DB_FALLBACK='LDAP{host:localhost}' apt-get upgrade"
237 .P
238 Here ssh is used to set up a tunneled LDAP connection and run debconf.
239 Debconf is told to use the LDAP server as the fallback database. Note the
240 use of "{host:localhost}" to configure how debconf accesses the LDAP
241 database by providing the "host" field with a value of "localhost".
242 .P
243 Here's another method:
244 .P
245 scp config.dat root@target:
246 ssh root@target "DEBCONF_DB_FALLBACK='File{/root/config.dat}' apt-get upgrade
247 .P
248 Here you copy the database over with scp, and then ssh over and make
249 debconf use the file you copied over. This illustrates a shorthand you can
250 use in the DEBCONF_DB_FALLBACK parameters -- if a field name is left off, it
251 defaults to "filename".
252 .P
253 There is only one problem with these uses of the DEBCONF_DB_FALLBACK parameter:
254 While the fallback database can provide answers to questions the other
255 debconf databases have never seen, it is only queried as a fallback; after
256 the other databases. If you need to instead temporarily override an
257 existing value on the remote host, you should instead use the
258 DEBCONF_DB_OVERRIDE variable. Like DEBCONF_DB_FALLBACK, it sets up a temporary
259 database, but this database is consulted before any others, and can be used
260 to override existing values.
261 .SH Developing for Debconf
262 Package developers and others who want to develop packages that use
263 debconf should read
264 .BR debconf-devel (7)
265 .
266 .P
267 Briefly, debconf communicates with maintainer scripts or other programs
268 via standard input and output, using a simple line-oriented command language
269 similar to that used by common internet protocols such as SMTP. Programs use
270 this protocol to ask debconf to display questions to the user, and retrieve
271 the user's answers. The questions themselves are defined in a separate file,
272 called the "templates file", which has a format not unlike a debian control
273 file.
274 .P
275 Debian packages which use debconf typically provide
276 both a templates file and a "config" script (run to preconfigure the
277 package) in the control metadata section of the package.
278 .SH ENVIRONMENT
279 .TP
280 .B DEBIAN_FRONTEND
281 Used to temporarily change the frontend debconf uses. See above.
282 .TP
283 .B DEBIAN_PRIORITY
284 Used to temporarily change the minimum priority of question debconf will
285 display. See above.
286 .TP
287 .B DEBCONF_DEBUG
288 .RS
289 Turns on debugging output on standard error. May be set to a facility name
290 or a regular expression which matches a facility name (such as '.*' to output
291 all debug info). The facility names include:
292 .TP
293 .B user
294 Debugging info of interest to a debconf user.
295 .TP
296 .B developer
297 Debugging info of interest to a package developer.
298 .TP
299 .B db
300 Debugging info about the backend database.
301 .RE
302 .TP
303 .B DEBCONF_NOWARNINGS
304 Set to "yes" to disable some warnings that debconf may display. Does not
305 suppress display of fatal errors.
306 .TP
307 .B DEBCONF_TERSE
308 Set to "yes" to enable terse mode, in which debconf frontends cut down on
309 the verbiage as much as possible.
310 .TP
311 .B DEBCONF_DB_FALLBACK
312 Stack a database after the normally used databases, so that it is used as a
313 fallback to get configuration information from. See "Unattended Package
314 Installation" above. If the value of the variable is the name of an
315 existing database in debconf.conf, then that database will be used.
316 Otherwise, the environment variable can be used to configure a database on the
317 fly, by telling the type of database, and optionally passing field:value
318 settings, inside curly braces after the type. Spaces are used to separate
319 fields, so you cannot specify a field value containing whitespace.
320 .P
321 Thus, this uses the fallbackdb in debconf.conf:
322 DEBCONF_DB_FALLBACK=fallbackdb
323 .P
324 While this sets up a new database of type File, and tells it a filename to
325 use and turns off backups:
326 DEBCONF_DB_FALLBACK=File{Filename:/root/config.dat Backup:no}
327 .P
328 And as a shorthand, this sets up a database of type File with a filename:
329 DEBCONF_DB_FALLBACK=File{/root/config.dat}
330 .P
331 Note that if a fallback database is set up on the fly, it will be read-only
332 by default.
333 .TP
334 .B DEBCONF_DB_OVERRIDE
335 Stack a database before the normally used databases, so that it can
336 override values from them. The value of the variable works the same as does
337 the value of DEBCONF_DB_FALLBACK.
338 .TP
339 .B DEBCONF_DB_REPLACE
340 Use a given database instead of the normally used databases.
341 This may be useful for testing with a separate database without having to
342 create a separate debconf.conf, or to avoid locking the normal databases.
343 .TP
344 .B DEBCONF_SYSTEMRC
345 If this environment variable is set, debconf will ignore a user's
346 ~/.debconfrc file, and use the system one instead.
347 If it is set to the name of a regular file, debconf will use that file in
348 preference to the system configuration files.
349 .TP
350 .B DEBCONF_FORCE_DIALOG
351 If this environment variable is set, debconf will use dialog in preference
352 to whiptail for the dialog frontend.
353 .TP
354 .B DEBCONF_FORCE_XDIALOG
355 If this environment variable is set, debconf will use Xdialog in preference
356 to whiptail for the dialog frontend.
357 .TP
358 .B DEBCONF_NONINTERACTIVE_SEEN
359 Set to "true" to cause the seen flag to be set for questions asked in the
360 noninteractive frontend.
361 .SH BUGS
362 Probably quite a few, there's a lot of code here.
363 .P
364 If you do file a bug report, be sure to include the following information:
365 .TP
366 .B *
367 The debconf frontend you were using when the problem occurred
368 .TP
369 .B *
370 What you did to trigger the problem.
371 .TP
372 .B *
373 The full text of any error messages. If you can reproduce the bug, do so
374 with DEBCONF_DEBUG='.*' set and exported. This speeds up debugging a
375 lot.
376 .SH SEE ALSO
377 .BR debconf.conf (5),
378 .BR debconf-devel (7),
379 .BR dpkg-preconfigure (8),
380 .BR dpkg-reconfigure (8),
381 .BR debconf (1),
382 .SH AUTHOR
383 Joey Hess <[email protected]>