Tip

This is the documentation for the 24.06 version. Looking for the documentation of the latest version? Have a look here.

Enabling the Serial Console¶

TNSR can utilize a serial console on hardware containing a serial port, either directly in hardware or virtualized though a feature such as IPMI for Serial Over LAN (SOL).

Note

The TNSR installer activates the first hardware serial console by default (ttyS0). Try to access the console before performing additional steps.

Netgate appliances equipped with IPMI ship with default BIOS settings enabled for SOL operation. This applies to the 1537, 1541 and future models containing IPMI devices.

Warning

Modifying the kernel command line incorrectly can result in a system that does not boot. Take a backup before making any boot configuration changes as there can be a risk of rendering the router unbootable.

Check Current Kernel Command Line¶

Before starting, check the current kernel command line using dmesg from a shell prompt:

$ sudo dmesg | grep Command
[    0.000000] Command line: BOOT_IMAGE=/vmlinuz-5.15.0-58-generic
root=/dev/mapper/ubuntu--vg-ubuntu--lv ro console=ttyS0,115200n8 console=tty0

Pay attention to any arguments after the ro in this example. Here the kernel command line is already enabling the first serial port and video consoles.

Reboot the system normally and the new settings will take effect.

Using the TNSR CLI¶

TNSR can manage kernel command line arguments using the CLI as described in Kernel Command Line Arguments. The CLI can manage changes to the console via Manual kernel arguments. TNSR will remove any existing matching parameters when a user adds their own, so be sure to replicate any existing parameters of the same type.

For example if the kernel command line only contained console=tty0, then to enable the first serial port, replicate that in the command to specify the kernel command line arguments:

tnsr# config
tnsr(config)# system kernel arguments manual console=ttyS0,115200n8 console=tty0
Changes to kernel command line arguments will take effect after system is rebooted.
tnsr(config)# configuration copy running startup
tnsr(config)# reboot now
Reboot initiated. Are you sure? [yes/no]
yes

Manually Editing the Kernel Boot Configuration¶

An alternate method for enabling the serial console is to manually edit the kernel boot configuration.

Warning

This method is more error-prone, so the best practice is to use the TNSR CLI to manage these parameters.

Backup the Kernel Boot Configuration¶

Enabling the serial console requires adding arguments to the kernel command line.

Backup the existing grub configuration file:

cp /boot/grub/grub.cfg ~/grub.cfg.bak

Edit the Kernel Boot Configuration¶

Edit /etc/default/grub with text editor (e.g. vi). The file should look like this:

GRUB_DEFAULT=0
GRUB_TIMEOUT_STYLE=hidden
GRUB_TIMEOUT=0
GRUB_DISTRIBUTOR=`lsb_release -i -s 2> /dev/null || echo Debian`
GRUB_CMDLINE_LINUX_DEFAULT="console=ttyS0,115200n8 console=tty0"
GRUB_CMDLINE_LINUX=""

Find the GRUB_CMDLINE_LINUX_DEFAULT line and edit or append the console settings. For IPMI SOL, the terminal device will be ttyS1. For a hardware serial console, it would be ttyS0. This example will change the serial console to ttyS1.

This example enables both SOL on ttyS1 and the VGA console on tty0. Edit the line so GRUB_CMDLINE_LINUX_DEFAULT contains console=ttyS1,115200n8 console=tty0 as shown:

GRUB_CMDLINE_LINUX_DEFAULT="console=ttyS1,115200n8 console=tty0"

Note

Adding entries for these two consoles results in boot messages being displayed on both SOL and iKVM/VGA output.

Rebuild the Kernel Boot Configuration¶

Build a new grub.cfg using the following command:

sudo grub-mkconfig -o /boot/grub/grub.cfg

Reboot the system normally and the new settings will take effect.

Accessing the Serial Console¶

IPMI Serial Over LAN¶

There are multiple methods which can connect to the serial console.

The simplest method is to use the ipmiconsole tool which is part of the freeipmi package.

ipmiconsole -h <IPMI address> -u <username> -P

To exit the IPMI console press the following keys in sequence: &, ..

Alternately, use ssh to connect to the IPMI controller then launch the serial console utility:

ssh <username>@<IPMI address>
cd system1
cd sol1
start

To exit the SOL console press the following keys in sequence: Esc, Enter, Shift+T.

Hardware Serial Console¶

To access the hardware serial console, a serial cable connection must be established between the client and the device. This varies widely by hardware and may be a USB port, DB9 port, RJ45 style port, and may also involve a null modem adapter. Check the hardware device manual for details.

On the client device, use standard serial client software such as screen, cu, PuTTY, minicom, or others to access the console. Consult the serial client software documentation for additional details.

For devices sold by Netgate, the hardware manual contains information about accessing the serial console which covers hardware and software. For an example, see the manual for the Netgate 5100.