Skip to main content

Remote Bootstrap (Troubleshooting)

This page covers common failures during ./infra.sh remote bootstrap (first-time server hardening).

Prerequisites​

Before running bootstrap, verify:

  1. You can SSH as root on port 22

    ssh root@<SERVER_HOST>

  2. Local tools are installed

    ansible --version
    ssh-keygen -h >/dev/null
    nc -h >/dev/null

  3. Secrets exist

    • .env.secrets contains REMOTE_ROOT_PASSWORD and REMOTE_EXTERNAL_ADMIN_PASSWORD.
    • Server is registered: 
      ./infra.sh server add <IP_OR_DOMAIN> --user root --port 22

Common Issues​

1) "REMOTE HOST IDENTIFICATION HAS CHANGED"​

When you rebuilt a VPS and reused the same IP/domain, your known_hosts entry is stale.

ssh-keygen -R <SERVER_HOST>

2) "Failed to connect via ssh" / UNREACHABLE​

Most frequent causes:

  • Wrong host/user/port in inventory

    ./infra.sh server list

  • Provider firewall blocks port 22

    nc -zv <SERVER_HOST> 22

  • Server is not ready yet Wait a few minutes after provisioning, then retry.

3) Bootstrap hangs on reboot / waiting for SSH​

Bootstrap typically changes SSH behavior (and may reboot). If it looks stuck:

  1. Try both SSH ports

    nc -zv <SERVER_HOST> 22
    nc -zv <SERVER_HOST> 36987

  2. If you have console access (VNC/serial), check SSH

    systemctl status ssh
    journalctl -u ssh -n 100 --no-pager

4) Cannot login as externaladmin after bootstrap​

Typical causes:

  • Wrong port (use 36987):

    ssh -p 36987 externaladmin@<SERVER_HOST>

  • Password mismatch: verify .env.secrets (REMOTE_EXTERNAL_ADMIN_PASSWORD).

  • Provider firewall blocks 36987 (open it on the provider side first).

5) Network stabilization issues (provider-specific)​

Some VPS images (e.g. Arsys) may require network stabilization. If bootstrap reports network validation failures:

  • Validate current network state:

    ip addr
    ip route
    ping -c 3 8.8.8.8

  • Check for conflicting tooling:

    ls -la /etc/netplan/ || true
    ls -la /etc/cloud/cloud.cfg.d/ || true

Manual Recovery (Last Resort)​

If you are locked out and only the provider console works:

  1. Restore SSH port 22

    sed -i 's/^#\\?Port .*/Port 22/' /etc/ssh/sshd_config
    systemctl restart ssh

  2. Ensure the user exists and can sudo (adjust to your policy)

    id externaladmin || useradd -m -s /bin/bash externaladmin
    usermod -aG sudo externaladmin

  3. Retry bootstrap after access is restored.