Synopsis #
An administrator with authorized console access can reset the root password from single-user mode. The procedure boots a minimal root shell, checks and mounts the installed filesystems read-write, runs passwd(1) , and resumes multiuser operation.
This is a recovery procedure for systems under the administrator’s control. Console access is a privileged security boundary. Encrypted root storage still requires its passphrase or keydisk before single-user mode can reach the installed system.
Prepare the Console #
Use a local keyboard and display, a serial console, a hypervisor console, or an authenticated provider console. Record any current error before restarting.
If the system still has a working administrative session, correct the account or SSH configuration from that session instead of rebooting.
Boot Single-User Mode #
On amd64 and i386, interrupt the normal boot countdown at the boot(8)
prompt and start the kernel with -s:
boot> boot -s
The console sequence differs on other architectures. Use the relevant boot_<arch>(8) manual page and INSTALL.<arch> document.
When the kernel asks for a shell, accept the default. The root filesystem is initially mounted read-only.
Check and Mount Filesystems #
Run fsck(8) in preen mode, then remount the root filesystem read-write with mount(8) :
# fsck -p /
# Check the root filesystem conservatively
# mount -uw /
# Remount root read-write
The passwd program and its libraries are normally under /usr, so /usr must also be available. If /usr is a separate filesystem:
# fsck -p /usr
# Check the separate /usr filesystem
# mount /usr
# Mount it according to /etc/fstab
Do not assume a fixed partition name. fstab(5) defines the installed layout.
If fsck -p reports an error that requires manual repair, stop and investigate the filesystem and disk condition. Do not substitute fsck -y without understanding the reported damage.
Reset and Verify the Password #
Change the root password:
# passwd root
Inspect the account record with getent(1) :
# getent passwd root
The account should have user ID 0, its expected home directory, and an appropriate login shell. Do not edit /etc/master.passwd directly. Use vipw(8)
if an account-record repair is also required.
Resume Normal Operation #
Enter exit or press Control-D to continue into multiuser mode. A full reboot is also acceptable:
# reboot
After login, verify the root password from the console and test the normal administrator account with doas. If remote access failed, validate the SSH configuration before reloading it:
# sshd -t
# Check server configuration syntax
# rcctl check sshd
# Confirm the daemon is running
After Recovery #
Determine why access was lost. Common causes include an expired or removed key, incorrect home-directory permissions, an invalid doas.conf, an SSH policy change, or a password-management error.
Preserve a tested non-root administrator account and an independent console path. For encrypted systems, store the disk-unlock recovery material separately from the machine. See Create an Administrator Account with doas and SSH Keys and Configure Secure Remote Access with OpenSSH .