← Full reference

sshd

The SSH server — key sshd_config options, checking the config with sshd -t / -T, reloading without losing access

sshd is the OpenSSH server: it accepts incoming SSH connections. Its behavior is set by /etc/ssh/sshd_config plus the files in /etc/ssh/sshd_config.d/*.conf. This page covers server settings; the client side (ssh, keys, ~/.ssh/config) is on the ssh page.

Syntax

sshd -t                 # check the config
sshd -T                 # print the effective values of all options
/usr/sbin/sshd [options]  # start the server (usually systemd does this)

Command-line options

OptionWhat it does
-tcheck the syntax of the config and host keys; on error — exit code 255 and a line with the line number
-Tcheck and print the effective values of all options (names in lowercase)
-T -C user=…,host=…,addr=…effective values for a specific connection — with Match blocks applied
-f fileanother config file
-p portlisten on this port (overrides Port)
-o 'Option value'set an option as a config line
-Ddon't go to the background
-ddebug: one session, verbose output, doesn't go to the background
-ewrite the log to stderr instead of syslog
-E filewrite the log to a file

Main sshd_config directives

Where to listen

DirectiveWhat it sets
Port 22port; several Port lines — several ports
ListenAddress 0.0.0.0address (and port: ListenAddress 10.0.0.1:2222)
AddressFamily any|inet|inet6IPv4, IPv6 or both

Who logs in and how

DirectiveWhat it sets
PermitRootLoginyes, prohibit-password (default: root by key only), forced-commands-only, no
PasswordAuthentication yes|nopassword login
PubkeyAuthentication yes|nokey login (default yes)
KbdInteractiveAuthentication yes|nointeractive input (one-time codes, PAM prompts)
PermitEmptyPasswords nowhether empty passwords are allowed
AuthorizedKeysFile .ssh/authorized_keyswhere to look for the user's public keys
AllowUsers alice bob@10.0.0.*let in only these users (user@host is allowed)
DenyUsers, AllowGroups, DenyGroupsthe same as a deny list and by group
UsePAM yesgo through PAM (yes on Ubuntu)

Protection and sessions

DirectiveWhat it sets
MaxAuthTries 6login attempts per connection
LoginGraceTime 120seconds to log in, then the connection is dropped
MaxStartups 10:30:100limit of concurrent unauthenticated connections
MaxSessions 10sessions per connection
ClientAliveInterval 300 / ClientAliveCountMax 3check that the client is alive and drop "dead" sessions
X11Forwarding, AllowTcpForwarding, AllowAgentForwardingallow forwarding
LogLevel INFO|VERBOSE|DEBUGlog verbosity
Match User|Group|Address …block: the options below apply only to matching connections, until the next Match or the end of the file

How the config is applied

  • The first value wins. For most options sshd takes the first value it encounters and ignores the rest.
  • Include /etc/ssh/sshd_config.d/*.conf is at the top of Ubuntu's main file. So files in sshd_config.d/ override what is written further down in sshd_config.
  • Changes take effect only after the server is reloaded: systemctl reload ssh or service ssh reload (they check the config first), or kill -HUP $(cat /run/sshd.pid). Already open sessions are not dropped.

Examples

# what is actually in effect now (not what's written in the file)
sshd -T | grep -E '^(port|permitrootlogin|passwordauthentication|pubkeyauthentication|allowusers) '

# disable password login in a separate file — it is read before the main one
echo 'PasswordAuthentication no' > /etc/ssh/sshd_config.d/10-hardening.conf
sshd -t && service ssh reload

# let in only two users, one of them only from the local network
echo 'AllowUsers deploy admin@10.0.0.*' >> /etc/ssh/sshd_config.d/10-hardening.conf

# password allowed only from one subnet
cat >> /etc/ssh/sshd_config <<'EOF'
Match Address 10.0.0.0/24
    PasswordAuthentication yes
EOF

# which values a specific user from a specific address gets
sshd -T -C user=deploy,host=client,addr=10.0.0.5 | grep passwordauthentication

# start a second instance on another port with a log file — for debugging
mkdir -p /run/sshd
/usr/sbin/sshd -p 2222 -E /tmp/sshd.log -o PidFile=/tmp/sshd2.pid

# debug server in the terminal: every login step is visible
/usr/sbin/sshd -d -p 2223

# check login without interactive prompts
ssh -o BatchMode=yes -p 2222 deploy@127.0.0.1 true && echo login works

Pitfalls

  • Reloading with a broken config kills the server. kill -HUP with a config error doesn't roll back: the main sshd process exits and the port stops listening. Always run sshd -t before reloading. service ssh reload and systemctl reload ssh do this check themselves.
  • Don't close your current session until you've checked login in a new one. A mistake in AllowUsers or PasswordAuthentication no without a key — and access is lost.
  • AllowUsers is an allowlist. As soon as it appears, everyone not listed (root included) gets Permission denied. In the log: not allowed because not listed in AllowUsers.
  • A value in sshd_config.d/ overrides the main file. You write PasswordAuthentication no at the end of sshd_config, but sshd_config.d/50-cloud-init.conf has yes — yes stays. Check with sshd -T.
  • Match applies until the end of the file. Everything written after a Match block belongs to it. Put Match blocks at the very end.
  • Missing privilege separation directory: /run/sshd — when started by hand (without systemd), the directory doesn't exist. mkdir -p /run/sshd.
  • On Ubuntu 24.04 the port is listened on by ssh.socket. On a machine with systemd, after changing Port or ListenAddress you need systemctl daemon-reload and systemctl restart ssh.socket, not just a service reload — this is spelled out in a comment in sshd_config.
  • Two Port lines don't replace each other — both ports are opened.
  • Owner of authorized_keys. With StrictModes yes (the default), sshd checks the owner and permissions of the home directory, ~/.ssh and authorized_keys. A file copied by root into someone else's home directory without chown is a common reason key login is refused; keep ~/.ssh at 700 and the file at 600.

See also

ssh · ss · service · useradd · sudo