path: root/en/boot-installer/parameters.xml

<!-- retain these comments for translator revision tracking -->
<!-- $Id$ -->

 <sect1 id="boot-parms"><title>Boot Parameters</title>
<para arch="linux-any">

Boot parameters are Linux kernel parameters which are generally used
to make sure that peripherals are dealt with properly.  For the most
part, the kernel can auto-detect information about your peripherals.
However, in some cases you'll have to help the kernel a bit.

</para><para>

If this is the first time you're booting the system, try the default
boot parameters (i.e., don't try setting parameters) and see if it works
correctly. It probably will.  If not, you can reboot later and look for
any special parameters that inform the system about your hardware.

</para><para arch="linux-any">

Information on many boot parameters can be found in the
<ulink url="http://www.tldp.org/HOWTO/BootPrompt-HOWTO.html"> Linux
BootPrompt HOWTO</ulink>, including tips for obscure hardware.  This
section contains only a sketch of the most salient parameters.  Some
common gotchas are included below in
<xref linkend="boot-troubleshooting"/>.

</para>

  <sect2 id="boot-console" arch="linux-any" condition="supports-serial-console">
  <title>Boot console</title>

<para>

If you are booting with a serial console, generally the kernel will
autodetect this.
If you have a videocard (framebuffer) and a keyboard also attached to
the computer which you wish to boot via serial console, you may have
to pass the
<userinput>console=<replaceable>device</replaceable></userinput>
argument to the kernel, where <replaceable>device</replaceable> is
a serial device of the target, which is usually something like
<filename>ttyS0</filename>.

</para><para>

You may need to specify parameters for the serial port, such as speed and
parity, for instance <userinput>console=ttyS0,9600n8</userinput>; other typical
speeds may be 57600 or 115200.  Be sure to specify this option after
<quote>---</quote>, so that it is copied into the bootloader configuration for
the installed system (if supported by the installer for the bootloader).

</para><para>

In order to ensure the terminal type used by the installer matches your
terminal emulator, the parameter
<userinput>TERM=<replaceable>type</replaceable></userinput> can be added.
Note that the installer only supports the following terminal types:
<literal>linux</literal>, <literal>bterm</literal>, <literal>ansi</literal>,
<literal>vt102</literal> and <literal>dumb</literal>. The default for
serial console in &d-i; is <userinput>vt102</userinput>. If you are using an IPMI console, or a
virtualization tool which does not provide conversion into such terminals types
itself, e.g. QEMU/KVM, you can start it inside a <command>screen</command>
session. That will indeed perform translation into the <literal>screen</literal>
terminal type, which is very close to <literal>vt102</literal>.

</para>

  </sect2>

  <sect2 id="installer-args"><title>&debian; Installer Parameters</title>
<para>

The installation system recognizes a few additional boot parameters<footnote>

<para>

With current kernels (2.6.9 or newer) you can use 32 command line options and
32 environment options. If these numbers are exceeded, the kernel will panic.
Also there is a limit of 255 characters for the whole kernel command line,
everything above this limit may be silently truncated.

</para>

</footnote> which may be useful.

</para><para>

A number of parameters have a <quote>short form</quote> that helps avoid
the limitations of the kernel command line options and makes entering the
parameters easier. If a parameter has a short form, it will be listed in
brackets behind the (normal) long form. Examples in this manual will
normally use the short form too.

</para>

<variablelist>
<varlistentry>
<term>debconf/priority (priority)</term>
<listitem><para>

This parameter sets the lowest priority of messages to be displayed.

</para><para>

The default installation uses <userinput>priority=high</userinput>.
This means that both high and critical priority messages are shown, but medium
and low priority messages are skipped.
If problems are encountered, the installer adjusts the priority as needed.

</para><para>

If you add <userinput>priority=medium</userinput> as boot parameter, you
will be shown the installation menu and gain more control over the installation.
When <userinput>priority=low</userinput> is used, all messages are shown
(this is equivalent to the <emphasis>expert</emphasis> boot method).
With <userinput>priority=critical</userinput>, the installation system
will display only critical messages and try to do the right thing without fuss.

</para></listitem>
</varlistentry>


<varlistentry>
<term>DEBIAN_FRONTEND</term>
<listitem><para>

This boot parameter controls the type of user interface used for the
installer. The current possible parameter settings are:

<itemizedlist>
<listitem>
<para><userinput>DEBIAN_FRONTEND=noninteractive</userinput></para>
</listitem><listitem>
<para><userinput>DEBIAN_FRONTEND=text</userinput></para>
</listitem><listitem>
<para><userinput>DEBIAN_FRONTEND=newt</userinput></para>
</listitem><listitem>
<para><userinput>DEBIAN_FRONTEND=gtk</userinput></para>
</listitem>
</itemizedlist>

The default frontend is <userinput>DEBIAN_FRONTEND=newt</userinput>.
<userinput>DEBIAN_FRONTEND=text</userinput> may be preferable for
serial console installs. Some specialized types of install media may
only offer a limited selection of frontends, but the
<userinput>newt</userinput> and <userinput>text</userinput> frontends
are available on most default install media.
On architectures that support it, the graphical installer uses
the <userinput>gtk</userinput> frontend.

</para></listitem>
</varlistentry>


<varlistentry>
<term>BOOT_DEBUG</term>
<listitem><para>

Setting this boot parameter to 2 will cause the installer's boot process
to be verbosely logged. Setting it to 3 makes debug shells
available at strategic points in the boot process. (Exit the shells to
continue the boot process.)

<variablelist>
<varlistentry>
<term><userinput>BOOT_DEBUG=0</userinput></term>
<listitem><para>This is the default.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>BOOT_DEBUG=1</userinput></term>
<listitem><para>More verbose than usual.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>BOOT_DEBUG=2</userinput></term>
<listitem><para>Lots of debugging information.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>BOOT_DEBUG=3</userinput></term>
<listitem><para>

Shells are run at various points in the boot process to allow detailed
debugging. Exit the shell to continue the boot.

</para></listitem>
</varlistentry>
</variablelist>

</para></listitem>
</varlistentry>


<varlistentry>
<term>log_host</term>
<term>log_port</term>
<listitem><para>

Causes the installer to send log messages to a remote syslog on the
specified host and port as well as to a local file. If not specified, the
port defaults to the standard syslog port 514.

</para></listitem>
</varlistentry>


<varlistentry>
<term>lowmem</term>
<listitem><para>

Can be used to force the installer to a lowmem level higher than the one
the installer sets by default based on available memory. Possible values
are 1 and 2. See also <xref linkend="lowmem"/>.

</para></listitem>
</varlistentry>

<varlistentry>
<term>noshell</term>
<listitem><para>

Prevents the installer from offering interactive shells on tty2 and tty3.
Useful for unattended installations where physical security is limited.

</para></listitem>
</varlistentry>

<varlistentry>
<term>debian-installer/framebuffer (fb)</term>
<listitem><para>

Some architectures use the kernel framebuffer to offer installation in
a number of languages. If framebuffer causes a problem on your system
you can disable the feature using the parameter
<userinput arch="x86">vga=normal</userinput> <userinput>fb=false</userinput>.
Problem symptoms are error messages about bterm or bogl, a blank screen,
or a freeze within a few minutes after starting the install.

</para></listitem>
</varlistentry>

<varlistentry arch="not-s390">
<term>debian-installer/theme (theme)</term>
<listitem><para>

A theme determines how the user interface of the installer looks (colors,
icons, etc.). Which themes are available may differ per frontend.  Currently
both the newt and gtk frontend have (apart from the default look) only
one additional theme named <quote>dark</quote> theme, which was
designed for visually impaired users. Set this theme by booting with 
<userinput>theme=<replaceable>dark</replaceable></userinput>
(there is also the keyboard shortcut <userinput>d</userinput> for this
in the boot menu).

</para></listitem>
</varlistentry>

<varlistentry>
<term>netcfg/disable_autoconfig</term>
<listitem><para>

By default, the &d-i; automatically probes for network configuration
via IPv6 autoconfiguration and DHCP. If the probe succeeds, you won't have a chance to review and
change the obtained settings. You can get to the manual network setup
only in case the automatic configuration fails.

</para><para>

If you have an IPv6 router or a DHCP server on your local network, but want to avoid them
because e.g. they give wrong answers, you can use the parameter
<userinput>netcfg/disable_autoconfig=true</userinput> to prevent any automatic
configuration of the network (neither v4 nor v6) and to enter the information manually.

</para></listitem>
</varlistentry>

<varlistentry>
<term>hw-detect/start_pcmcia</term>
<listitem><para>

Set to <userinput>false</userinput> to prevent starting PCMCIA
services, if that causes problems. Some laptops are well known for
this misbehavior.

</para></listitem>
</varlistentry>

<varlistentry>
<term>preseed/url (url)</term>
<listitem><para>

Specify the url to a preconfiguration file to download and use for
automating the install. See <xref linkend="automatic-install"/>.

</para></listitem>
</varlistentry>

<varlistentry>
<term>preseed/file (file)</term>
<listitem><para>

Specify the path to a preconfiguration file to load for
automating the install. See <xref linkend="automatic-install"/>.

</para></listitem>
</varlistentry>

<varlistentry>
<term>preseed/interactive</term>
<listitem><para>

Set to <userinput>true</userinput> to display questions even if they have
been preseeded. Can be useful for testing or debugging a preconfiguration
file. Note that this will have no effect on parameters that are passed as
boot parameters, but for those a special syntax can be used.
See <xref linkend="preseed-seenflag"/> for details.

</para></listitem>
</varlistentry>

<varlistentry>
<term>auto-install/enable (auto)</term>
<listitem><para>

Delay questions that are normally asked before preseeding is possible until
after the network is configured.
See <xref linkend="preseed-auto"/> for details about using this to
automate installs.

</para></listitem>
</varlistentry>

<varlistentry>
<term>finish-install/keep-consoles</term>
<listitem><para>

During installations from serial or management console, the regular
virtual consoles (VT1 to VT6) are normally disabled in
<filename>/etc/inittab</filename>.
Set to <userinput>true</userinput> to prevent this.

</para></listitem>
</varlistentry>

<varlistentry>
<term>cdrom-detect/eject</term>
<listitem><para>

By default, before rebooting, &d-i; automatically ejects the optical
media used during the installation. This can be unnecessary if the system
does not automatically boot off such media. In some cases it may even be
undesirable, for example if the optical drive cannot reinsert the media
itself and the user is not there to do it manually. Many slot loading,
slim-line, and caddy style drives cannot reload media automatically.

</para><para>

Set to <userinput>false</userinput> to disable automatic ejection, and
be aware that you may need to ensure that the system does not
automatically boot from the optical drive after the initial
installation.

</para></listitem>
</varlistentry>

<varlistentry>
<term>base-installer/install-recommends (recommends)</term>
<listitem><para>

By setting this option to <userinput>false</userinput>, the package
management system will be configured to not automatically install
<quote>Recommends</quote>, both during the installation and for the
installed system. See also <xref linkend="di-install-base"/>.

</para><para>

Note that this option allows to have a leaner system, but can also result
in features being missing that you might normally expect to be available.
You may have to manually install some of the recommended packages to
obtain the full functionality you want. This option should therefore only
be used by very experienced users.

</para></listitem>
</varlistentry>

<varlistentry>
<term>debian-installer/allow_unauthenticated</term>
<listitem><para>

By default the installer requires that repositories be authenticated
using a known gpg key. Set to <userinput>true</userinput> to 
disable that authentication. 
<emphasis role="bold">Warning: insecure, not recommended.</emphasis>

</para></listitem>
</varlistentry>

<varlistentry arch="mipsel;mips64el">
<term>ramdisk_size</term>
<listitem><para>

This parameter should already be set to a correct value where needed;
set it only it you see errors during the boot that indicate the ramdisk
could not be loaded completely. The value is in kB.

</para></listitem>
</varlistentry>

<varlistentry>
<term>rescue/enable</term>
<listitem><para>

Set to <userinput>true</userinput> to enter rescue mode rather than
performing a normal installation. See <xref linkend="rescue"/>.

</para></listitem>
</varlistentry>

</variablelist>

  </sect2>

  <sect2 id="preseed-args">
  <title>Using boot parameters to answer questions</title>
<para>

With some exceptions, a value can be set at the boot prompt for any question
asked during the installation, though this is only really useful in specific
cases. General instructions how to do this can be found in
<xref linkend="preseed-bootparms"/>. Some specific examples are listed below.

</para>

<variablelist>

<varlistentry>
<term>debian-installer/language (language)</term>
<term>debian-installer/country (country)</term>
<term>debian-installer/locale (locale)</term>
<listitem><para>

There are two ways to specify the language, country and locale to use for
the installation and the installed system.

</para><para>

The first and easiest is to pass only the parameter <literal>locale</literal>.
Language and country will then be derived from its value. You can for example
use <userinput>locale=de_CH</userinput> to select German as language and
Switzerland as country (<literal>de_CH.UTF-8</literal> will be set as default
locale for the installed system). Limitation is that not all possible
combinations of language, country and locale can be achieved this way.

</para><para>

The second, more flexible option is to specify <literal>language</literal>
and <literal>country</literal> separately. In this case
<literal>locale</literal> can optionally be added to specify a specific
default locale for the installed system. Example:
<userinput>language=en country=DE locale=en_GB.UTF-8</userinput>.

</para></listitem>
</varlistentry>

<varlistentry>
<term>anna/choose_modules (modules)</term>
<listitem><para>

Can be used to automatically load installer components that are not loaded
by default.
Examples of optional components that may be useful are
<classname>openssh-client-udeb</classname> (so you can use
<command>scp</command> during the installation)<phrase arch="not-s390"> and
<classname>ppp-udeb</classname> (see <xref linkend="pppoe"/>)</phrase>.

</para></listitem>
</varlistentry>

<varlistentry>
<term>netcfg/disable_autoconfig</term>
<listitem><para>

Set to <userinput>true</userinput> if you want to disable IPv6 autoconfiguration
and DHCP and instead force static network configuration.

</para></listitem>
</varlistentry>

<varlistentry>
<term>mirror/protocol (protocol)</term>
<listitem><para>

By default the installer will use the http protocol to download files from
&debian; mirrors and changing that to ftp is not possible during installations
at normal priority. By setting this parameter to <userinput>ftp</userinput>,
you can force the installer to use that protocol instead. Note that you
cannot select an ftp mirror from a list, you have to enter the hostname
manually.

</para></listitem>
</varlistentry>

<varlistentry>
<term>tasksel:tasksel/first (tasks)</term>
<listitem><para>

Can be used to select tasks that are not available from the interactive task
list, such as the <literal>kde-desktop</literal> task.
See <xref linkend="pkgsel"/> for additional information.

</para></listitem>
</varlistentry>

</variablelist>

  </sect2>

  <sect2 id="module-parms">
  <title>Passing parameters to kernel modules</title>
<para>

If drivers are compiled into the kernel, you can pass parameters to them
as described in the kernel documentation. However, if drivers are compiled
as modules and because kernel modules are loaded a bit differently during
an installation than when booting an installed system, it is not possible
to pass parameters to modules as you would normally do. Instead, you need
to use a special syntax recognized by the installer which will then make
sure that the parameters are saved in the proper configuration files and
will thus be used when the modules are actually loaded. The parameters
will also be propagated automatically to the configuration for the installed
system.

</para><para>

Note that it is now quite rare that parameters need to be passed to modules.
In most cases the kernel will be able to probe the hardware present in a
system and set good defaults that way. However, in some situations it may
still be needed to set parameters manually.

</para><para>

The syntax to use to set parameters for modules is:

<informalexample><screen>
<replaceable>module_name</replaceable>.<replaceable>parameter_name</replaceable>=<replaceable>value</replaceable>
</screen></informalexample>

If you need to pass multiple parameters to the same or different modules,
just repeat this. For example, to set an old 3Com network interface card
to use the BNC (coax) connector and IRQ 10, you would pass:

<informalexample><screen>
3c509.xcvr=3 3c509.irq=10
</screen></informalexample>

</para>
  </sect2>

  <sect2 id="module-blacklist">
  <title>Blacklisting kernel modules</title>
<para>

Sometimes it may be necessary to blacklist a module to prevent it from
being loaded automatically by the kernel and udev. One reason could be that
a particular module causes problems with your hardware. The kernel also
sometimes lists two different drivers for the same device. This can cause
the device to not work correctly if the drivers conflict or if the wrong
driver is loaded first.

</para><para>

You can blacklist a module using the following syntax:
<userinput><replaceable>module_name</replaceable>.blacklist=yes</userinput>.
This will cause the module to be blacklisted in
<filename>/etc/modprobe.d/blacklist.local</filename> both during the
installation and for the installed system.

</para><para>

Note that a module may still be loaded by the installation system itself.
You can prevent that from happening by running the installation in expert
mode and unselecting the module from the list of modules displayed during
the hardware detection phases.

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