Create an Administrator Account with doas and SSH Keys

Synopsis #

Routine administration should use a regular account and doas(1) , not a persistent root login. This guide creates an administrator, installs an SSH public key, validates privilege escalation, and preserves a recovery path until the replacement access method has been tested.

Complete this procedure from the local console or a provider console. Keep the existing root session open throughout the final access tests.

Create the Account #

The installer can create a regular account and place it in the wheel group. If no suitable account exists, run adduser(8) as root:

Run in the root shell:

adduser

Select wheel when the prompts ask for additional groups. The account’s login group remains the primary group selected elsewhere in the dialog.

For an existing account, inspect its current primary and supplementary groups before using usermod(8) :

Run in the root shell:

id admin

The usermod -G option appends supplementary memberships. Use -S only when intentionally replacing the complete supplementary-group list. To add wheel while retaining existing memberships:

Run in the root shell:

usermod -G wheel admin

Replace admin with the actual account name, then verify the complete result with id(1) :

Run in the root shell:

id admin

Configure doas #

The doas.conf(5) file does not exist on every installation. A minimal policy for administrators in wheel is:

permit persist :wheel

Create or edit /etc/doas.conf without discarding any existing policy. Rules are evaluated in order, so review the complete file when adding the wheel rule. Keep the file owned by root and validate it:

Run in the root shell:

test -e /etc/doas.conf || install -o root -g wheel -m 600 /dev/null /etc/doas.conf
  # Create the file only when it does not already exist
vi /etc/doas.conf
  # Add the rule without discarding existing policy
chown root:wheel /etc/doas.conf
  # Preserve administrative ownership
chmod 600 /etc/doas.conf
  # Restrict the policy file
doas -C /etc/doas.conf
  # Check the policy syntax

The persist option caches successful authentication for a limited time. Remove it when every privileged command should require authentication. Avoid nopass for a general administrator rule.

Generate an SSH Key #

Generate the key on the client system from which administration will occur. ssh-keygen(1) creates an Ed25519 key by default, but specifying the type makes the intent explicit:

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519

Protect the private key with a passphrase. Transfer only the .pub file.

Install the Public Key #

While password authentication still works, append the public key through ssh(1) :

ssh admin@server.example.com 'umask 077; mkdir -p .ssh; cat >> .ssh/authorized_keys' < ~/.ssh/id_ed25519.pub

On the server, derive the configured home directory rather than assuming its path. Verify and, if necessary, repair ownership and modes:

Run in the root shell:

admin_home=$(getent passwd admin | cut -d: -f6)
  # Read the account's configured home directory
chown -R admin "$admin_home/.ssh"
  # Make the account own its SSH directory without assuming a group
chmod 700 "$admin_home/.ssh"
  # Prevent access by other users
chmod 600 "$admin_home/.ssh/authorized_keys"
  # Restrict the authorized-key file

The home directory must not be writable by unrelated users.

Test the Complete Administrative Path #

Open a new client session and require public-key authentication with the intended key:

ssh -o IdentitiesOnly=yes -o PreferredAuthentications=publickey \
    -o PasswordAuthentication=no -o KbdInteractiveAuthentication=no \
    -i ~/.ssh/id_ed25519 admin@server.example.com

From that new session, verify identity and privilege escalation:

id
  # Confirm the regular account and wheel membership
doas id
  # Confirm that doas reaches effective user ID 0

Do not close the console or original root session until both commands succeed.

Change SSH Authentication Policy #

Public-key access can now replace remote root and password login. Make those policy changes through sshd_config(5) , validate them with sshd(8) , and test another new session before ending the recovery session.

The complete lockout-safe procedure is in Configure Secure Remote Access with OpenSSH .

Recovery Record #

Record:

  • how to reach the physical, serial, hypervisor, or provider console;
  • the administrator account name;
  • the public-key fingerprint;
  • where a protected backup or replacement credential is held;
  • how to restore password authentication temporarily if all keys are lost.

An SSH key and a doas rule are access controls, not a substitute for recovery planning.

Report a bug