path: root/en/appendix/example-preseed-etch-new.xml

<!-- retain these comments for translator revision tracking -->
<!-- $Id: example-preseed-etch.xml 32158 2005-11-16 01:20:19Z joeyh $ -->

<!--
Should be renamed to this, but don't want to break link from ch4 now.
<appendix id="appendix-preseed" condition="etch">
-->
<appendix id="example-preseed" condition="etch">
<title>Automating the installation using preseeding</title>

<para>

This appendix explains the intricacies of preseeding answers to dialogs in
&d-i; to automate your installation.

</para><para>

The configuration fragments used in this appendix are also available as an
example preseed file from &urlset-example-preseed;.

</para>

 <sect1 condition="FIXME" id="preseed-intro">
 <title>Introduction</title>

<itemizedlist>
<listitem><para>
  Supports 1st and 2nd stage
</para></listitem>
<listitem><para>
  Methods: initrd, net, file
</para></listitem>
<listitem><para>
  Hooks
</para></listitem>
<listitem><para>
  Seen flags
</para></listitem>
<listitem><para>
  Limitations
</para></listitem>
<listitem><para>
  How 2nd stage preseeding works
</para></listitem>
</itemizedlist>

 </sect1>

 <sect1 id="preseed-using">
 <title>Using preseeding</title>

  <sect2 id="preseed-loading">
  <title>Loading the preseed file</title>
<para>

If you using initrd preseeding, you only have to make sure a file named
<filename>preseed.cfg</filename> is included in the root directory of the
initrd. The installer will automatically check if this file is present and
load it.

</para><para>

For the other preseeding methods you need to tell the installer what file to
use when you boot it. This is done by passing the kernel a boot parameter,
either manually at boot or by editing the <filename>syslinux.cfg</filename>
(or similar) file and adding the parameter to the end of the append line(s)
for the kernel.

</para><para>

If you do specify the preseed file in the syslinux configuration, you might
set the timeout to 1 in syslinux.cfg to avoid needing to hit enter to boot
the installer.

</para><para>

To make sure the installer gets the right preseed file, you can optionally
specify a checksum for the file. Currently this needs to be a md5sum, and if
specified it must match the preseed file or the installer will refuse to use it.

</para>

<informalexample><screen>
# Boot parameters to specify:
# - if you're netbooting:
#   preseed/url=http://host/path/to/preseed
#   preseed/url/checksum=5da499872becccfeda2c4872f9171c3d
#
# - if you're booting a remastered CD:
#   preseed/file=/cdrom/preseed
#   preseed/file/checksum=5da499872becccfeda2c4872f9171c3d
#
# - if you're installing from USB media (put the preseed file in the
#   toplevel directory of the USB stick):
#   preseed/file=/hd-media/preseed
#   preseed/file/checksum=5da499872becccfeda2c4872f9171c3d
</screen></informalexample>

<para>

While you're at it, you may want to add a boot parameter
<userinput>debconf/priority=critical</userinput>. This will avoid most
questions even if the preseeding below misses some.

</para>
  </sect2>

  <sect2 id="preseed-bootparms">
  <title>Using boot parameters to supplement preseeding</title>
<para>

Some parts of the installation process cannot be automated using some forms
of preseeding, because the questions are asked before the preseed file is
loaded. For example, if the preseed file is downloaded over the network,
the network setup must be done first. One reason to use initrd preseeding
is that it allows preseeding of even these early steps of the installation
process.

</para><para>

If a preseed file cannot be used to preseed some steps, the install can
still be fully automated, since you can pass preseed values to the kernel
on the command line. Just pass <userinput>path/to/var=value</userinput>
for any of the preseed variables listed in the examples.

</para>
<note><para>

The 2.4 kernel accepts a maximum of 8 command line options and
8 environment options (including any options added by default for the
installer). If these numbers are exceeded, 2.4 kernels will drop any
excess options and 2.6 kernels will panic. With kernel 2.6.9 or newer,
you can use 32 command line options and 32 environment options.

</para></note>
<para>

For most installations some of the default options in your bootloader
configuration file, like 'vga=normal', may be safely removed which may
allow you to add more options for preseeding.

</para>
<note><para>

It may not always be possible to specify values with spaces for boot
parameters, even if you delimit them with quotes.

</para></note>
  </sect2>
 </sect1>

 <sect1 condition="FIXME" id="preseed-creating">
 <title>Creating a preseed file</title>

<itemizedlist>
<listitem><para>
  Relation with /var/lib/(c)debconf/templates
</para></listitem>
<listitem><para>
  Most values need to be in English or codes
</para></listitem>
<listitem><para>
  Using a manual installation as base
</para></listitem>
<listitem><para>
  Finding other possible values
</para></listitem>
</itemizedlist>

<para>

To check if the format of your preseed file is valid before performing an
install, you can use the command <command>debconf-set-selections -c
<replaceable>preseed.cfg</replaceable></command>.

</para>
 </sect1>

 <sect1 id="preseed-stage1">
 <title>Preseeding the first stage of the installation</title>
<para>

The configuration fragments used in this appendix are also available as an
example preseed file from &urlset-example-preseed;.

</para><para>

Note that this example is based on an installation for the Intel x86
architecture. If you are installing a different architecture, some of the
examples (like keyboard selection and bootloader installation) may not be
relevant and will need to be replaced by debconf settings valid for your
architecture.

</para>
 
  <sect2 id="preseed-l10n">
  <title>Localization</title>
<para>

Setting localization values will only work if you are using initrd preseeding.
With all other methods the preseed file will only be loaded after these
questions have been asked.

</para><para>

The locale can be used to specify both language and country.
To specify the locale as a boot parameter, use
<userinput>debian-installer/locale=<replaceable>en_US</replaceable></userinput>.

<informalexample><screen>
# Locale sets language and country.
d-i debian-installer/locale string en_US
</screen></informalexample>

</para><para>

Keyboard configuration consists of selecting a keyboard architecture and a
keymap. In most cases the correct keyboard architecture is selected by
default, so there's normally no need to preseed it. The keymap must of
course be valid for the selected or preseeded architecture.

</para><para>

To skip keyboard configuration preseed
<classname>console-tools/archs</classname> with
<userinput>skip-config</userinput>.
This will result in the kernel keymap remaining active.

</para>

<informalexample><screen>
# Keyboard selection.
#d-i console-tools/archs select at
d-i console-keymaps-at/keymap select us
# Example for a different keyboard architecture
#d-i console-keymaps-usb/keymap select mac-usb-us

</screen></informalexample>

<note><para>

The changes in the input layer for 2.6 kernels have made the keyboard
architecture virtually obsolete. For 2.6 kernels normally a <quote>PC</quote>
(<userinput>at</userinput>) keymap should be selected.

</para></note>
  </sect2>

  <sect2 id="preseed-network">
  <title>Network configuration</title>
<para>

Of course, preseeding the network configuration won't work if you're
loading your preseed file from the network. But it's great when you're
booting from CD or USB stick. If you are loading preseed files from
the network, you can pass network config parameters in using kernel
boot parameters.

</para>

<informalexample><screen>
# netcfg will choose an interface that has link if possible. This makes it
# skip displaying a list if there is more than one interface.
d-i netcfg/choose_interface select auto

# If you have a slow dhcp server and the installer times out waiting for
# it, this might be useful.
#d-i netcfg/dhcp_timeout string 60

# If you prefer to configure the network manually, here's how:
#d-i netcfg/disable_dhcp boolean true
#d-i netcfg/get_nameservers string 192.168.1.1
#d-i netcfg/get_ipaddress string 192.168.1.42
#d-i netcfg/get_netmask string 255.255.255.0
#d-i netcfg/get_gateway string 192.168.1.1
#d-i netcfg/confirm_static boolean true

# Any hostname and domain names assigned from dhcp take precedence over
# values set here. However, setting the values still prevents the questions
# from being shown, even if values come from dhcp.
d-i netcfg/get_hostname string unassigned-hostname
d-i netcfg/get_domain string unassigned-domain

# Disable that annoying WEP key dialog.
d-i netcfg/wireless_wep string
# The wacky dhcp hostname that some ISPs use as a password of sorts.
#d-i netcfg/dhcp_hostname string radish
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-mirror">
  <title>Mirror settings</title>
<para>

Depending on the installation method you use, a mirror may used both to
download additional components of the installer, the base system and to
set up the <filename>/etc/apt/sources.list</filename> for the installed
system.

</para><para>

The parameter <classname>mirror/suite</classname> determines the suite for
the installed system.

</para><para>

The parameter <classname>mirror/udeb/suite</classname> determines the suite
for additional components for the installer. It is only useful to set this
if components are actually downloaded over the network and should match the
suite that was used to build the initrd for the installation method used for
the installation.
By default the value for <classname>mirror/udeb/suite</classname> is the same
as <classname>mirror/suite</classname>.

</para>

<informalexample><screen>
d-i mirror/country string enter information manually
d-i mirror/http/hostname string http.us.debian.org
d-i mirror/http/directory string /debian
d-i mirror/http/proxy string

# Suite to install.
#d-i mirror/suite string testing
# Suite to use for loading installer components (optional).
#d-i mirror/udeb/suite string testing
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-partman">
  <title>Partitioning</title>
<para>

Using preseeding to partition the harddisk is very much limited to what is
supported by <classname>partman-auto</classname>. You can choose to either
partition existing free space on a disk or a whole disk. The layout of the
disk can be determined by using a predefined recipe, a custom recipe from
a recipe file or a recipe included in the preseed file. It is currently not
possible to partition multiple disks using preseeding nor to set up RAID or
LVM.

</para>

<warning><para>

The identification of disks is dependent on the order in which their drivers
are loaded. If there are multiple disks in the system, make very sure the
correct one will be selected before using preseeding.

</para></warning>

<informalexample><screen>
# If the system has free space you can choose to only partition that space.
#d-i partman-auto/init_automatically_partition \
#      select Use the largest continuous free space

# Alternatively, you can specify a disk to partition. The device name can
# be given in either devfs or traditional non-devfs format.
# For example, to use the first disk devfs knows of:
d-i partman-auto/disk string /dev/discs/disc0/disc

# You can choose from any of the predefined partitioning recipes:
d-i partman-auto/choose_recipe \
       select All files in one partition (recommended for new users)
#d-i partman-auto/choose_recipe \
#       select Separate /home partition
#d-i partman-auto/choose_recipe \
#       select Separate /home, /usr, /var, and /tmp partitions

# Or provide a recipe of your own...
# The recipe format is documented in the file devel/partman-auto-recipe.txt.
# If you have a way to get a recipe file into the d-i environment, you can
# just point at it.
#d-i partman-auto/expert_recipe_file string /hd-media/recipe

# If not, you can put an entire recipe the preseed file in one (logical)
# line. This example creates a small /boot partition, suitable swap, and
# uses the rest of the space for the root partition:
#d-i partman-auto/expert_recipe string                         \
#      boot-root ::                                            \
#              40 50 100 ext3                                  \
#                      $primary{ } $bootable{ }                \
#                      method{ format } format{ }              \
#                      use_filesystem{ } filesystem{ ext3 }    \
#                      mountpoint{ /boot }                     \
#              .                                               \
#              500 10000 1000000000 ext3                       \
#                      method{ format } format{ }              \
#                      use_filesystem{ } filesystem{ ext3 }    \
#                      mountpoint{ / }                         \
#              .                                               \
#              64 512 300% linux-swap                          \
#                      method{ swap } format{ }                \
#              .

# This makes partman automatically partition without confirmation.
d-i partman/confirm_write_new_label boolean true
d-i partman/choose_partition \
       select Finish partitioning and write changes to disk
d-i partman/confirm boolean true
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-time">
  <title>Clock and time zone setup</title>

<informalexample><screen>
# Controls whether or not the hardware clock is set to UTC.
d-i clock-setup/utc boolean true

# You may set this to any valid setting for $TZ; see the contents of
# /usr/share/zoneinfo/ for valid values.
d-i time/zone string US/Eastern
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-account" condition="NOT-YET">
  <title>Account setup</title>
<para>

The password for the root account and name and password for a first regular
user's account can be preseeded. For the passwords you can use either clear
text values or MD5 <emphasis>hashes</emphasis>.

</para>
<warning><para>

Be aware that preseeding passwords is not completely secure as everyone
with physical access to the preseed file will have the knowledge of these
passwords. Using MD5 hashes is considered slightly better in terms of
security but it might also give a false sense of security as physical
access to a MD5 hash allows for brute force attacks.

</para></warning>

<informalexample><screen>
# Root password, either in clear text
#passwd passwd/root-password password r00tme
#passwd passwd/root-password-again password r00tme
# or encrypted using an MD5 hash.
#passwd passwd/root-password-crypted password [MD5 hash]

# Skip creation of a normal user account.
#passwd passwd/make-user boolean false

# Alternatively, create a normal user account.
#passwd passwd/user-fullname string Debian User
#passwd passwd/username string debian
# Normal user's password, either in clear text
#passwd passwd/user-password password insecure
#passwd passwd/user-password-again password insecure
# or encrypted using an MD5 hash.
#passwd passwd/user-password-crypted password [MD5 hash]
</screen></informalexample>

<para>

The <classname>passwd/root-password-crypted</classname> and
<classname>passwd/user-password-crypted</classname> variables can also be
preseeded with <quote>!</quote> as value. In that case, the corresponding
account is disabled. This may be convenient for the root account, provided
of course that an alternate method is setup to allow administrative
activities or root login (for instance by using SSH key authentication).

</para>
  </sect2>

  <sect2 id="preseed-bootloader">
  <title>Boot loader installation</title>

<informalexample><screen>
# Grub is the default boot loader (for x86). If you want lilo installed
# instead, uncomment this:
#d-i grub-installer/skip boolean true

# This is fairly safe to set, it makes grub install automatically to the MBR
# if no other operating system is detected on the machine.
d-i grub-installer/only_debian boolean true

# This one makes grub-installer install to the MBR if if finds some other OS
# too, which is less safe as it might not be able to boot that other OS.
d-i grub-installer/with_other_os boolean true

# Alternatively, if you want to install to a location other than the mbr,
# uncomment and edit these lines:
#d-i grub-installer/bootdev  string (hd0,0)
#d-i grub-installer/only_debian boolean false
#d-i grub-installer/with_other_os boolean false
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-finish">
  <title>Finishing up the first stage install</title>

<informalexample><screen>
# Avoid that last message about the install being complete.
d-i prebaseconfig/reboot_in_progress note

# This will prevent the installer from ejecting the CD during the reboot,
# which is useful in some situations.
#d-i cdrom-detect/eject boolean false
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-shell">
  <title>Shell commands</title>

<informalexample><screen>
# d-i preseeding is inherently not secure. Nothing in the installer checks
# for attempts at buffer overflows or other exploits of the values of a
# preseed file like this one. Only use preseed files from trusted
# locations! To drive that home, and because it's generally useful, here's
# a way to run any shell command you'd like inside the installer,
# automatically.

# This first command is run as early as possible, just after
# preseeding is read.
#d-i preseed/early_command string anna-install some-udeb

# This command is run just before the install finishes, but when there is
# still a usable /target directory.
#d-i preseed/late_command string echo foo > /target/etc/bar

# This command is run just as base-config is starting up.
#base-config base-config/early_command string echo hi mom

# This command is run after base-config is done, just before the login:
# prompt. This is a good way to install a set of packages you want, or to
# tweak the configuration of the system.
#base-config base-config/late_command \
#      string apt-get install zsh; chsh -s /bin/zsh
</screen></informalexample>

  </sect2>
 </sect1>

 <sect1 id="preseed-stage2">
 <title>Preseeding the second stage of the installation</title>

  <sect2 id="preseed-baseconfig">
  <title>Base config</title>

<informalexample><screen>
# Avoid the introductory message.
base-config base-config/intro note

# Avoid the final message.
base-config base-config/login note

# If you installed a display manager, but don't want to start it immediately
# after base-config finishes.
#base-config base-config/start-display-manager boolean false

# Some versions of the installer can report back on what you've installed.
# The default is not to report back, but sending reports helps the project
# determine what software is most popular and include it on CDs.
#popularity-contest popularity-contest/participate boolean false
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-account">
  <title>Account setup</title>

<informalexample><screen>
# To preseed the root password, you have to put it in the clear in this
# file. That is not a very good idea, use caution!
#passwd passwd/root-password password r00tme
#passwd passwd/root-password-again password r00tme

# If you want to skip creation of a normal user account.
#passwd passwd/make-user boolean false

# Alternatively, you can preseed the user's name and login.
#passwd passwd/user-fullname string Debian User
#passwd passwd/username string debian
# And their password, but use caution!
#passwd passwd/user-password password insecure
#passwd passwd/user-password-again password insecure
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-apt">
  <title>Apt setup</title>

<informalexample><screen>
# This question controls what source the second stage installation uses
# for packages. Choices are cdrom, http, ftp, filesystem, edit sources list
# by hand
base-config apt-setup/uri_type select http

# If you choose ftp or http, you'll be asked for a country and a mirror.
base-config apt-setup/country select enter information manually
base-config apt-setup/hostname string http.us.debian.org
base-config apt-setup/directory string /debian
# Stop after choosing one mirror.
base-config apt-setup/another boolean false

# You can choose to install non-free and contrib software.
#base-config apt-setup/non-free boolean true
#base-config apt-setup/contrib boolean true

# Do enable security updates.
base-config apt-setup/security-updates boolean true
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-tasksel">
  <title>Package selection</title>
<para>

You can choose to install any combination of tasks that are available.
Available tasks as of this writing include:

<itemizedlist>
<listitem><para>
  <userinput>Standard system</userinput>
</para></listitem>
<listitem><para>
  <userinput>Desktop environment</userinput>
</para></listitem>
<listitem><para>
  <userinput>Web server</userinput>
</para></listitem>
<listitem><para>
  <userinput>Print server</userinput>
</para></listitem>
<listitem><para>
  <userinput>DNS server</userinput>
</para></listitem>
<listitem><para>
  <userinput>File server</userinput>
</para></listitem>
<listitem><para>
  <userinput>Mail server</userinput>
</para></listitem>
<listitem><para>
  <userinput>SQL database</userinput>
</para></listitem>
<listitem><para>
  <userinput>Laptop</userinput>
</para></listitem>
<listitem><para>
  <userinput>manual package selection</userinput>
</para></listitem>
</itemizedlist>

The last of these will run aptitude. You can also choose to install no tasks,
and force the installation of a set of packages in some other way. We recommend
always including the <userinput>Standard system</userinput> task.

</para>

<informalexample><screen>
tasksel tasksel/first multiselect Standard system, Desktop environment
#tasksel tasksel/first multiselect Standard system, Web server
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-mailer">
  <title>Mailer configuration</title>
<para>

During a normal install, exim asks only a few questions. Here's how to
avoid even those. More complicated preseeding is possible.

</para>

<informalexample><screen>
exim4-config exim4/dc_eximconfig_configtype \
       select no configuration at this time
exim4-config exim4/no_config boolean true
exim4-config exim4/no_config boolean true

# It's a good idea to set this to whatever user account you choose to
# create. Leaving the value blank results in postmaster mail going to
# /var/mail/mail.
exim4-config exim4/dc_postmaster string
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-X">
  <title>X configuration</title>
<para>

Preseeding Debian's X config is possible, but you probably need to know
some details about the video hardware of the machine, since Debian's X
configurator does not do fully automatic configuration of everything.

</para>

<informalexample><screen>
# X can detect the right driver for some cards, but if you're preseeding,
# you override whatever it chooses. Still, vesa will work most places.
#xserver-xfree86 xserver-xfree86/config/device/driver select vesa

# A caveat with mouse autodetection is that if it fails, X will retry it
# over and over. So if it's preseeded to be done, there is a possibility of
# an infinite loop if the mouse is not autodetected.
#xserver-xfree86 xserver-xfree86/autodetect_mouse boolean true

# Monitor autodetection is recommended.
xserver-xfree86 xserver-xfree86/autodetect_monitor boolean true
# Uncomment if you have an LCD display.
#xserver-xfree86 xserver-xfree86/config/monitor/lcd boolean true
# X has three configuration paths for the monitor. Here's how to preseed
# the "medium" path, which is always available. The "simple" path may not
# be available, and the "advanced" path asks too many questions.
xserver-xfree86 xserver-xfree86/config/monitor/selection-method \
       select medium
xserver-xfree86 xserver-xfree86/config/monitor/mode-list \
       select 1024x768 @ 60 Hz
</screen></informalexample>

  </sect2>

  <sect2 id="preseed-other">
  <title>Preseeding other packages</title>

<informalexample><screen>
# Depending on what software you choose to install, or if things go wrong
# during the installation process, it's possible that other questions may
# be asked. You can preseed those too, of course. To get a list of every
# possible question that could be asked during an install, do an
# installation, and then run these commands:
#   debconf-get-selections --installer > file
#   debconf-get-selections >> file
</screen></informalexample>

  </sect2>
 </sect1>

 <sect1 id="preseed-advanced">
 <title>Advanced options</title>
<para>

It is possible to include other preseed files from a preseed file. Any
settings in those files will override pre-existing settings from files
loaded earlier. This makes it possible to put, for example, general
networking settings for your location in one file and more specific
settings for certain configurations in other files.

</para>

<informalexample><screen>
# More that one file can be listed, separated by spaces; all will be
# loaded. The included files can have preseed/include directives of their
# own as well. Note that if the filenames are relative, they are taken from
# the same directory as the preseed file that includes them.
#d-i preseed/include string x.cfg

# The installer can optionally verify checksums of preseed files before
# using them. Currently only md5sums are supported, list the md5sums
# in the same order as the list of files to include.
#d-i preseed/include/checksum string 5da499872becccfeda2c4872f9171c3d

# More flexibly, this runs a shell command and if it outputs the names of
# preseed files, includes those files. 
#d-i preseed/include_command \
#      string echo if [ "`hostname`" = bob ]; then echo bob.cfg; fi
</screen></informalexample>

 </sect1>
</appendix>