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

• Download Installation Media

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

• Prepare Installation Media

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.

Installer License

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.

Welcome Menu

Next, the installer prompts to launch rescue options or start the Install process.

Welcome Menu

Use the arrow keys to select an option, then press Enter. The options on this screen are:

Install

Continue installing pfSense software

Rescue Shell

Starts a basic shell prompt where advanced users can perform tasks to prepare the hardware in ways not fully supported by the installer, or to perform diagnostic tests or repairs on the firewall.

Choose Advanced Options from the bottom row of the menu to display additional options (Advanced Options).

Advanced Options

The options on the Advanced Options menu fine-tune the target installation.

Advanced Options

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 of 0 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 and disabled.

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.

Configuration Recovery

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.

Network Setup Prompt

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.

Select WAN Interface

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.

WAN Interface Configuration

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.

Static IP Address

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.

Static IP Address (Configured)

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.

VLAN Configuration

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.

Select LAN Interface

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.

LAN Interface Configuration

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.

Confirm Network Configuration

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.

Prompt displayed on systems not yet eligible to run pfSense Plus software

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.

Filesystem and Partition Options

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

ZFS Configuration Type

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!

ZFS Disk Selection

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.

UFS Disk Selection

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!

Final Confirmation before Installing

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

Select Software Version to Install

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.

Output After Installation Completes

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.

Reboot Prompt

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

• Copy Files to a USB Drive

• Alternate Remote Backup Techniques (for an example of using SCP)