Configure OpenSSH Host-Based Authentication on Linux

Host-based SSH authentication lets a trusted client machine prove its identity with the host's private key, then log in when the server authorizes that client hostname and remote username pair. It is not the same as normal SSH public-key login, where each user keeps a personal key in ~/.ssh/.

This walkthrough uses a two-host RHEL 10 client and Ubuntu 26.04 server lab with SELinux left in enforcing mode on the client. You will enable ssh-keysign on the source host, trust the client Ed25519 host key on the target after verifying its fingerprint, and authorize hbalab through /etc/ssh/shosts.equiv.

What is SSH host-based authentication?

Host-based authentication answers a different question than user public-key authentication:

• What is trusted — the client host (machine identity), not a user's personal keypair
• Who maps to whom — for system-wide /etc/ssh/shosts.equiv, the remote username must match the local account you request on the ssh command line
• How the client proves the host — OpenSSH signs the attempt with /etc/ssh/ssh_host_* private keys through ssh-keysign (you do not run ssh-keysign yourself; the ssh command invokes it when host-based authentication needs a signature)
• How the server verifies the host — the signature must match a trusted client host public key in the administrator-controlled host-key store

This is also separate from server host-key verification during a normal SSH connection. Normal SSH first lets the client verify the server. Host-based authentication then lets the server verify the client machine before deciding whether the requested user may log in.

How host-based authentication works

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────────────────┐
│ ssh client      │ ──► │ ssh-keysign      │ ──► │ signs with client host      │
│ (user session)  │     │ reads /etc/ssh/  │     │ private key (root-only)     │
│                 │     │ ssh_host_*_key   │     │                             │
└─────────────────┘     └──────────────────┘     └─────────────────────────────┘
         │                                                    │
         │              hostbased userauth packet             │
         ▼                                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ sshd on server                                                              │
│  1) verify signature against /etc/ssh/ssh_known_hosts (client host key)     │
│     when IgnoreUserKnownHosts yes (recommended for central trust)           │
│  2) match client hostname + remote user in /etc/ssh/shosts.equiv            │
│  3) open session as the local user named on ssh user@server                  │
└─────────────────────────────────────────────────────────────────────────────┘

On RHEL 10, ssh-keysign ships in the openssh-keysign subpackage and is not installed with openssh-clients alone.

Host-based vs public-key vs SSH certificate authentication

Host-based authentication fits only when machine identity is meaningful and the trusted client fleet stays small. For day-to-day access, start with SSH key authentication. For many hosts and users, compare OpenSSH certificate authentication before enabling machine-wide trust.

Should you use host-based authentication?

Treat every trusted client host as a high-value asset. Compromise of that host can expose every account pairing listed in shosts.equiv, not just one user's key.

Lab environment

The captured logins use two separate VMs on 192.168.56.0/24. SELinux stays Enforcing on the RHEL client; do not disable it for this procedure.

Both hosts need matching forward and reverse names in /etc/hosts or DNS. Before you configure trust files, confirm reachability with the layered checks in test an SSH connection.

Example /etc/hosts on both client and server:

192.168.56.116  vm1.lab.example vm1
192.168.56.121  vm2.lab.example vm2

The test command run from the client:

ssh hbalab@vm2.lab.example

Prerequisites

Verify OpenSSH and ssh-keysign

On the client (RHEL 10), confirm packages and install the signing helper if needed:

rpm -q openssh-clients openssh-keysign

openssh-clients-9.9p1-27.el10_2.x86_64
openssh-keysign-9.9p1-27.el10_2.x86_64

If openssh-keysign is missing, install it with dnf:

sudo dnf install openssh-keysign

The helper must be setuid root:

ls -l /usr/libexec/openssh/ssh-keysign

-r-sr-xr-x. 1 root root 338112 Aug 21 05:30 /usr/libexec/openssh/ssh-keysign

On the server (Ubuntu), you only need openssh-server running. Host-based authentication does not require sshd on the client.

dpkg -l openssh-server | tail -1

ii  openssh-server 1:10.2p1-2ubuntu3.6 amd64        secure shell (SSH) server, for secure access from remote machines

Verify client host keys

Host-based authentication needs machine keys under /etc/ssh on the client:

sudo ls -l /etc/ssh/ssh_host_ed25519_key /etc/ssh/ssh_host_ed25519_key.pub

If keys are missing, generate them:

sudo ssh-keygen -A

Host private keys must stay mode 600 and owned by root.

Verify hostname resolution

On the server, forward and reverse lookups for the client address should return vm1.lab.example:

getent hosts vm1.lab.example

192.168.56.116  vm1.lab.example vm1

Reverse lookup on the server must agree:

getent hosts 192.168.56.116

192.168.56.116  vm1.lab.example vm1

If reverse lookup returns only the IP address, host-based authentication fails with userauth_hostbased mismatch until you fix naming (covered later).

Trust files at a glance

Configure the SSH client

Client changes live in /etc/ssh/ssh_config. They affect outbound ssh sessions only; you do not restart sshd on the client after editing this file.

Enable host-based authentication and ssh-keysign

Add these settings to the global /etc/ssh/ssh_config (or a snippet under /etc/ssh/ssh_config.d/ included from the global file):

Host *
    HostbasedAuthentication yes
    EnableSSHKeysign yes

EnableSSHKeysign is accepted only in the global client configuration, not in a per-user ~/.ssh/config file.

Verify effective client settings

ssh -G prints the configuration ssh will use for the server hostname:

ssh -G vm2.lab.example | grep -iE 'hostbasedauthentication|enablesshkeysign'

hostbasedauthentication yes
enablesshkeysign yes

Both values should be yes before you test from the client.

Configure the SSH server

All steps below run on vm2 (vm2.lab.example, the SSH server).

Enable host-based authentication

Create /etc/ssh/sshd_config.d/99-hostbased.conf (or edit sshd_config) with a centrally managed baseline:

HostbasedAuthentication yes
IgnoreUserKnownHosts yes
IgnoreRhosts yes

• IgnoreUserKnownHosts yes — client machine trust comes only from /etc/ssh/ssh_known_hosts, not from individual users' ~/.ssh/known_hosts
• IgnoreRhosts yes — ignore per-user ~/.rhosts and ~/.shosts; the system-wide /etc/ssh/shosts.equiv is still honored

That gives you two administrator-controlled questions on the server:

• /etc/ssh/ssh_known_hosts — which client machines do we trust?
• /etc/ssh/shosts.equiv — which host and user combinations may log in?

Confirm effective values:

sudo sshd -T | grep -iE 'hostbasedauthentication|ignoreuserknownhosts|ignorerhosts'

hostbasedauthentication yes
ignoreuserknownhosts yes
ignorerhosts yes

See OpenSSH authentication methods for how these directives interact with Match blocks.

Configure central host and user authorization

Create /etc/ssh/shosts.equiv on the server with one line per authorized client hostname and remote username:

vm1.lab.example hbalab

Set ownership and mode:

sudo chown root:root /etc/ssh/shosts.equiv
sudo chmod 644 /etc/ssh/shosts.equiv

Here both sides use the same username: hbalab on vm1 connects as hbalab on vm2. That is the simple system-wide shosts.equiv model used in this guide. Mapping one username to a different account requires per-user ~/.shosts, which we are deliberately not using here.

Trust the client host key

The server must trust the client machine's public host key. Copy it from the client over a trusted administrative path — do not copy the private /etc/ssh/ssh_host_ed25519_key.

On vm1 (the client), display the Ed25519 public host key:

sudo cat /etc/ssh/ssh_host_ed25519_key.pub

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEeTyvFvs5FNVgu2mNGqDZwoEhN08xwXTKCLaTgy1Xul

Verify its fingerprint before you install it on the server:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

256 SHA256:m0IbDhiWVYyfyiyaMJJjBMDlxsm5n5gRMU1SgW9gV4A no comment (ED25519)

On vm2 (the server), add one line to /etc/ssh/ssh_known_hosts with the client hostname and the public key from the step above:

vm1.lab.example ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEeTyvFvs5FNVgu2mNGqDZwoEhN08xwXTKCLaTgy1Xul

One compatible trusted client host key is sufficient. Add other key types only when compatibility requirements justify them.

If sshd is already running on the client, ssh-keyscan -t ed25519 vm1.lab.example can fetch the same public key — but that approach fails with Connection refused when the client has no SSH server listening, which is normal for a dedicated client host.

Validate and reload sshd

Run a syntax check before you reload:

sudo sshd -t

A silent exit means sshd accepts the configuration files. Reload the running daemon:

sudo systemctl reload ssh

Use the systemctl command restart only when reload is insufficient.

Test host-based authentication

From vm1, log in as hbalab and force host-based authentication so other methods do not mask failures. Use StrictHostKeyChecking=accept-new only in the lab so the client's first connection to the server's host key can proceed — that step is separate from host-based client trust on the server.

ssh -vv -o StrictHostKeyChecking=accept-new \
  -o PreferredAuthentications=hostbased \
  -o PubkeyAuthentication=no \
  -o PasswordAuthentication=no \
  hbalab@vm2.lab.example hostname -f

A successful trace shows host-based authentication offered, attempted, and accepted:

debug1: Next authentication method: hostbased
debug1: userauth_hostbased: trying hostkey ssh-ed25519 SHA256:m0IbDhiWVYyfyiyaMJJjBMDlxsm5n5gRMU1SgW9gV4A using sigalg ssh-ed25519
Authenticated to vm2.lab.example ([192.168.56.121]:22) using "hostbased".
debug1: Remote: Accepted for vm1.lab.example [192.168.56.116] by /etc/ssh/shosts.equiv.
vm2.lab.example

If you never see Next authentication method: hostbased, the problem is on the client (HostbasedAuthentication, EnableSSHKeysign, or missing openssh-keysign). If host-based is attempted but rejected, investigate the server (shosts.equiv, /etc/ssh/ssh_known_hosts, hostname/DNS). Remove the PreferredAuthentications and PubkeyAuthentication overrides after the test; they are diagnostic only.

Restrict host-based authentication to specific accounts

Host-based trust is not open to every account by default. The server still requires a shosts.equiv line, a matching local account, and HostbasedAuthentication yes for that account.

Limit which accounts accept host-based logins with a Match User block in sshd_config:

Match User hbalab
    HostbasedAuthentication yes
    PasswordAuthentication no

Match User backupsvc
    HostbasedAuthentication no
    PubkeyAuthentication yes

Only place valid directives inside Match. Evaluate the effective policy with:

host and addr describe the incoming client connection, not the SSH server. Simulate a login from vm1 with:

sudo sshd -T -C user=hbalab,host=vm1.lab.example,addr=192.168.56.116 | grep -iE 'hostbasedauthentication|passwordauthentication|pubkeyauthentication'

passwordauthentication no
pubkeyauthentication yes
hostbasedauthentication yes

Adjust user=, host=, and addr= to mirror the client hostname and source address. Add laddr=192.168.56.121,lport=22 when you need to match rules tied to the local server endpoint.

Hostname and DNS requirements

Verify forward and reverse resolution

Host-based authentication compares the client hostname in the authenticated request against names in shosts.equiv and /etc/ssh/ssh_known_hosts. Keep the same form everywhere — short name (vm1) or FQDN (vm1.lab.example), not a mix.

On the server, confirm both directions for the client address:

getent hosts vm1.lab.example
getent hosts 192.168.56.116

Both commands should return vm1.lab.example for 192.168.56.116. Multi-homed clients must use the address and hostname pairing you authorized, or reverse DNS on the server must return the name listed in shosts.equiv.

Fix userauth_hostbased mismatch

When reverse lookup fails, sshd may log:

userauth_hostbased mismatch: client sends vm1.lab.example, but we resolve 192.168.56.116 to 192.168.56.116

Fix forward and reverse records in DNS or /etc/hosts first. Consistent naming makes the trust relationship easier to audit.

If you cannot correct reverse DNS immediately, set on the server:

HostbasedUsesNameFromPacketOnly yes

That skips the server's reverse-DNS-derived hostname check and uses the hostname from the authenticated host-based request instead. The client must still prove possession of the corresponding trusted host private key. Prefer fixing DNS first; UseDNS yes is not the primary fix for this error class.

Security considerations

Host-based authentication concentrates risk at the machine layer:

• Compromise of a trusted client exposes every shosts.equiv pairing you listed, not just one user's key
• Host private keys in /etc/ssh are more sensitive than a single user key because ssh-keysign can sign for any local user session on the client
• Keep the trust list small — one jump or batch host, not a subnet
• Rotate host keys deliberately — update /etc/ssh/ssh_known_hosts when a client host key changes
• Leave SELinux enforcing on RHEL — fix contexts instead of disabling MAC

For most new designs, SSH user keys or certificates provide clearer revocation and a smaller blast radius.

Troubleshooting

No matching host-based algorithm

If verbose output shows host-based attempted but no acceptable key type remains, check algorithm support on the client:

ssh -Q HostbasedAcceptedAlgorithms

ssh-ed25519
ecdsa-sha2-nistp256
rsa-sha2-256
rsa-sha2-512

On the server, align HostbasedAcceptedAlgorithms with the client host key you installed. Older documentation may reference HostbasedAcceptedKeyTypes; on OpenSSH 9.x and 10.x use HostbasedAcceptedAlgorithms.

Summary

OpenSSH host-based authentication trusts a client machine through its host keys and ssh-keysign, then authorizes a matching host/username pair in /etc/ssh/shosts.equiv before opening a local session with the same account name. It is distinct from user public-key login and from SSH certificates.

On the client, enable HostbasedAuthentication and EnableSSHKeysign in global /etc/ssh/ssh_config and install openssh-keysign on RHEL. On the server, set HostbasedAuthentication yes, IgnoreUserKnownHosts yes, and IgnoreRhosts yes; verify the client Ed25519 fingerprint before adding it to /etc/ssh/ssh_known_hosts; maintain a minimal shosts.equiv. Reload sshd after server changes only.

When ssh -vv never shows hostbased, troubleshoot the client (HostbasedAuthentication, EnableSSHKeysign, openssh-keysign). When host-based is attempted but rejected, check server authorization, the trusted client key in /etc/ssh/ssh_known_hosts, and hostname resolution. For new fleets, prefer SSH user keys or certificates.

References

• sshd_config(5) — OpenBSD — HostbasedAuthentication, IgnoreUserKnownHosts, IgnoreRhosts, HostbasedUsesNameFromPacketOnly, HostbasedAcceptedAlgorithms
• ssh_config(5) — OpenBSD — HostbasedAuthentication, EnableSSHKeysign
• ssh-keysign(8) — OpenBSD — host key signing helper
• Red Hat Enterprise Linux 10 security considerations — ssh-keysign setuid behavior and host key permissions