Connect to the Console

A connection to the console on the target hardware is a requirement to run the installer.

Connecting to a VGA Console

For hardware with a VGA console, this is as simple as connecting a monitor and keyboard.

Connecting to a Serial Console

For hardware with a serial console, the process is more involved and requires a client PC with an appropriate port and terminal software. Follow the instructions below to connect using a serial console.

The instructions in this section cover general serial console topics. Some devices, such as firewalls from the Netgate Store, require slightly different methods to connect to the serial console. For devices from the Netgate Store, visit the Netgate Documentation for model-specific serial console instructions.

Serial Console Requirements

Connecting to a serial console on most firewalls requires the correct hardware on every part of the link, including:

  • The client PC must have a physical serial port or a USB-to-Serial adapter

  • The firewall must have a physical serial port

  • A null modem serial cable and/or adapter, or a device-specific serial cable

  • A terminal program on the client, such as PuTTY

  • The correct serial settings for the client software

For most of the firewalls purchased from the Netgate Store, the only hardware requirement is a USB A to Mini-B cable. See Netgate Documentation for specifics.

In addition to the proper hardware connection, a serial console client program must also be available on the client PC, and the serial speed and other settings must be available.

Locating a Serial Port (Server/Firewall)

First, ensure the firewall hardware has a serial port. To use the serial console, the hardware must have a physical serial port at COM1. Embedded units typically have a DB9 (9-pin) serial port, but some have an RJ45 style console connector with an adapter cable that ends with a DB9 connector.

Connect a Serial Cable

First, a null modem serial cable must be connected between the firewall and a client PC. Depending on the serial port and cable being used, a serial cable gender changer may also be necessary to match the available ports.

If a real null modem serial cable is unavailable, a null modem adapter can be used to convert a standard serial cable into a null modem cable.

If the client PC does not have a physical serial port, use a USB-to-Serial adapter.

Locate the Client Serial Port

On the client PC, the serial port device name must be determined so that the client software can be used on the correct port.

Windows

On Windows clients, a physical serial port is typically COM1. With a USB-to-Serial adapter, it may be COM3. Open Device Manager in Windows and expand Ports (COM & LPT) to find the port assignment.

macOS

On macOS, the name can be tricky for a user to determine since it can vary based several factors. On recent versions of macOS, the devices are likely to be named /dev/cu.usbserial-<id> where the <id> is an identifier for the USB serial adapter, such as a serial number.

When in doubt, run ls -l /dev/cu.* from a Terminal prompt to see a list of available USB serial devices and locate the appropriate one for the hardware. If there are multiple devices, the correct device is likely the one with the most recent timestamp or highest ID.

Linux

The device associated with a USB-to-Serial adapter is likely to show up as /dev/ttyUSB0. Look for messages about the device attaching in the system log files or by running dmesg.

Note

If the device does not appear in /dev/, check to see if the device requires additional drivers.

FreeBSD

The device associated with a USB-to-Serial adapter is likely to show up as /dev/cuaU0. Look for messages about the device attaching in the system log files or by running dmesg.

Determine Serial Console Settings

The settings for the serial port, including the speed, must be known before a client can successfully connect to a serial console.

Whichever serial client is used, ensure that it is set for the proper Speed (115200), Data Bits (8), Parity (No), and Stop Bits (1). This is typically written as 115200/8/N/1.

Note

Some hardware defaults to a slower speed. This is relevant to the BIOS and initial output, not to pfSense® software which defaults to 115200.

Many serial clients default to 9600/8/N/1, so adjusting these settings is required to connect. Use 115200/8/N/1 with pfSense software regardless of the setting of the hardware/BIOS.

For hardware using BIOS serial speeds other than 115200, change the baud rate to 115200 in the BIOS setup so the BIOS and pfSense software are both accessible with the same settings. Refer to the hardware manual for information on setting its baud rate.

115200 is the default speed pfSense software uses out of the box, but the serial speed used by pfSense software can be changed later. See Serial Console Speed.

Locate a Serial Client

A serial client program must be used on the client PC. The most popular client for Windows is PuTTY, which is free and works well. PuTTY is also available for Linux and can be installed on macOS using brew. On UNIX and UNIX-Like operating systems, the screen program is readily available or easily installed and it can also be used to connect to serial ports from a terminal program or system console.

Windows

PuTTY is the most popular free choice for serial communication on Windows. SecureCRT is another client that works well.

Warning

Do not use Hyperterminal. Even if it is already present on the client PC, it is unreliable and prone to formatting incorrectly and losing data.

macOS

On macOS clients, the GNU screen utility is the easiest and most common choice. ZTerm and cu (similar to FreeBSD) can be used as well.

Linux

On Linux clients, the GNU screen utility is the easiest and most common choice. Programs such as PuTTY, minicom, or dterm can be used as well.

FreeBSD

On FreeBSD clients, the GNU screen utility is the easiest and most common choice.

As an alternative, use the built-in program tip. Typing tip com1 (Or tip ucom1 if using a USB serial adapter) will connect to the first serial port. Disconnect by typing ~. at the start of a line.

Start a Serial Client

Now that all of the requirements have been met, it is time to run the serial client.

If the client software is not covered in this section, consult its documentation to determine how to make a serial connection.

PuTTY

  • Start PuTTY

  • Select Serial for the Connection Type

  • Enter the serial port device name for Serial Line, e.g. COM3 or /dev/ttyUSB0.

  • Enter the appropriate Speed, e.g. 115200

  • Click Open

MINICOM

$ minicom -D /dev/ttyUSB0 -R 115200

GNU screen

  • Open a terminal / command prompt

  • Invoke the screen command using the path to the serial port, for example:

    $ sudo screen /dev/ttyUSB0 115200

In some cases there may be a terminal encoding mismatch. If this happens, run screen in UTF-8 mode:

$ sudo screen -U /dev/cu.usbserial-1234 115200

The standard screen controls apply. Press Ctrl-A, \ to quit, or Ctrl-A, Ctrl-\ in some cases.

tip

The tip command on FreeBSD consults /etc/remotes and connects to serial ports based on the settings there. To setup a connection to a USB-to-serial adapter at 115200, add a line such as the following to /etc/remote:

ucom1fast:dv=/dev/cuaU0:br#115200:pa=none:

To access the port, invoke tip:

$ tip ucom1fast

To quit, press Enter, then type ~.. If connected through a terminal ssh client, ~~. may need to be used instead so that the ssh client itself doesn’t interpret the keys.