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.
Use this procedure only on systems under the administrator’s control. Protect console access: it can allow changes to the root account. 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.
If the console is marked secure in /etc/ttys, accept the default shell when prompted. Otherwise, single-user entry requires the root password; use verified recovery media and the boot recovery procedure
when that password is unavailable. 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) :
Run in the root shell:
fsck -p / && 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:
Run in the root shell:
fsck -p /usr && 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:
Run in the root shell:
passwd root
Inspect the account record with getent(1) :
Run in the root shell:
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 #
Reboot normally after the password change so the normal startup filesystem checks run. Exiting a single-user shell continues with rc fastboot, which skips those checks; use that path only after checking all required filesystems:
Run in the root shell:
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:
Run in the root shell:
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 .