Troubleshooting Installation Issues¶

The vast majority of the time, installations of pfSense® software finish with no problems. The following sections describe the most common problems and the steps to resolve them.

Installer Network Connectivity Problems¶

As the installer requires network connectivity getting the WAN settings correct is critical to its success.

If the installer is unable to contact Netgate servers it will display an error saying “Cannot verify the eligibility of this system, please try again.” This could be due to a network configuration or connectivity issue, for example. Double check the WAN settings before attempting the installation again.

If the installer is still unable to achieve outbound connectivity, it may need to be relocated behind a different connection or on a different network through which it can directly reach the Internet.

Errors During Installation¶

Errors may occur during the installation, for example if the network connection is interrupted or if the installer encounters a problem with the hardware.

The installer saves a log containing all of the installation output to a file named /tmp/install-log.txt.

After the installer encounters an error, it displays a notice stating the installation failed and then exits to a shell prompt.

From that shell prompt, it’s possible to copy that log file off either over the network with scp or by copying it to a USB drive, for example.

Boot from Install Media Fails¶

Due to the wide array of hardware combinations in use, it is not uncommon for a memstick or CD to boot incorrectly (or not at all). Given the unpredictable nature of commodity hardware support, using hardware from the Netgate Store is the only guaranteed path to success.

That said, the most common problems and solutions are:

USB Memstick Support:: Some BIOS implementations can be picky about USB memstick support. If booting from one stick fails, try a different one.
USB 3 Ports:: Certain combinations of USB sticks and ports, especially USB 3.0 ports, may not work correctly. Try a USB 2.0 memstick and/or a USB 2.0 port.
BIOS Issues:: Update to the most recent BIOS, and disable any unneeded peripherals such as Firewire, Floppy Drives, and Audio.
Dirty Optical Drive:: Clean the drive with a cleaning disc or a can of compressed air, try another drive, or use USB media instead.
Bad Optical Media:: Burn another disc and/or burn the disc at a lower speed. Perhaps try another brand of optical media or use USB media instead.
SATA/IDE Cable Issues:: Try a different cable between the DVD drive and the controller or motherboard or use USB media instead.

Boot from hard drive after installation fails¶

After the installation completes and the firewall restarts, there are conditions which may prevent the operating system from fully booting. The most common reasons are typically BIOS-related. For example, a BIOS implementation may not boot from a disk using GPT or ZFS, or may require UEFI.

Some of these may be worked around by choosing different options for the partition layout during the installation process. Upgrading the BIOS to the latest version available may also help.

Altering the SATA options in the BIOS has improved booting in some situations as well. If a SATA hard drive is being used, experiment with changing the SATA options in the BIOS for settings such as AHCI, Legacy, or IDE. AHCI is the best mode to use with current versions of pfSense software.

Interface link up not detected¶

If the firewall complains that it did not detect an interface link up event during automatic assignment, first make sure that the cable is unplugged and that the interface does not have a link light prior to choosing the link detection option. After selecting the option, plug the cable back into the interface and ensure it has a link light prior to pressing Enter. Test or replace the cable in question if it does not show a link light on the switch and/or NIC port once it is connected.

If a network cable is connected directly between two computers and not to a switch, and one of those pieces of hardware is older (e.g. 10/100 NIC) ensure that a crossover cable is being used. Gigabit adapters all support Auto-MDIX and will handle this internally, but many older 10/100 adapters do not. Similarly, if connecting a firewall running pfSense software to a switch that does not support Auto-MDIX, use a straight-through patch cable.

If the interface is properly connected but the firewall still does not detect the link event, the network interface may not properly detect or report link status to the operating system or driver. In this case, manually assigning the interfaces is necessary.

Hardware Troubleshooting¶

the following suggestions will help resolve general hardware issues.

Booting from USB¶

If the boot stops with a mountroot> prompt while booting off the installer image, usually with USB CD/DVD drives, escape to the loader prompt from the boot menu and run the following:

set kern.cam.boot_delay=10000
boot

At which point the boot will continue normally.

If the firewall is running permanently from a medium that requires this delay, add the following line as a Loader Tunable:

kern.cam.boot_delay=10000

Remove unnecessary hardware¶

If the firewall contains hardware that will not be used, remove or disable it. This normally isn’t an issue, but can cause problems and has the potential to reduce performance. If an unused piece of hardware is removable, take it out of the firewall or disable it in the BIOS.

Upgrade the BIOS¶

The second most common fix for hardware problems is upgrading the BIOS to the latest revision. People seem to have a hard time believing this one, but trust us, do it. BIOS updates commonly fix bugs in hardware. It isn’t uncommon to hit problems induced by hardware bugs on systems that have been stable running Windows for long periods of time. Either Windows doesn’t trigger the bug, or has a work around, as Netgate TAC has encountered this on multiple occasions. Things that BIOS updates can fix include: Failing to boot, time keeping problems, general instability, and other issues like hardware compatibility.

Reset BIOS settings to factory defaults¶

Recycled systems may have an atypical BIOS configuration. Most contain an option allowing factory default options to be loaded. Use this option to get a fresh start on the BIOS settings.

Other BIOS settings¶

If the BIOS allows power management configuration, try toggling that option. Look for anything else that seems relevant to whichever aspect of the installation is failing. If it gets to this point, the target hardware is probably a lost cause and alternate hardware may be necessary. Also check to see if the BIOS has an event log that may list hardware errors such as memory test failures.

If the hardware uses a new or recent chipset, a development version of pfSense software may work. Depending on the development cycle of pfSense software, snapshots may be available via upgrade or potentially for installation from within the installer.

Other Hardware Issues¶

The target hardware may be faulty, which testing with diagnostic software may reveal. Test the hard drive with diagnostic software from the OEM, and test the memory with a program such as memtest86+. These and more tools are available on the “Ultimate Boot CD”, which is preloaded with many free hardware diagnostic tools.

Also ensure that all of the fans are spinning at speed, and that no components are overheating. If this is older reused hardware, compressed/canned air cleaning of the fans and heat sinks can work wonders.