| 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]> |