Troubleshooting in Single User Mode¶
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.
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
5Reboot System and then enter
s) to reboot and automatically enter single user mode.
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
- Use the Loader Prompt
Enter the loader directly, either by using option
3from the ASCII loader menu or if the boot menu is unavailable, press the
Spacebar while the kernel is loading at boot time, which will start the boot loader with an
The correct moment to hit
Spacevaries 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
Spacewhen “Loading kernel…” and/or the kernel loading spinner are visible.
Do not press a key at the
Hit any key to stop autobootprompt 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:
Check the prompt again before typing this command. It must say either
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.
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.
/sbin/rebootor 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
- Continue Boot
Exiting the single user mode shell via
^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.xmlalterations, but will not activate changes which must be present before the kernel loads.
Working in Single User Mode¶
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
nextboot configuration must be cleared manually:
# /sbin/nextboot -D
Failing to clear the
nextboot configuration will result in the system
booting back into single user mode on every boot.
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.
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.