Online Network Installer¶
The Online Network Installer is a new method of installing pfSense® software on Netgate hardware and other eligible AMD64-based systems.
The online network installer image does not contain installation packages for pfSense software, it fetches them over the Internet. This allows a single installer to offer choices between multiple versions of pfSense software without needing to package them all into a gigantic single disk image. This also means that when installing, the target device always receives the most up-to-date versions of available components.
Warning
This installer checks that a system is eligible to access pfSense Plus software before proceeding. If a system is ineligible, the user can either follow the directions to become eligible or install pfSense CE Software instead.
Prerequisites¶
Download Installer Image¶
There are three installation images to support different types of hardware:
AMD64 Memstick (Serial and VGA) for installing via USB media
AMD64 ISO image for installing via IPMI or optical drive
AARCH64 Memstick for installing on 64-bit ARM devices from Netgate, such as the Netgate 1100 and Netgate 2100.
These installation images can be downloaded from the Netgate Store at https://shop.netgate.com/products/netgate-installer using a Netgate Store Account.
See also
Limitations¶
The Online Network Installer has the following known limitations at this time:
No support for PPP-based WANs such as PPPoE, L2TP, PPTP, or PPP (e.g. 4G Cellular)
No support for 32-bit ARM devices such as the Netgate 3100
Prepare to Install¶
Writing the disk image and preparing to run the installer works similar to past methods. For example, the best practice for writing images to USB drives is to use Etcher.
See also
Connect to a Network¶
This installer is an online installer and requires Internet connectivity to download installation data from Netgate servers. Currently the installer supports DHCP and static IP address configurations. Connect the WAN port of the device into a live network connection supporting one of those connectivity types.
Boot the Installer¶
Certain systems may need to be nudged to boot from the installer image in different ways. Typically this involves hitting a hotkey during boot to bring up a boot menu, going into the BIOS to pick a boot device, or invoking a special command from a BIOS prompt.
Consult the Netgate Product Manuals for information on booting install media on various Netgate hardware. For third party hardware, check with the OEM.
Installation Walkthrough¶
Serial Console Terminal Type¶
For devices with a serial console, the installer first asks what kind of terminal type it should use.
- ansi
Generic terminal with color coding
- vt100
Generic terminal without color, most basic/compatible option, select if no others work
- xterm
X terminal window. For modern terminal clients such as GNU screen, PuTTY, SecureCRT, Tabby, and other similar clients the
xterm
choice is most likely to produce the best looking output.- cons25w
FreeBSD console style terminal
The installer assumes cons25w
for VGA consoles.
License Screen¶
When the installer starts the first screen it presents offers license terms for pfSense® software which the user must accept before installation.
Read the terms carefully. Use the Page Down and Page Up keys to display
additional license text. Press Enter
to Accept the terms and proceed.
Advanced Options¶
The options on the Advanced Options menu fine-tune the target installation.
Use the arrow keys to select an option, then press Enter
to set or toggle
the value. The options on this screen are:
- Swap Size
Sets the size of the swap partition the installer will create on the target disk. Swap space is used for holding crash dump data as well as for virtual memory to supplement available RAM.
Enter a value with a size suffix, such as
1G
for 1 GiB of swap space. Use a value of0
to disable swap.Note
Swap usage can cause a higher volume of disk writes, but the best practice is to at least keep a small swap partition for crash dump data.
- Console Serial
Controls whether or not the serial console should be enabled on the target installation. Toggles between
enabled
anddisabled
.- Console Type
Sets a specific type of console for the target installation.
- EFI
EFI console, best suited for systems booting EFI with video and/or serial.
- Video
Traditional VGA style console.
- None
Do not set a specific console type.
After setting options on this menu, choose Continue and OK and the installer will return to the Welcome Menu.
Configuration Recovery¶
At this point the installer searches for available configurations to recover and use for the target installation. This can be an existing prior installation of pfSense software or a configuration file on a USB drive. The installer lists every configuration file it can locate and offers the user a choice of which to use, or to proceed without recovering a configuration.
To recover a configuration and copy it to the target installation, use the arrow
keys to select it from the list and press the Enter
key.
If the installer could not locate any existing configuration files, it skips this step automatically.
Network Setup¶
As this is an online installer it requires network connectivity to download installation packages from Netgate servers. To configure the network, the installer has to know which port is WAN and which is LAN, and configuration details for those networks.
Note
Models of Netgate hardware known to the installer will automatically have their WAN and LAN assigned to their default ports, skipping this manual assignment process and going right to Confirm Network Configuration.
Select WAN Interface¶
The first interface to assign is the WAN interface. This is the interface connected to the upstream network (e.g. Internet, modem, CPE, etc.). The installer presents a list of all detected interfaces and their MAC addresses, along with their current link state.
Use the up/down arrow keys to select the WAN interface and press Enter
to
continue.
Note
When re-visiting this assignment screen later, for example to change the interface assignment or configuration, the list also includes the current assignment (e.g. WAN or LAN) at the end of each row.
Configure WAN Interface¶
The next step is to configure the WAN interface. The installer supports either DHCP or static IP address configuration for interfaces. Additionally, interfaces may be VLAN tagged if necessary.
To change the type of interface configuration, select Interface Mode and
press the Enter
key. To configure a VLAN tag, select VLAN Settings and
press the Enter
key.
These options are explained in further detail in the following sections.
DHCP WAN¶
When the WAN interface is set to DHCP (Client) there are no additional options to configure, the behavior is automatic.
Static IP Address WAN¶
Changing the Interface Mode to STATIC presents several additional fields to configure WAN connectivity.
The available settings are:
- IP Address
The IPv4 address and CIDR mask to use for external connectivity.
- Default Gateway
The IPv4 address of the default gateway through which the installer can reach the Internet.
- DNS Server
The IPv4 address of a DNS server, usually at the ISP or a public DNS server such as Google, CloudFlare, etc.
The figure above depicts a fully configured static IP address WAN.
VLAN Configuration¶
Each interface can be optionally configured to use a VLAN tag when communicating with the rest of the network connected to that interface.
To use a VLAN tag, first select VLAN Settings from the interface configuration screen to reach the VLAN settings screen.
The VLAN configuration screen controls how installer uses VLANs on an interface. The following options are available:
- Enable VLAN
Enables or disables VLAN support for the interface.
- VLAN Tag
Sets the VLAN tag for traffic on the interface.
- Priority Tag
Sets a VLAN priority value.
Select OK to return to the interface configuration.
Select LAN Interface¶
The next step is to select the LAN interface. This is used for connecting to the installer from a local network if needed. While not used in this particular walkthrough, future installer features will rely on having a working LAN configuration.
Note
When re-visiting this assignment screen later, for example to change the interface assignment or configuration, the list also includes the current assignment (e.g. WAN or LAN) at the end of each row.
Configure LAN Interface¶
The options to configure the LAN are similar to a WAN but not identical.
The following options are available when configuring the LAN interface:
- Interface Mode
Select between DHCP Client and Static IP Address configuration types.
- VLAN Settings
Enter VLAN Configuration mode for this interface.
- IP Address
Configure a static IP address and CIDR mask for the LAN. Default is
192.168.1.1/24
.- DHCPD Enabled
Toggles DHCP server behavior off/on (default: on)
Note
This option, along with the range start/end, are only available when LAN is set to a static IP address configuration.
- DHCPD Range Start
Sets the starting address of the LAN DHCP range. Default is
192.168.1.100
.- DHCPD Range End
Sets the ending address of the LAN DHCP range. Default is
192.168.1.150
.
Confirm Network Configuration¶
This screen lists the current interface assignments, either after manual assignment or from being assigned automatically for known models of Netgate hardware.
If the default settings are OK, then choose to Continue from here by
selecting it with the left/right arrows and pressing the Enter
key.
The default settings are a DHCP client WAN, static IP Address LAN on
192.168.1.1/24
with DHCP server enabled on LAN from 192.168.1.100
to
192.168.1.150
.
To change the interface assignments or configuration, select the interface with
the up and down arrows and then use the left/right arrows to highlight
Assign Interface then press the Enter
key. Refer to the previous
sections for information on how to assign and configure each interface.
At this point the installer should have Internet connectivity.
Ineligible Device Prompt¶
The installer gathers information about the device and communicates with Netgate servers to determine if the device is eligible to run pfSense Plus software. If the device is eligible, it moves forward to the filesystem selection screen. If the device is not eligible, the installer displays a prompt informing the user of this fact.
Warning
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.” For suggestions on how to correct that, see Connectivity Problems.
If the device does not have an active subscription for pfSense Plus software, one can be purchased at this time by visiting https://www.netgate.com/purchase-plus and entering the Netgate Device ID (NDI), which is listed on this screen of the installer as well.
After subscribing, choose the Retry Validation option to allow the installer to check the subscription status again.
Alternately, users can choose the Install CE option to install pfSense CE Software, and that installation can upgrade to pfSense Plus software later after completing the subscription process.
Filesystem and Partition Settings¶
After verifying the subscription, the next step is to choose the filesystem and partition type.
The available options are:
- File System
The type of filesystem to use on the target disk.
- ZFS
A robust modern filesystem that supports many advanced features, such as boot environments, but it uses a lot more resources. Even so, this is the default and best practice choice for nearly all cases.
- UFS
An older filesystem that works well but can be fragile when it comes to sudden interruptions such as power loss. It uses less resources, but also doesn’t support any modern features such as boot environments.
- Partition Scheme
The partition scheme to use on the target disk.
- GPT
A modern partitioning method which is well supported on modern AMD64 systems but in rare cases it can have issues with older BIOS implementations. This is the default choice as there are very few systems which do not support GPT.
- MBR
A more basic partition scheme but one which is more widely compatible. This is also used on ARM-based systems.
ZFS¶
When installing to ZFS the installer prompt to choose the ZFS Configuration. ZFS supports multiple disks in various ways for redundancy and/or extra capacity. Though using multiple disks with ZFS is software RAID, it is quite reliable and better than using a single disk.
The available types are:
- stripe
A single disk, or multiple disks added together to make one larger disk (RAID 0).
Note
For devices with a single target disk, this is the correct choice.
- mirror
Two or more disks that all contain the same content for redundancy. Can keep operating even if one disk dies. (RAID 1)
- raid10
RAID 1+0, n x 2-way mirrors. A combination of stripes and mirrors, which gives redundancy and extra capacity. Can lose one disk from any pair at any time.
- raidzX
Single, Double, or Triple redundant RAID. Uses 1, 2, or 3 parity disks with a pool to give extra capacity and redundancy, so either one, two, or three disks can fail before a pool is compromised. Though similar to RAID 5 and 6, the RAIDZ design has significant differences.
Select a type and press Enter
Next, the installer prompts for which disks it will include in the selected ZFS Configuration.
Use the up
and down
arrow keys to highlight a disk and Space
to
select disks. For mirrors or RAID types, select enough disks to fulfill the
requirements for the chosen type.
Warning
Select a disk even if there is only one in the list!
Note
If installer cannot find any drives, or if it shows incorrect drives, it is possible that the desired drive is attached to an unsupported controller or a controller set for an unsupported mode in the BIOS. See Troubleshooting Installation Issues for help.
UFS¶
When installing to UFS, the installer will prompt to select the target disk
where the installer will write out the pfSense® software, e.g. ada0
. The
installer will show all supported drives.
Note
Unlike ZFS, UFS only supports a single disk, though some setups such as those using a RAID controller may still use multiple disks, so long as they present a single virtual volume the installer can utilize.
Note
If installer cannot find any drives, or if it shows incorrect drives, it is possible that the desired drive is attached to an unsupported controller or a controller set for an unsupported mode in the BIOS. See Troubleshooting Installation Issues for help.
Final Confirmation¶
After selecting the target disk the installer prompts for confirmation one final time before it makes destructive changes to the disk.
Danger
Choosing to continue from this point will destroy anything left on the target disk!
Version Selection¶
At this point the installer presents a list of pfSense software that this device is eligible to run. This list will typically include the current version of pfSense software and one prior release. Depending on the current status of an upcoming release cycle, the installer may also offer development snapshots.
Select the version to install from the list with the up/down arrow keys, select
OK with the left/right arrow keys, then press Enter
Tip
In most cases the correct selection will be the one labeled “Current Stable Version”.
Installation¶
After picking the version, the installer proceeds to download the installation data for that version and installs it on the target disk.
The installer displays the output from this process as it works. When finished, the installed presents an OK button which will continue to post-installation tasks.
Finish Up¶
At this point the installation is complete. The installer will prompt one final time to either reboot into the new installation or to start a shell prompt for any manual adjustments advanced users may wish to make.
Once the device has booted from its own internal disk the device is ready for use.
Congratulations, the installation is complete!
The next step is to connect to the GUI and configure the device as described in Configuration.
Troubleshooting¶
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.
See also
Alternate Remote Backup Techniques (for an example of using SCP)