1DEBCONF(7)             Miscellaneous Information Manual             DEBCONF(7)
2
3
4

NAME

6       debconf - Debian package configuration system
7

DESCRIPTION

9       Debconf  is  a  configuration  system  for  Debian packages. There is a
10       rarely-used command named debconf, documented in debconf(1)
11
12       Debconf provides  a  consistent  interface  for  configuring  packages,
13       allowing  you  to choose from several user interface frontends. It sup‐
14       ports preconfiguring packages before they are installed,  which  allows
15       large  installs  and upgrades to ask you for all the necessary informa‐
16       tion up front, and then go do the work while you do something else.  It
17       lets  you, if you're in a hurry, skip over less important questions and
18       information while installing a package (and revisit it later).
19

Preconfiguring packages

21       Debconf can configure packages before they are even installed onto your
22       system.  This  is useful because it lets all the questions the packages
23       are going to ask be asked at the beginning of an install, so  the  rest
24       of the install can proceed while you are away getting a cup of coffee.
25
26       If  you  use  apt  (version  0.5  or  above),  and  you  have apt-utils
27       installed, each package apt installs will be  automatically  preconfig‐
28       ured. This is controlled via /etc/apt/apt.conf.d/70debconf
29
30       Sometimes you might want to preconfigure a package by hand, when you're
31       not installing it with apt. You  can  use  dpkg-preconfigure(8)  to  do
32       that, just pass it the filenames of the packages you want to preconfig‐
33       ure. You will need apt-utils installed for that to work.
34

Reconfiguring packages

36       Suppose you installed the package, and  answered  debconf's  questions,
37       but now that you've used it awhile, you realize you want to go back and
38       change some of your answers. In the past, reinstalling  a  package  was
39       often  the  thing  to  do  when you got in this situation, but when you
40       reinstall the package, debconf seems to remember you have answered  the
41       questions, and doesn't ask them again (this is a feature).
42
43       Luckily, debconf makes it easy to reconfigure any package that uses it.
44       Suppose you want to reconfigure debconf itself. Just run, as root:
45         dpkg-reconfigure debconf
46
47       This will ask  all  the  questions  you  saw  when  debconf  was  first
48       installed.   It may ask you other questions as well, since it asks even
49       low priority questions that may have been skipped when the package  was
50       installed.   You  can use it on any other package that uses debconf, as
51       well.
52

Frontends

54       One of debconf's unique features is that the interface it  presents  to
55       you is only one of many, that can be swapped in at will. There are many
56       debconf frontends available:
57
58       dialog The default frontend, this uses  the  whiptail(1)  or  dialog(1)
59              programs to display questions to you. It works in text mode.
60
61       readline
62              The  most  traditional frontend, this looks quite similar to how
63              Debian configuration always has been:  a  series  of  questions,
64              printed  out  at  the console using plain text, and prompts done
65              using the readline library. It even supports tab completion. The
66              libterm-readline-gnu-perl package is strongly recommended if you
67              chose to use this frontend; the default readline module does not
68              support  prompting  with default values.  At the minimum, you'll
69              need the perl-modules package installed to use this frontend.
70
71              This frontend has some special hotkeys. Pageup (or ctrl-u)  will
72              go  back  to  the previous question (if that is supported by the
73              package that is using debconf), and pagedown  (or  ctrl-v)  will
74              skip forward to the next question.
75
76              This is the best frontend for remote admin work over a slow con‐
77              nection, or for those who are comfortable with unix.
78
79       noninteractive
80              This is the anti-frontend. It never interacts with you  at  all,
81              and  makes  the  default  answers  be used for all questions. It
82              might mail error messages to root, but that's it;  otherwise  it
83              is  completely  silent  and  unobtrusive, a perfect frontend for
84              automatic installs. If you are using this front-end, and require
85              non-default  answers  to questions, you will need to preseed the
86              debconf database; see the section below  on  Unattended  Package
87              Installation for more details.
88
89       gnome  This  is  a  modern  X GUI using the gtk and gnome libraries. Of
90              course, it requires a valid DISPLAY to work; debconf  will  fall
91              back  to  other frontends if it can't work. Note that this fron‐
92              tend requires you have the libgtk3-perl package installed.
93
94       kde    This frontend provides a modern X GUI based on the KDE Platform.
95              You  of  course need a DISPLAY to use this frontend and you must
96              install debconf-kde-helper package. The frontend will fall  back
97              to dialog if some of the prerequisites are not met.
98
99       editor This  is  for those fanatics who have to do everything in a text
100              editor. It runs your editor on a file that looks something  like
101              a typical unix config file, and you edit the file to communicate
102              with debconf. Debconf's author prefers to not comment  regarding
103              the circumstances that led to this frontend being written.
104
105       web
106              This  frontend  acts  as  a web server, that you connect to with
107              your web browser, to browse the questions and answer  them.   It
108              has  a  lot of promise, but is a little rough so far.  When this
109              frontend starts up, it will print out the  location  you  should
110              point  your  web  browser to. You have to run the web browser on
111              the same machine you are configuring, for security reasons.
112
113              Do keep in mind that this is not a very secure frontend.  Anyone
114              who  has  access  to the computer being configured can currently
115              access the web server and configure things while  this  frontend
116              is running. So this is more of a proof of concept than anything.
117
118       You  can change the default frontend debconf uses by reconfiguring deb‐
119       conf. On the other hand, if you just want to change the frontend for  a
120       minute,  you  can  set  the DEBIAN_FRONTEND environment variable to the
121       name of the frontend to use. For example:
122         DEBIAN_FRONTEND=readline apt-get install slrn
123
124       The dpkg-reconfigure(8) and dpkg-preconfigure(8) commands also let  you
125       pass  --frontend=  to  them,  followed by the frontend you want them to
126       use.
127
128       Note that not all frontends will work in all circumstances. If a  fron‐
129       tend  fails  to start up for some reason, debconf will print out a mes‐
130       sage explaining why, and fall back to the next-most similar frontend.
131

Priorities

133       Another nice feature of debconf is that the questions it asks  you  are
134       prioritized. If you don't want to be bothered about every little thing,
135       you can set up debconf to only ask you the  most  important  questions.
136       On the other hand, if you are a control freak, you can make it show you
137       all questions. Each question has a priority.  In  increasing  order  of
138       importance:
139
140       low    Very  trivial questions that have defaults that will work in the
141              vast majority of cases.
142
143       medium Normal questions that have reasonable defaults.
144
145       high   Questions that don't have a reasonable default.
146
147       critical
148              Questions that you really, really need to see (or else).
149
150       Only questions with a priority equal to or greater  than  the  priority
151       you  choose  will  be  shown  to you. You can set the priority value by
152       reconfiguring debconf, or temporarily by passing  --priority=  followed
153       by  the  value to the dpkg-reconfigure(8) and dpkg-preconfigure(8) com‐
154       mands, or by setting the DEBIAN_PRIORITY environment variable.
155

Backend Database

157       Debconf uses a rather  flexible  and  potentially  complicated  backend
158       database  for  storing  data such as the answers to questions. The file
159       /etc/debconf.conf is used to configure this database. If  you  need  to
160       set  up something complicated, like make debconf read a remote database
161       to get defaults, with local overrides,  read  the  debconf.conf(5)  man
162       page  for  all  the  gory  details.  Generally, the backend database is
163       located in /var/cache/debconf/
164        .
165

Unattended Package Installation

167       If you have many machines to manage you will sometimes find yourself in
168       the  position  of  needing  to  perform  an  unattended installation or
169       upgrade of packages on many systems, when the default answers  to  some
170       configuration  questions  are  not  acceptable.  There are many ways to
171       approach this; all involve setting up a database and making debconf use
172       it to get the answers you want.
173
174       You should really read debconf.conf(5) before this section, as you need
175       to understand how debconf's databases work.
176
177       The easiest way to set up the database is to install  the  packages  on
178       one  machine and answer their questions as usual. Or you might just use
179       dpkg-preconfigure(8) to configure a set of  packages  without  actually
180       installing them. Or you might even decide to write a plain text debconf
181       database by hand or something.
182
183       Once you have the database, you need to figure  out  how  to  make  the
184       remote  systems  use it. This depends of course on the configuration of
185       those systems and what database types they are set up to use.
186
187       If you are using the LDAP debconf database, an entire network of debian
188       machines  can  also  have  any  or  all  package installation questions
189       answered automatically by a single LDAP server.
190
191       But perhaps you're using something a little bit easier to set up  like,
192       say, the default debconf database configuration, or you just don't want
193       your remote systems to use LDAP all the time. In  this  case  the  best
194       approach  is  to temporarily configure the remote systems to stack your
195       database underneath their own existing databases, so they pull  default
196       values  out  of  it.  Debconf  offers  two  environment variables, DEB‐
197       CONF_DB_FALLBACK and DEBCONF_DB_OVERRIDE, to make it easy to do this on
198       the fly. Here is a sample use:
199
200          cat /var/cache/debconf/config.dat | \
201          ssh root@target "DEBIAN_FRONTEND=noninteractive \
202                         DEBCONF_DB_FALLBACK=Pipe apt-get upgrade"
203
204       This  makes  the  debconf  on  the remote host read in the data that is
205       piped across the ssh connection and interpret it as a plain text format
206       debconf  database. It then uses that database as a fallback database --
207       a read-only database that is queried for answers to  questions  if  the
208       system's main debconf database lacks answers.
209
210       Here's another way to use the DEBCONF_DB_FALLBACK environment variable:
211
212         ssh -R 389:ldap:389 root@target \
213            "DEBCONF_DB_FALLBACK='LDAP{host:localhost}' apt-get upgrade"
214
215       Here  ssh is used to set up a tunneled LDAP connection and run debconf.
216       Debconf is told to use the LDAP server as the fallback  database.  Note
217       the  use  of  "{host:localhost}"  to configure how debconf accesses the
218       LDAP database by providing the "host" field with  a  value  of  "local‐
219       host".
220
221       Here's another method:
222
223         scp config.dat root@target:
224         ssh root@target "DEBCONF_DB_FALLBACK='File{/root/config.dat}' apt-get
225       upgrade
226
227       Here you copy the database over with scp, and then ssh  over  and  make
228       debconf  use the file you copied over. This illustrates a shorthand you
229       can use in the DEBCONF_DB_FALLBACK parameters -- if  a  field  name  is
230       left off, it defaults to "filename".
231
232       There  is  only  one problem with these uses of the DEBCONF_DB_FALLBACK
233       parameter: While the fallback database can provide answers to questions
234       the  other  debconf  databases have never seen, it is only queried as a
235       fallback; after the other databases. If you need to instead temporarily
236       override  an  existing value on the remote host, you should instead use
237       the DEBCONF_DB_OVERRIDE variable. Like DEBCONF_DB_FALLBACK, it sets  up
238       a temporary database, but this database is consulted before any others,
239       and can be used to override existing values.
240

Developing for Debconf

242       Package developers and others who want to  develop  packages  that  use
243       debconf should read debconf-devel(7)
244        .
245
246       Briefly, debconf communicates with maintainer scripts or other programs
247       via standard input and output, using  a  simple  line-oriented  command
248       language  similar  to  that  used  by common internet protocols such as
249       SMTP. Programs use this protocol to ask debconf to display questions to
250       the user, and retrieve the user's answers. The questions themselves are
251       defined in a separate file, called the "templates file",  which  has  a
252       format not unlike a debian control file.
253
254       Debian  packages  which  use debconf typically provide both a templates
255       file and a "config" script (run to preconfigure  the  package)  in  the
256       control metadata section of the package.
257

ENVIRONMENT

259       DEBIAN_FRONTEND
260              Used to temporarily change the frontend debconf uses. See above.
261
262       DEBIAN_PRIORITY
263              Used to temporarily change the minimum priority of question deb‐
264              conf will display. See above.
265
266       DEBCONF_DEBUG
267              Turns on debugging output on standard error. May  be  set  to  a
268              facility  name  or a regular expression which matches a facility
269              name (such as '.*' to output all debug info). The facility names
270              include:
271
272              user   Debugging info of interest to a debconf user.
273
274              developer
275                     Debugging info of interest to a package developer.
276
277              db     Debugging info about the backend database.
278
279       DEBCONF_NOWARNINGS
280              Set  to "yes" to disable some warnings that debconf may display.
281              Does not suppress display of fatal errors.
282
283       DEBCONF_TERSE
284              Set to "yes" to enable terse mode, in  which  debconf  frontends
285              cut down on the verbiage as much as possible.
286
287       DEBCONF_DB_FALLBACK
288              Stack  a  database after the normally used databases, so that it
289              is used as a fallback to get configuration information from. See
290              "Unattended  Package  Installation"  above.  If the value of the
291              variable is the name of an existing  database  in  debconf.conf,
292              then  that  database  will  be used.  Otherwise, the environment
293              variable can be used to configure a  database  on  the  fly,  by
294              telling the type of database, and optionally passing field:value
295              settings, inside curly braces after the type. Spaces are used to
296              separate  fields, so you cannot specify a field value containing
297              whitespace.
298
299       Thus, this uses the fallbackdb in debconf.conf:
300         DEBCONF_DB_FALLBACK=fallbackdb
301
302       While this sets up a new database of type File, and tells it a filename
303       to use and turns off backups:
304         DEBCONF_DB_FALLBACK=File{Filename:/root/config.dat Backup:no}
305
306       And  as  a shorthand, this sets up a database of type File with a file‐
307       name:
308         DEBCONF_DB_FALLBACK=File{/root/config.dat}
309
310       Note that if a fallback database is set up on the fly, it will be read-
311       only by default.
312
313       DEBCONF_DB_OVERRIDE
314              Stack  a database before the normally used databases, so that it
315              can override values from them. The value of the  variable  works
316              the same as does the value of DEBCONF_DB_FALLBACK.
317
318       DEBCONF_DB_REPLACE
319              Use  a  given  database  instead of the normally used databases.
320              This may be useful for testing with a separate database  without
321              having  to  create  a separate debconf.conf, or to avoid locking
322              the normal databases.
323
324       DEBCONF_SYSTEMRC
325              If this environment variable  is  set,  debconf  will  ignore  a
326              user's ~/.debconfrc file, and use the system one instead.  If it
327              is set to the name of a regular file, debconf will use that file
328              in preference to the system configuration files.
329
330       DEBCONF_FORCE_DIALOG
331              If  this environment variable is set, debconf will use dialog in
332              preference to whiptail for the dialog frontend.
333
334       DEBCONF_FORCE_XDIALOG
335              If this environment variable is set, debconf will use Xdialog in
336              preference to whiptail for the dialog frontend.
337
338       DEBCONF_NONINTERACTIVE_SEEN
339              Set  to  "true"  to  cause the seen flag to be set for questions
340              asked in the noninteractive frontend.
341

BUGS

343       Probably quite a few, there's a lot of code here.
344
345       If you do file a bug report, be sure to include the following  informa‐
346       tion:
347
348       *      The debconf frontend you were using when the problem occurred
349
350       *      What you did to trigger the problem.
351
352       *      The  full  text  of any error messages. If you can reproduce the
353              bug, do so with DEBCONF_DEBUG='.*' set and exported. This speeds
354              up debugging a lot.
355

SEE ALSO

357       debconf.conf(5), debconf-devel(7), dpkg-preconfigure(8), dpkg-reconfig‐
358       ure(8), debconf(1),
359

AUTHOR

361       Joey Hess <joeyh@debian.org>
362
363
364
365                                                                    DEBCONF(7)
Impressum