If you have any other operating systems on your system that you wish to keep (dual boot setup), you should make sure that they have been properly shut down before you boot the installer. Installing an operating system while another operating system is in hibernation (has been suspended to disk) could result in loss of, or damage to the state of the suspended operating system which could cause problems when it is rebooted.

If your computer will boot from USB, this will probably be the easiest route for installation. Assuming you have prepared everything, just plug your USB stick into some free USB connector and reboot the computer. The system should boot up, and unless you have used the flexible way to build the stick and not enabled it, you should be presented with a graphical boot menu (on hardware that supports it). Here you can select various installer options, or just hit Enter.

If you have a CD set, and if your machine supports booting directly off the CD, great! Simply configure your system for booting, insert your CD, reboot, and proceed to the next chapter.

Note that certain CD drives may require special drivers, and thus be inaccessible in the early instal-lation stages. If it turns out the standard way of booting off a CD doesn’t work for your hardware, revisit this chapter and read about alternate kernels and installation methods which may work for you.

Even if you cannot boot from CD-ROM, you can probably install the BlackWeb Linux system components and any packages you want from CD-ROM. Simply boot using a different medium and when it’s time to install the operating system, base system, and any additional packages, point the installation system at the CD-ROM drive.

To start the installer from Windows, you can either

• obtain CD-ROM/DVD-ROM or USB memory stick installation media

• download a standalone Windows executable, which is available as tools/win32-loader/stable/win32-loader.exe on the BlackWeb Linux mirrors

If you use an installation CD or DVD, a pre-installation program should be launched automatically when you insert the disc. In case Windows does not start it automatically, or if you are using a USB memory stick, you can run it manually by accessing the device and executing setup.exe.

After the program has been started, a few preliminary questions will be asked and the system will be prepared to reboot into the BlackWeb Linux GNU/Linux installer.

Boot into DOS (not Windows). To do this, you can for instance boot from a recovery or diagnostic disk.

If you can access the installation CD, change the current drive to the CD-ROM drive, e.g.

d:

else make sure you have first prepared your hard disk as explained in Section 4.4.2, and change the current drive to it if needed.

Enter the subdirectory for the flavor you chose, e.g.,

cd \install.386

If you prefer using the graphical installer, enter the gtk sub-directory.

cd gtk

Next, execute install.bat. The kernel will load and launch the installer system.

To boot the installer from hard disk, you must first download and place the needed files as described in Section 4.4.

If you intend to use the hard drive only for booting and then download everything over the net-work, you should download the netboot/BlackWeb Linux-installer/i386/initrd.gz file and its cor-responding kernel netboot/BlackWeb Linux-installer/i386/linux. This will allow you to repartition the hard disk from which you boot the installer, although you should do so with care.

Alternatively, if you intend to keep an existing partition on the hard drive unchanged during the install, you can download the hd-media/initrd.gz file and its kernel, as well as copy a CD (or DVD) iso to the drive (make sure the file is named ending in .iso). The installer can then boot from the drive and install from the CD/DVD image, without needing the network.

For LILO, you will need to configure two essential things in /etc/lilo.conf:

• to load the initrd.gz installer at boot time;

• have the vmlinuz kernel use a RAM disk as its root partition. Here is a /etc/lilo.conf example:

image=/boot/newinstall/vmlinuz

label=newinstall

initrd=/boot/newinstall/initrd.gz

For more details, refer to the initrd(4) and lilo.conf(5) man pages. Now run lilo and reboot.

The procedure for GRUB1 is quite similar. Locate your menu.lst in the /boot/grub/ directory (or sometimes /boot/boot/grub/) and add an entry for the installer, for example (assuming /boot is on the first partition of the first disk in the system):

title New Install

root (hd0,0)

kernel /boot/newinstall/vmlinuz

initrd /boot/newinstall/initrd.gz

The procedure for GRUB2 is very similar. The file is named grub.cfg instead of menu.lst. An entry for the installer would be for instance for example:

menuentry ’New Install’ {

insmod part_msdos

insmod ext2

set root=’(hd0,msdos1)’

linux /boot/newinstall/vmlinuz

initrd /boot/newinstall/initrd.gz

}

From here on, there should be no difference between GRUB or LILO.

Booting from the network requires that you have a network connection and a TFTP network boot server (and probably also a DHCP, RARP, or BOOTP server for automatic network configuration).

It could be that your Network Interface Card or Motherboard provides PXE boot functionality. This is a Intel™ re-implementation of TFTP boot. If so, you may be able to configure your BIOS to boot from the network.

It could be that your Network Interface Card provides TFTP boot functionality.

The etherboot project (http://www.etherboot.org) provides bootdiskettes and even bootroms that do a TFTPboot.

When the installer boots, you should be presented with a friendly graphical screen showing the BlackWeb Linux logo and a menu:

Installer boot menu

Install

Graphical install

Advanced options >

Help

Install with speech synthesis

Note: This graphical screen will look very slightly different depending on how your computer has booted (BIOS or UEFI), but the same options will be shown.

Depending on the installation method you are using, the “Graphical install” option may not be avail-able. Bi-arch images additionally have a 64 bit variant for each install option, right below it, thus almost doubling the number of options.

For a normal installation, select either the “Graphical install” or the “Install” entry — using either the arrow keys on your keyboard or by typing the first (highlighted) letter — and press Enter to boot the installer. The “Install” entry is already selected by default.

The “Advanced options” entry gives access to a second menu that allows to boot the installer in expert mode, in rescue mode and for automated installs.

If you wish or need to add any boot parameters for either the installer or the kernel, press Tab (BIOS boot) or e (UEFI boot). This will display the boot command for the selected menu entry and allow you to edit it to suit your needs. The help screens (see below) list some common possible options. Press Enter (BIOS boot) or F10 (UEFI boot) to boot the installer with your options; pressing Esc will return you to the boot menu and undo any changes you made.

Choosing the “Help” entry will result in the first help screen being displayed which gives an overview of all available help screens. To return to the boot menu after the help screens have been displayed, type ’menu’ at the boot prompt and press Enter. All help screens have a boot prompt at which the boot command can be typed:

Press F1 for the help index, or ENTER to boot:

At this boot prompt you can either just press Enter to boot the installer with default options or enter a specific boot command and, optionally, boot parameters. A number of boot parameters which might be useful can be found on the various help screens. If you do add any parameters to the boot command line, be sure to first type the boot method (the default is install) and a space before the first parameter (e.g., install fb=false).

When the installer boots, you should be presented with a friendly graphical screen showing the BlackWeb Linux logo and a menu:

Installer boot menu

Install

Graphical install

Advanced options >

Help

Install with speech synthesis

Note: This graphical screen will look very slightly different depending on how your computer has booted (BIOS or UEFI), but the same options will be shown.

Depending on the installation method you are using, the “Graphical install” option may not be avail-able. Bi-arch images additionally have a 64 bit variant for each install option, right below it, thus almost doubling the number of options.

For a normal installation, select either the “Graphical install” or the “Install” entry — using either the arrow keys on your keyboard or by typing the first (highlighted) letter — and press Enter to boot the installer. The “Install” entry is already selected by default.

The “Advanced options” entry gives access to a second menu that allows to boot the installer in expert mode, in rescue mode and for automated installs.

If you wish or need to add any boot parameters for either the installer or the kernel, press Tab (BIOS boot) or e (UEFI boot). This will display the boot command for the selected menu entry and allow you to edit it to suit your needs. The help screens (see below) list some common possible options. Press Enter (BIOS boot) or F10 (UEFI boot) to boot the installer with your options; pressing Esc will return you to the boot menu and undo any changes you made.

Choosing the “Help” entry will result in the first help screen being displayed which gives an overview of all available help screens. To return to the boot menu after the help screens have been displayed, type ’menu’ at the boot prompt and press Enter. All help screens have a boot prompt at which the boot command can be typed:

Press F1 for the help index, or ENTER to boot:

At this boot prompt you can either just press Enter to boot the installer with default options or enter a specific boot command and, optionally, boot parameters. A number of boot parameters which might be useful can be found on the various help screens. If you do add any parameters to the boot command line, be sure to first type the boot method (the default is install) and a space before the first parameter (e.g., install fb=false).

The graphical version of the installer is only available for a limited number of architectures, including 32-bit PC. The functionality of the graphical installer is essentially the same as that of the text-based installer as it basically uses the same programs, but with a different frontend.

Although the functionality is identical, the graphical installer still has a few significant advantages. The main advantage is that it supports more languages, namely those that use a character set that cannot be displayed with the text-based “newt” frontend. It also has a few usability advantages such as the option to use a mouse, and in some cases several questions can be displayed on a single screen.

The graphical installer is available with all CD images and with the hd-media installation method. To boot the graphical installer simply select the relevant option from the boot menu. Expert and rescue mode for the graphical installer can be selected from the “Advanced options” menu. The previously used boot methods installgui, expertgui and rescuegui can still be used from the boot prompt which is shown after selecting the “Help” option in the boot menu.

There is also a graphical installer image that can be netbooted. And there is a special “mini” ISO image1, which is mainly useful for testing.

Just as with the text-based installer it is possible to add boot parameters when starting the graphical installer.

Note: The graphical installer requires significantly more memory to run than the text-based in-staller: 210MB. If insufficient memory is available, it will automatically fall back to the text-based “newt” frontend.

If the amount of memory in your system is below 80MB, the graphical installer may fail to boot at all while booting the text-based installer would still work. Using the text-based installer is recom-mended for systems with little available memory.

Some users may need specific support because of e.g. some visual impairment. USB braille displays are detected automatically (not serial displays connected via a serial-to-USB converter), but most other accessibility features have to be enabled manually. On machines that support it, the boot menu emits a beep when it is ready to receive keystrokes. Some boot parameters can then be appended to enable accessibility features (see also Section 5.1.7). Note that on most architectures the boot loader interprets your keyboard as a QWERTY keyboard.

The BlackWeb Linux installer supports several front-ends for asking questions, with varying convenience for accessibility: notably, text uses plain text while newt uses text-based dialog boxes. The choice can be made at the boot prompt, see the documentation for BlackWeb Linux_FRONTEND in Section 5.3.2.

Support for software speech synthesis is available on all installer images which have the graphical installer, i.e. all netinst, CD and DVD images, and the netboot gtk variant. It can be activated by selecting it in the boot menu by typing s Enter. The textual version of the installer will then be automatically selected, and support for software speech synthesis will be automatically installed on the target system.

The first question (language) is spoken in english, and the remainder of installation is spoken in the selected language (if available in espeak).

The default speech rate is quite slow. To make it faster, press CapsLock-6. To make it slower, press CapsLock-5. The default volume should be medium. To make it louder, press CapsLock-2. To make it quieter, press CapsLock-1. To get more details on the browsing shortcuts, see the Speakup guide (http://www.linux-speakup.org/spkguide.txt).

Support for hardware speech synthesis devices is available on all installer images which have the graphical installer, i.e. all netinst, CD and DVD images, and the netboot gtk variant. You thus need to select a “Graphical install” entry in the boot menu.

Hardware speech synthesis devices cannot be automatically detected. You thus need to append the speakup.synth=driver boot parameter to tell speakup which driver it should use. driver should be replaced by the driver code for your device (see driver code list (http://www.linux-speakup.org/spkguide.txt)). The textual version of the installer will then be automatically selected, and support for the speech synthesis device will be automatically installed on the target system.

Some accessibility devices are actual boards that are plugged inside the machine and that read text directly from the video memory. To get them to work framebuffer support must be disabled by us-ing the vga=normal fb=false boot parameter. This will however reduce the number of available languages.

If desired a textual version of the bootloader can be activated before adding the boot parameter by typing h Enter.

For users with low vision, the installer can use a high-contrast color theme that makes it more readable.

To enable it, append the theme=dark boot parameter.

Alternatively, BlackWeb Linux can be installed completely automatically by using preseeding. This is docu-mented in Appendix B.

Documentation on accessibility of the installed system is available on the BlackWeb Linux Accessibility wiki page.

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 periph-erals. However, in some cases you’ll have to help the kernel a bit.

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.

Information on many boot parameters can be found in the Linux BootPrompt HOWTO (http://www.tldp.org/HOWTO/BootPrompt-HOWTO.html), including tips for obscure hardware. This section contains only a sketch of the most salient parameters. Some common gotchas are included below.

If you are booting with a serial console, generally the kernel will autodetect this. If you have a video-card (framebuffer) and a keyboard also attached to the computer which you wish to boot via serial console, you may have to pass the console=device argument to the kernel, where device is your serial device, which is usually something like ttyS0.

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

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

The installation system recognizes a few additional boot parameters2 which may be useful.

A number of parameters have a “short form” 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.

debconf/priority (priority)

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

The default installation uses priority=high. This means that both high and critical priority messages are shown, but medium and low priority messages are skipped. If problems are en-countered, the installer adjusts the priority as needed.

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

BlackWeb Linux_FRONTEND

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

• BlackWeb Linux_FRONTEND=noninteractive

• BlackWeb Linux_FRONTEND=text

• BlackWeb Linux_FRONTEND=newt

• BlackWeb Linux_FRONTEND=gtk

The default frontend is BlackWeb Linux_FRONTEND=newt. BlackWeb Linux_FRONTEND=text may be prefer-able for serial console installs. Some specialized types of install media may only offer a limited selection of frontends, but the newt and text frontends are available on most default install media. On architectures that support it, the graphical installer uses the gtk frontend.

BOOT_DEBUG

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.)

BOOT_DEBUG=0

This is the default.

BOOT_DEBUG=1

More verbose than usual.

BOOT_DEBUG=2

Lots of debugging information.

BOOT_DEBUG=3

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

INSTALL_MEDIA_DEV

The value of the parameter is the path to the device to load the BlackWeb Linux installer from. For exam-ple, INSTALL_MEDIA_DEV=/dev/floppy/0

The boot floppy, which normally scans all floppies it can to find the root floppy, can be overridden by this parameter to only look at the one device.

log_host

log_port

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.

lowmem

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.

noshell

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

BlackWeb Linux-installer/framebuffer (fb)

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 vga=normal fb=false. Problem symptoms are error messages about bterm or bogl, a blank screen, or a freeze within a few minutes after starting the install.

BlackWeb Linux-installer/theme (theme)

A theme determines how the user interface of the installer looks (colors, icons, etc.). What themes are available differs per frontend. Currently both the newt and gtk frontends only have a “dark” theme that was designed for visually impaired users. Set the theme by booting with theme=dark.

netcfg/disable_autoconfig

By default, the BlackWeb Linux-installer 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.

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 netcfg/disable_autoconfig=true to prevent any automatic configuration of the network (neither v4 nor v6) and to enter the information manually.

hw-detect/start_pcmcia

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

disk-detect/dmraid/enable (dmraid)

Set to true to enable support for Serial ATA RAID (also called ATA RAID, BIOS RAID or fake RAID) disks in the installer. Note that this support is currently experimental. Additional information can be found on the BlackWeb Linux Installer Wiki (http://wiki.BlackWeb Linux.org/BlackWeb LinuxInstaller/).

preseed/url (url)

Specify the url to a preconfiguration file to download and use for automating the install. See Section 4.6.

preseed/file (file)

Specify the path to a preconfiguration file to load for automating the install. See Section 4.6.

preseed/interactive

Set to true 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 Section B.5.2 for details.

auto-install/enable (auto)

Delay questions that are normally asked before preseeding is possible until after the network is configured. See Section B.2.3 for details about using this to automate installs.

finish-install/keep-consoles

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

cdrom-detect/eject

By default, before rebooting, BlackWeb Linux-installer automatically ejects the optical media used during the installation. This can be unnecessary if the system does not automatically boot off the CD. 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.

Set to false 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.

base-installer/install-recommends (recommends)

By setting this option to false, the package management system will be configured to not automatically install “Recommends”, both during the installation and for the installed system. See also Section 6.3.4.

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.

BlackWeb Linux-installer/allow_unauthenticated

By default the installer requires that repositories be authenticated using a known gpg key. Set to true to disable that authentication. Warning: insecure, not recommended.

rescue/enable

Set to true to enter rescue mode rather than performing a normal installation. See Section 8.7.

With some exceptions, a value can be set at the boot prompt for any question asked during the instal-lation, though this is only really useful in specific cases. General instructions how to do this can be found in Section B.2.2. Some specific examples are listed below.

BlackWeb Linux-installer/language (language)

BlackWeb Linux-installer/country (country)

BlackWeb Linux-installer/locale (locale)

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

The first and easiest is to pass only the parameter locale. Language and country will then be derived from its value. You can for example use locale=de_CH to select German as language and Switzerland as country (de_CH.UTF-8 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.

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

anna/choose_modules (modules)

Can be used to automatically load installer components that are not loaded by default. Examples of optional components that may be useful are openssh-client-udeb (so you can use scp during the installation) and ppp-udeb (see Section D.5).

netcfg/disable_autoconfig

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

mirror/protocol (protocol)

By default the installer will use the http protocol to download files from BlackWeb Linux mirrors and changing that to ftp is not possible during installations at normal priority. By setting this param-eter to ftp, 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.

tasksel:tasksel/first (tasks)

Can be used to select tasks that are not available from the interactive task list, such as the kde-desktop task. See Section 6.3.5.2 for additional information.

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.

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.

The syntax to use to set parameters for modules is:

module_name.parameter_name=value

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:

3c509.xcvr=3 3c509.irq=10

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.

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

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.

Sometimes, especially with older CD-ROM drives, the installer may fail to boot from a CD-ROM. The installer may also — even after booting successfully from CD-ROM — fail to recognize the CD-ROM or return errors while reading from it during the installation.

There are many different possible causes for these problems. We can only list some common issues and provide general suggestions on how to deal with them. The rest is up to you.

There are two very simple things that you should try first.

• If the CD-ROM does not boot, check that it was inserted correctly and that it is not dirty.

• If the installer fails to recognize a CD-ROM, try just running the option Detect and mount CD-ROM a second time. Some DMA related issues with very old CD-ROM drives are known to be resolved in this way.

If this does not work, then try the suggestions in the subsections below. Most, but not all, suggestions discussed there are valid for both CD-ROM and DVD, but we’ll use the term CD-ROM for simplicity.

If you cannot get the installation working from CD-ROM, try one of the other installation methods that are available.

• Some older CD-ROM drives do not support reading from discs that were burned at high speeds using a modern CD writer.

• Some very old CD-ROM drives do not work correctly if “direct memory access” (DMA) is enabled for them.

If the CD-ROM fails to boot, try the suggestions listed below.

• Check that your BIOS actually supports booting from CD-ROM (only an issue for very old systems) and that CD booting is enabled in the BIOS.

• If you downloaded an iso image, check that the md5sum of that image matches the one listed for the image in the MD5SUMS file that should be present in the same location as where you downloaded the image from.

$ md5sum BlackWeb Linux-testing-i386-netinst.iso a20391b12f7ff22ef705cee4059c6b92 BlackWeb Linux-testing-i386-netinst.iso

Next, check that the md5sum of the burned CD-ROM matches as well. The following command should work. It uses the size of the image to read the correct number of bytes from the CD-ROM.

$ dd if=/dev/cdrom | \

head -c ‘stat –format=%s BlackWeb Linux-testing-i386-netinst.iso‘ | \

md5sum

a20391b12f7ff22ef705cee4059c6b92 -

262668+0 records in

262668+0 records out

134486016 bytes (134 MB) copied, 97.474 seconds, 1.4 MB/s

If, after the installer has been booted successfully, the CD-ROM is not detected, sometimes simply trying again may solve the problem. If you have more than one CD-ROM drive, try changing the CD-ROM to the other drive. If that does not work or if the CD-ROM is recognized but there are errors when reading from it, try the suggestions listed below. Some basic knowledge of Linux is required for this. To execute any of the commands, you should first switch to the second virtual console (VT2) and activate the shell there.

• Switch to VT4 or view the contents of /var/log/syslog (use nano as editor) to check for any specific error messages. After that, also check the output of dmesg.

• Check in the output of dmesg if your CD-ROM drive was recognized. You should see something like (the lines do not necessarily have to be consecutive):

Probing IDE interface ide1…

hdc: TOSHIBA DVD-ROM SD-R6112, ATAPI CD/DVD-ROM drive ide1 at 0x170-0x177,0x376 on irq 15

hdc: ATAPI 24X DVD-ROM DVD-R CD-R/RW drive, 2048kB Cache, UDMA(33)

Uniform CD-ROM driver Revision: 3.20

If you don’t see something like that, chances are the controller your CD-ROM is connected to was not recognized or may be not supported at all. If you know what driver is needed for the controller, you can try loading it manually using modprobe.

• Check that there is a device node for your CD-ROM drive under /dev/. In the example above, this would be /dev/hdc. There should also be a /dev/cdrom.

• Use the mount command to check if the CD-ROM is already mounted; if not, try mounting it manually:

$ mount /dev/hdc /cdrom

Check if there are any error messages after that command.

• Check if DMA is currently enabled:

$ cd /proc/ide/hdc $ grep using_dma settings using_dma 1 0 1 rw

A “1” in the first column after using_dma means it is enabled. If it is, try disabling it:

$ echo -n “using_dma:0” >settings

Make sure that you are in the directory for the device that corresponds to your CD-ROM drive.

• If there are any problems during the installation, try checking the integrity of the CD-ROM using the option near the bottom of the installer’s main menu. This option can also be used as a general test if the CD-ROM can be read reliably.

If you have problems and the kernel hangs during the boot process, doesn’t recognize peripherals you actually have, or drives are not recognized properly, the first thing to check is the boot parameters, as discussed in Section 5.3.

In some cases, malfunctions can be caused by missing device firmware (see Section 2.2 and Section 6.4).

If software speech synthesis does not work, there is most probably an issue with your sound board, usually because either the driver for it is not included in the installer, or because it has unusual mixer level names which are set to muted by default. You should thus submit a bug report which includes the output of the following commands, run on the same machine from a Linux system which is known to have sound working (e.g., a live CD).

• dmesg

• lspci

• lsmod

• amixer

There are some common installation problems that can be solved or avoided by passing certain boot parameters to the installer.

If your screen begins to show a weird picture while the kernel boots, eg. pure white, pure black or colored pixel garbage, your system may contain a problematic video card which does not switch to the framebuffer mode properly. Then you can use the boot parameter fb=false to disable the framebuffer console. Only a reduced set of languages will be available during the installation due to limited console features.

Some very old laptop models produced by Dell are known to crash when PCMCIA device detection tries to access some hardware addresses. Other laptops may display similar problems. If you expe-rience such a problem and you don’t need PCMCIA support during the installation, you can disable PCMCIA using the hw-detect/start_pcmcia=false boot parameter. You can then configure PCMCIA after the installation is completed and exclude the resource range causing the problems.

Alternatively, you can boot the installer in expert mode. You will then be asked to enter the re-source range options your hardware needs. For example, if you have one of the Dell laptops men-tioned above, you should enter exclude port 0x800-0x8ff here. There is also a list of some common resource range options in the System resource settings section of the PCMCIA HOWTO (http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-HOWTO-1.html#ss1.12). Note that you have to omit the commas, if any, when you enter this value in the installer.

During the boot sequence, you may see many messages in the form can’t find something, or something not present, can’t initialize something, or even this driver release depends on something. Most of these messages are harmless. You see them because the kernel for the installation system is built to run on computers with many different peripheral devices. Obviously, no one computer will have every possible peripheral device, so the operating system may emit a few complaints while it looks for peripherals you don’t own. You may also see the system pause for a while. This happens when it is waiting for a device to respond, and that device is not present on your system. If you find the time it takes to boot the system unacceptably long, you can create a custom kernel later (see Section 8.6).

If you get through the initial boot phase but cannot complete the install, the menu option Save de-bug logs may be helpful. It lets you store system error logs and configuration information from the installer to a floppy, or download them using a web browser. This information may provide clues as to what went wrong and how to fix it. If you are submitting a bug report, you may want to attach this information to the bug report.

Other pertinent installation messages may be found in /var/log/ during the installation, and /var/log/installer/ after the computer has been booted into the installed system.

If you still have problems, please submit an installation report. We also encourage installation reports to be sent even if the installation is successful, so that we can get as much information as possible on the largest number of hardware configurations.

Note that your installation report will be published in the BlackWeb Linux Bug Tracking System (BTS) and forwarded to a public mailing list. Make sure that you use an e-mail address that you do not mind being made public.

If you have a working BlackWeb Linux system, the easiest way to send an installation report is to install the installation-report and reportbug packages (aptitude install installation-report re-portbug), configure reportbug as explained in Section 8.5.2, and run the command reportbug installation-reports.

Alternatively you can use this template when filling out installation reports, and file the report as a bug report against the installation-reports pseudo package, by sending it to <submit@bugs.BlackWeb Linux.org>.

Package: installation-reports

Boot method: <How did you boot the installer? CD? floppy? network?>

Image version: <Full URL to image you downloaded is best>

Date: <Date and time of the install>

Machine: <Description of machine (eg, IBM Thinkpad R32)>

Processor:

Memory:

Partitions: <df -Tl will do; the raw partition table is preferred>

Output of lspci -knn (or lspci -nn):

Base System Installation Checklist:

[O] = OK, [E] = Error (please elaborate below), [ ] = didn’t try it

Initial boot: [ ]

Detect network card: [ ]

Configure network: [ ]

Detect CD: [ ]

Load installer modules: [ ]

Detect hard drives: [ ]

Partition hard drives: [ ]

Install base system: [ ]

Clock/timezone setup: [ ]

User/password setup: [ ]

Install tasks: [ ]

Install boot loader: [ ]

Overall install: [ ]

Comments/Problems:

<Description of the install, in prose, and any thoughts, comments and ideas you had during the initial install.>

In the bug report, describe what the problem is, including the last visible kernel messages in the event of a kernel hang. Describe the steps that you did which brought the system into the problem state.