Bootstrap

Bootstrap

Bootstrap is a one-time transition from the initial server identity to the managed login user.

Preconditions

• The host is in the bootstrap inventory group.
• The current inventory user can become root with sudo.
• The vault defines a nonempty password, salt, and at least one SSH public key.
• You have console access or an out-of-band recovery path in case SSH is misconfigured.

What bootstrap does

The first play creates bootstrap_login_user_name, which defaults to bootstraper. The users role:

• installs sudo;
• creates the user, home directory, and .ssh directory;
• writes authorized_keys with mode 0600;
• creates passwordless sudo configuration when requested;
• sets the initial password once;
• writes a marker under /var/lib/ansible/bootstrap-users to avoid resetting a user-changed password on future runs.

The second play reconnects as the managed user. When bootstrap_manage_updates: true, it updates APT, runs a dist upgrade with service starts blocked during package installation, then reboots.

Run it

uv run ansible-playbook \
  -i inventories/production/hosts.yaml \
  --ask-vault-pass \
  playbooks/bootstrap.yaml

Add -K if the initial inventory user needs a sudo password. Do not add it for root or a passwordless sudo user.

Run one host only:

uv run ansible-playbook \
  -i inventories/production/hosts.yaml \
  --ask-vault-pass \
  playbooks/bootstrap.yaml \
  --limit server-01

Verify before setup

ssh -i ~/.ssh/id_ed25519 bootstraper@203.0.113.10 id
ssh -i ~/.ssh/id_ed25519 bootstraper@203.0.113.10 'sudo -n true'

Both commands must succeed. If sudo -n true fails, fix the user or sudoers configuration before you run setup.

Password behavior

The role intentionally does not overwrite the bootstrap password after the first successful initialization. To initialize it again for a specific user:

sudo rm /var/lib/ansible/bootstrap-users/<user>

Run bootstrap again afterward. This changes the account password, so do it only when you understand the impact.

If bootstrap_login_user_force_password_change: true, the user password is expired after initialization. Key-only SSH cannot normally change an expired password. Use console access or temporarily relax the SSH policy when needed.