Troubleshooting in Single User Mode

Warning

This option must only be used under the guidance of a support representative or a FreeBSD user with advanced knowledge.

Single user mode is a special boot mode in which only the operating system kernel is loaded and a bare minimum of functions are available. For example, networking is not configured, the GUI is not available, and no system services are started. The root filesystem defaults to read-only and other filesystems are not mounted. In single user mode, commands must be entered into a shell prompt on the primary system console.

Warning

This action requires access to the primary system console, which depending on hardware and configuration may be a video console or serial console. Ensure console access is available and working before attempting to enter single user mode.

Entering Single User Mode

There are multiple ways to enter single user mode:

Next Boot Configuration

From the console or SSH menu, choose option 5 Reboot System and then enter S (capital s) to reboot and automatically enter single user mode.

Warning

ZFS systems will not automatically clear this configuration when exiting single user mode. See Re-mount ZFS Volumes as Read/Write.

Choose Single User Mode on Boot Menu

From the loader menu with the ASCII logo, choose the menu option to enter single user mode, typically option 2

Use the Loader Prompt

Enter the loader directly, either by using option 3 from the ASCII loader menu or if the boot menu is unavailable, press the Space bar while the kernel is loading at boot time, which will start the boot loader with an OK or loader> prompt.

Note

The correct moment to hit Space varies by hardware.

The OS may display prompt such as “Hit [Enter] to boot immediately, or any other key for command prompt.” at the proper moment to press Space. If that message is not present, press Space when “Loading kernel…” and/or the kernel loading spinner are visible.

Do not press a key at the Hit any key to stop autoboot prompt as that is too early. That prompt is for U-Boot or similar and is before the OS boot process starts.

Enter the following command at the loader prompt:

boot -s

Warning

Check the prompt again before typing this command. It must say either loader> or OK. If the prompt shows a different string such as Marvel>> that is not the correct prompt for this action. Reboot and try again.

After invoking one of those options, the kenel will load and then immediately after, the operating system will prompt for a shell:

Enter full pathname of the shell or RETURN for /bin/sh:

At that point, press Enter and the resulting shell prompt is now running in single user mode.

Tip

Redminder: At this point, all filesystems are still read-only.

Exiting Single User Mode

There are two ways to exit single user mode, and the method to use depends on the changes made.

Reboot

Run /sbin/reboot or an equivalent command to force an operating system reboot. This is the safest choice as it will ensure the system is fully reinitialized. This method is required when making boot-time changes such as those in Managing Loader Tunables.

Continue Boot

Exiting the single user mode shell via exit, logout, or ^D (Ctrl-D) will terminate the single user mode shell and then continue to boot the system into its regular multi-user mode. This may be OK for simple changes such as config.xml alterations, but will not activate changes which must be present before the kernel loads.

Working in Single User Mode

Mounting Filesystems

In single user mode the root filesystem defaults to read-only and other filesystems are not mounted.

Re-mount UFS Volumes as Read/Write

To mount all UFS type filesystems in read-write mode, run the following command:

# /sbin/mount -a -t ufs

Re-mount ZFS Volumes as Read/Write

For ZFS the procedure to mount the all filesystems as read-write in single user mode requires several commands.

First, remount the root slice as read-write:

# /sbin/mount -u /

If that produces an error, try:

# /sbin/zfs set readonly=off pfSense/ROOT/default

Next, mount all ZFS filesystems, datasets, etc:

# /sbin/zfs mount -a

On newer versions, such as pfSense® plus software installations with ZFS boot environment support, this may not mount all of the ZFS datasets as a few are marked not to mount automatically. In this case, mount them manually:

# /sbin/zfs mount pfSense/ROOT/default/cf
# /sbin/zfs mount pfSense/ROOT/default/var_db_pkg

Finally, if the system was put into single user mode using the reboot menu S option, the nextboot configuration must be cleared manually:

# /sbin/nextboot -D

Warning

Failing to clear the nextboot configuration will result in the system booting back into single user mode on every boot.

Tip

It is safe to run this command even if the system was not booted in that way, so always run this command on ZFS systems before exiting single user mode.

Running Commands

Be aware that when running commands single user mode, their behavior may be unexpected as the system does not have a full traditional terminal setup, and some default shell environment variables and console/terminal settings are not available. For example, using vi, the arrow keys on the keyboard may not work or the dimensions of the terminal may be incorrect.

Some commands may be run without typing the full pathname to the binary, but it is safest to use the full path where possible.