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:
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 ZFS Systems.
From the loader menu with the ASCII logo, choose the menu option to enter single user mode, typically option
Enter the loader directly, either by using option
3from the ASCII loader menu or by pressing space while the kernel loads.
OKprompt in the loader, enter
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
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.
To mount all UFS type filesystems in read-write mode, run the following command:
# /sbin/mount -a -t ufs
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 /
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.