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.
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 in 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, or try another drive.
- Bad Optical Media
Burn another disc and/or burn the disc at a lower speed. Perhaps try another brand of media.
- SATA/IDE Cable Issues
Try a different cable between the DVD drive and the controller or motherboard
- Boot Loader Issues
There have been cases where specific versions of the CD boot loader from FreeBSD did not work on certain hardware. In these cases, see Alternate Installation Techniques to perform the target drive installation on a separate PC and then move it to the target hardware.
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.
For additional troubleshooting techniques, see Troubleshooting Boot Issues.
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:
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.
Disable PNP OS in the BIOS¶
This is a common fix for older hardware. BIOS configuration screens may contain
a setting for PNP OS or Plug and Play OS, which should be set to
no . A few have a setting for OS, which should usually be set
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. Check the Snapshots page to see if there is a development (e.g. Beta or release candidate) build to try.
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.