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:

  • 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 ZFS Systems.

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

  • Enter the loader directly, either by using option 3 from the ASCII loader menu or by pressing space while the kernel loads.

    From the OK prompt in the loader, enter boot -s

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.

  • 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 /boot/loader.conf.local.

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

UFS Systems

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

# /sbin/mount -a -t ufs

ZFS Systems

On ZFS systems 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 /

Next, mount all ZFS filesystems, datasets, etc:

# /sbin/zfs mount -a

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.