4 Troubleshooting

4.1 Repairing an Existing FreeBSD Installation

FreeBSD features a “fixit” option in the top menu of the sysinstall(8) installation program. It provides a shell with common programs from the FreeBSD base system; this environment is useful for repairing or troubleshooting an existing FreeBSD installation. To use fixit mode, you will also need either the fixit.flp floppy, generated in the same fashion as the boot floppies, or the “live filesystem” CDROM. In multi-disk FreeBSD distributions, the live filesystem image is typically located on the installation disk. Note that some UNIX system administration experience is required to use the fixit option.

Generally, there are two ways of invoking fixit mode. Users who can boot from the FreeBSD installation CDROM, should do so and then choose the “fixit” item from the main sysinstall(8) menu. Then select the “CDROM/DVD” option from the fixit menu.

Users who cannot boot from CDROM, but can boot from floppy disk, require a few more steps. In addition to the boot.flp and kernX.flp disks required for installation, create the fixit.flp floppy disk, in the same way as the other floppy disks. Follow the instructions for booting the installation program from floppy disk until reaching the main sysinstall(8) menu. At that point, choose the “fixit” item from the main sysinstall(8) menu. Then select the “Floppy” option from the fixit menu, and insert the fixit.flp floppy disk when prompted to do so.

The CDROM and floppy fixit environments are similar, but not identical. Both offer a shell with a variety of commands available for checking, repairing and examining filesystems and their contents. The CDROM version of fixit provides all of the commands and programs available in the FreeBSD base system, through the live filesystem. By contrast, the floppy fixit environment can only offer a subset of commands due to space constraints.

In the floppy version of fixit, some standalone utilities can be found in /stand or /mnt2/stand. In the CDROM version of fixit, these same programs can be found in /stand or /mnt2/rescue (as well as the rest of the programs from the live filesystem, which can be found under /mnt).

4.2 Common Installation Problems for AMD64 Architecture Users

4.2.1. My system hangs while probing hardware during boot, or it behaves strangely during install, or the floppy drive isn't probed.
4.2.2. My system uses the nVidia nForce3 Pro-150 chipset and I get hangs at the end of boot or suddenly starts losing interrupts.
4.2.4. I go to boot from the hard disk for the first time after installing FreeBSD, the kernel loads and probes my hardware, but stops with messages like:
4.2.5. I go to boot from the hard disk for the first time after installing FreeBSD, but the Boot Manager prompt just prints F? at the boot menu each time but the boot won't go any further.
4.2.7. The system finds my ed(4) network card, but I keep getting device timeout errors.
4.2.12. I have this CMD640 IDE controller that is said to be broken.
4.2.15. I have an IBM EtherJet PCI card, it is detected by the fxp(4) driver correctly, but the lights on the card don't come on and it doesn't connect to the network.
4.2.17. When I install onto a drive managed by a Mylex PCI RAID controller, the system fails to boot (eg. with a read error message).

4.2.1. My system hangs while probing hardware during boot, or it behaves strangely during install, or the floppy drive isn't probed.

FreeBSD 5.0 and above makes extensive use of the system ACPI service on the i386, amd64 and ia64 platforms to aid in system configuration if it's detected during boot. Unfortunately, some bugs still exist in both the ACPI driver and within system motherboards and BIOS. The use of ACPI can be disabled by setting the “hint.acpi.0.disabled” hint in the third stage boot loader:

set hint.acpi.0.disabled="1"

This is reset each time the system is booted, so it is necessary to add hint.acpi.0.disabled="1" to the file /boot/loader.conf. More information about the boot loader can be found in the FreeBSD Handbook.

4.2.2. My system uses the nVidia nForce3 Pro-150 chipset and I get hangs at the end of boot or suddenly starts losing interrupts.

There are problems with the apic on this chipset and/or the bios on every machine that we had seen at the time of release. While disabling ACPI as above will work, a less drastic option may be to set the “hint.apic.0.disabled” hint instead. If you have the option in the bios, try disabling the APIC support. Unfortunately some machines lack this option.

4.2.4. I go to boot from the hard disk for the first time after installing FreeBSD, the kernel loads and probes my hardware, but stops with messages like:

changing root device to ad1s1a panic: cannot mount root

What is wrong? What can I do?

What is this bios_drive:interface(unit,partition)kernel_name thing that is displayed with the boot help?

There is a longstanding problem in the case where the boot disk is not the first disk in the system. The BIOS uses a different numbering scheme to FreeBSD, and working out which numbers correspond to which is difficult to get right.

In the case where the boot disk is not the first disk in the system, FreeBSD can need some help finding it. There are two common situations here, and in both of these cases, you need to tell FreeBSD where the root filesystem is. You do this by specifying the BIOS disk number, the disk type and the FreeBSD disk number for that type.

The first situation is where you have two IDE disks, each configured as the master on their respective IDE busses, and wish to boot FreeBSD from the second disk. The BIOS sees these as disk 0 and disk 1, while FreeBSD sees them as ad0 and ad2.

FreeBSD is on BIOS disk 1, of type ad and the FreeBSD disk number is 2, so you would say:

1:ad(2,a)kernel

Note that if you have a slave on the primary bus, the above is not necessary (and is effectively wrong).

The second situation involves booting from a SCSI disk when you have one or more IDE disks in the system. In this case, the FreeBSD disk number is lower than the BIOS disk number. If you have two IDE disks as well as the SCSI disk, the SCSI disk is BIOS disk 2, type da and FreeBSD disk number 0, so you would say:

2:da(0,a)kernel

To tell FreeBSD that you want to boot from BIOS disk 2, which is the first SCSI disk in the system. If you only had one IDE disk, you would use '1:' instead.

Once you have determined the correct values to use, you can put the command exactly as you would have typed it in the /boot.config file using a standard text editor. Unless instructed otherwise, FreeBSD will use the contents of this file as the default response to the boot: prompt.

4.2.5. I go to boot from the hard disk for the first time after installing FreeBSD, but the Boot Manager prompt just prints F? at the boot menu each time but the boot won't go any further.

The hard disk geometry was set incorrectly in the Partition editor when you installed FreeBSD. Go back into the partition editor and specify the actual geometry of your hard disk. You must reinstall FreeBSD again from the beginning with the correct geometry.

If you are failing entirely in figuring out the correct geometry for your machine, here's a tip: Install a small DOS partition at the beginning of the disk and install FreeBSD after that. The install program will see the DOS partition and try to infer the correct geometry from it, which usually works.

The following tip is no longer recommended, but is left here for reference:

If you are setting up a truly dedicated FreeBSD server or workstation where you don't care for (future) compatibility with DOS, Linux or another operating system, you've also got the option to use the entire disk (`A' in the partition editor), selecting the non-standard option where FreeBSD occupies the entire disk from the very first to the very last sector. This will leave all geometry considerations aside, but is somewhat limiting unless you're never going to run anything other than FreeBSD on a disk.

4.2.7. The system finds my ed(4) network card, but I keep getting device timeout errors.

Your card is probably on a different IRQ from what is specified in the /boot/device.hints file. The ed driver does not use the `soft' configuration by default (values entered using EZSETUP in DOS), but it will use the software configuration if you specify -1 in the hints for the interface.

Either move the jumper on the card to a hard configuration setting (altering the kernel settings if necessary), or specify the IRQ as -1 by setting the hint “hint.ed.0.irq="-1"” This will tell the kernel to use the soft configuration.

Another possibility is that your card is at IRQ 9, which is shared by IRQ 2 and frequently a cause of problems (especially when you have a VGA card using IRQ 2!). You should not use IRQ 2 or 9 if at all possible.

4.2.12. I have this CMD640 IDE controller that is said to be broken.

FreeBSD does not support this controller.

4.2.15. I have an IBM EtherJet PCI card, it is detected by the fxp(4) driver correctly, but the lights on the card don't come on and it doesn't connect to the network.

We don't understand why this happens. Neither do IBM (we asked them). The card is a standard Intel EtherExpress Pro/100 with an IBM label on it, and these cards normally work just fine. You may see these symptoms only in some IBM Netfinity servers. The only solution is to install a different Ethernet adapter.

4.2.17. When I install onto a drive managed by a Mylex PCI RAID controller, the system fails to boot (eg. with a read error message).

There is a bug in the Mylex driver which results in it ignoring the “8GB” geometry mode setting in the BIOS. Use the 2GB mode instead.

This file, and other release-related documents, can be downloaded from http://www.FreeBSD.org/snapshots/.

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.

All users of FreeBSD 6-STABLE should subscribe to the <stable@FreeBSD.org> mailing list.

For questions about this documentation, e-mail <doc@FreeBSD.org>.