How to Boot into Single-User Mode for Recovery on FreeBSD

When you encounter system issues with your FreeBSD installation that prevent normal operation, single-user mode provides a powerful recovery environment. This specialized boot mode grants you administrative access to your system with minimal services running, allowing you to perform maintenance and recovery tasks. This guide will walk you through the process of entering single-user mode, common recovery scenarios, and best practices for system restoration.

What is Single-User Mode?

Single-user mode is a special boot state in FreeBSD where:

• The system runs with minimal services
• Only the root filesystem is mounted (read-only initially)
• Network services are disabled
• Only the console is accessible (no remote access)
• You have root privileges by default
• Most daemons and background processes are not started

This stripped-down environment makes it ideal for system recovery, filesystem repairs, password resets, and other administrative tasks when normal operation is compromised.

When to Use Single-User Mode

Consider booting into single-user mode when:

• Your system won’t boot normally due to configuration errors
• You need to repair damaged filesystems
• You’ve forgotten the root password
• Critical system files or configurations need restoration
• You need to perform maintenance that requires exclusive access to filesystems
• Normal boot processes fail due to corrupted startup scripts
• You need to reinstall or rollback system packages when normal operation is impossible

Methods to Boot into Single-User Mode

FreeBSD offers multiple ways to enter single-user mode, depending on your system’s boot loader and configuration.

Method 1: Using the Boot Menu (Recommended)

1. Restart your FreeBSD system

2. At the boot loader menu, press any key to stop the automatic boot countdown

3. At the prompt, type:

   boot -s
   

4. Press Enter to continue the boot process in single-user mode

Method 2: Interrupting the Boot Process

If you’re using the standard FreeBSD boot loader:

1. Restart your FreeBSD system

2. When you see the boot countdown, press the Space bar to interrupt it

3. At the OK prompt, enter:

   set boot_single=YES
   boot
   

Method 3: From a Running System

If you can still access your system but need to restart in single-user mode:

# shutdown now

or

# shutdown -s now

The -s flag specifically requests single-user mode on reboot.

Setting Up the Environment in Single-User Mode

After booting into single-user mode, you’ll be presented with a series of prompts to configure your environment.

Shell Selection

The system will first ask you to specify a shell:

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

In most cases, pressing ENTER to select the default /bin/sh is recommended unless you have specific requirements.

Filesystem Mounting

By default, only the root filesystem is mounted, and it’s mounted read-only. To perform most recovery tasks, you’ll need write access and other filesystems mounted.

1. Check that your root filesystem is intact:

   # fsck -p
   

2. Remount the root filesystem with write permissions:

   # mount -u /
   

3. Mount all other filesystems (optional, but often necessary):

   # mount -a -t ufs
   

4. If you need ZFS filesystems:

   # zfs mount -a
   

5. If you need procfs:

   # mount -t procfs proc /proc
   

Common Recovery Scenarios

Scenario 1: Resetting a Forgotten Root Password

One of the most common reasons to boot into single-user mode is to reset a forgotten root password:

1. Boot into single-user mode using any method above

2. Remount the root filesystem with write permissions:

   # mount -u /
   

3. Use the passwd command to set a new root password:

   # passwd
   

4. Enter and confirm the new password

5. Reboot the system:

   # reboot
   

Scenario 2: Repairing Filesystem Issues

Filesystem corruption can prevent normal booting. To repair:

1. Boot into single-user mode

2. Run a filesystem check on your partitions:

   # fsck -y /dev/ada0p2   # Replace with your actual partition
   

   The -y flag automatically answers “yes” to all questions.

3. For more severe issues, you might need to specify the filesystem type:

   # fsck_ufs -y /dev/ada0p2
   

4. If using ZFS, run:

   # zpool import -f poolname
   # zpool scrub poolname
   

Scenario 3: Fixing Boot Configuration Issues

If your system won’t boot due to errors in configuration files:

1. Boot into single-user mode

2. Remount root with write permissions:

   # mount -u /
   

3. Edit the problematic configuration file:

   # ee /etc/rc.conf   # Use your preferred editor (ee, vi, etc.)
   

4. Fix any syntax errors or problematic settings

5. Save and exit the editor

6. Reboot the system:

   # reboot
   

Scenario 4: Recovering from Failed Updates or Installations

If a system update or package installation rendered your system unbootable:

1. Boot into single-user mode

2. Mount filesystems with write access:

   # mount -u /
   # mount -a -t ufs
   

3. Rollback package changes:

   # pkg rollback -r YYYY-MM-DD_HH:MM:SS   # Specify a known good date
   

4. Or fix individual packages:

   # pkg remove problematic_package
   # pkg install -f important_package
   

Advanced Recovery Techniques

Using Boot Environments (BEs)

If your FreeBSD system uses ZFS boot environments, you have additional recovery options:

1. Boot into single-user mode

2. List available boot environments:

   # bectl list
   

3. Activate a previous, working boot environment:

   # bectl activate previous_working_BE
   

4. Reboot:

   # reboot
   

Chrooting into Your System

For more complex repairs, you might need to use a FreeBSD installation medium and chroot into your existing system:

1. Boot from FreeBSD installation media

2. Choose the “Shell” option

3. Mount your existing system:

   # mount /dev/ada0p2 /mnt   # Replace with your root partition
   # mount /dev/ada0p1 /mnt/boot   # If you have a separate boot partition
   

4. Chroot into the mounted system:

   # chroot /mnt
   

5. Perform necessary repairs

6. Exit and reboot:

   # exit
   # reboot
   

Security Considerations

Single-user mode provides unrestricted access to your system, which presents some security concerns:

• Physical access to a FreeBSD machine generally means complete control

• Consider setting a boot loader password for sensitive systems

• Edit /boot/loader.conf and add:

  boot_askpassword="YES"
  

• For additional security, you can require the root password even in single-user mode by editing /etc/ttys and changing:

  console none                            unknown off secure
  

  to:

  console none                            unknown off insecure
  

Best Practices for Single-User Mode Recovery

1. Document your steps: Keep notes on what changes you make during recovery

2. Make backups: Before editing critical files, create backups:

   # cp /etc/rc.conf /etc/rc.conf.backup
   

3. Use read-only access first: Examine problems before making changes

4. Verify filesystems: Always run fsck before mounting filesystems writable

5. Keep recovery media available: Maintain up-to-date FreeBSD installation media

6. Know your hardware: Document disk layouts and partition information

7. Practice recovery: Test recovery procedures before real emergencies occur

Returning to Multi-User Mode

Once your recovery tasks are complete, you can return to normal operation:

# exit

Or, to explicitly reboot:

# reboot

Troubleshooting Single-User Mode Issues

Cannot Remount Root Filesystem

If you get errors when trying to remount the root filesystem:

1. Run a more aggressive filesystem check:

   # fsck -y /
   

2. If still unsuccessful, you might need to boot from external media

Boot Loader Not Appearing

If you can’t access the boot loader menu:

1. Try repeatedly pressing Space, Enter, or Escape during boot
2. If using a serial console, ensure your terminal program is configured correctly
3. Some hardware configurations may require specific timing for key presses

System Still Won’t Boot After Repairs

If your system still won’t boot normally after attempts at repair:

1. Consider booting from installation media
2. Use the “Shell” option to gain access to recovery tools
3. Mount your system’s disks and perform more extensive repairs
4. As a last resort, back up data and consider reinstalling FreeBSD

Conclusion

Single-user mode is an essential tool in the FreeBSD administrator’s toolkit. It provides a safe environment to perform critical system repairs when normal operation is impossible. By understanding how to properly enter single-user mode and navigate its environment, you can resolve many types of system failures and return your FreeBSD system to normal operation.

Remember that prevention is always better than recovery—maintain regular backups, document your system configuration, and test recovery procedures before real emergencies occur.