/etc/ssh/sshd_config has around a hundred keywords, and the shipped file mentions maybe a third of them, most commented out. Commented lines are supposed to show the default, but distributions change defaults in drop-in files, so the file you read is often not what sshd is doing.
This is a reference: how sshd parses its configuration, how to see the effective values, and what each option that matters does, with its upstream default. Defaults below were checked with sshd -T on OpenSSH 9.2 and 10.0. For which values to choose and why, read our SSH security best practices guide alongside this one.
How sshd Reads Its Configuration
Three rules explain nearly every "why is my setting ignored" question:
The first value wins β for most keywords, sshd uses the first value it reads and ignores later ones. This is the opposite of most config files. A PasswordAuthentication no at the bottom of the file loses to a PasswordAuthentication yes above it.
Drop-ins are read first β Debian, Ubuntu, RHEL 9+ and Fedora put Include /etc/ssh/sshd_config.d/*.conf at the top of the main file. Drop-ins therefore beat the main file, and among drop-ins, the alphabetically first file wins. 10-hardening.conf beats 50-cloud-init.conf.
Match blocks run to the next Match β a Match line starts a conditional block that ends at the next Match or the end of the file. Indentation means nothing. Put Match blocks at the end of the main file, or in their own drop-in (in current releases a Match block inside an included file ends with that file).
# Syntax check: silent on success, names the file and line on error
$ sudo sshd -t
/etc/ssh/sshd_config line 132: Directive 'Port' is not allowed within a Match block
# The effective configuration, after includes and defaults (lowercase keys)
$ sudo sshd -T | grep -E '^(port|permitrootlogin|passwordauthentication|x11forwarding) '
port 22
permitrootlogin without-password
passwordauthentication yes
x11forwarding yes
# Which drop-in set it?
$ sudo grep -ri '^ *passwordauthentication' /etc/ssh/sshd_config /etc/ssh/sshd_config.d/
/etc/ssh/sshd_config.d/50-cloud-init.conf:PasswordAuthentication yes
# Evaluate Match blocks for a specific connection
$ sudo sshd -T -C user=backup,host=nas.lan,addr=10.0.4.20 | grep -E '^(forcecommand|allowtcpforwarding) '
allowtcpforwarding no
forcecommand internal-sftp
# Apply: reload keeps existing sessions open
$ sudo systemctl reload ssh # Debian / Ubuntu
$ sudo systemctl reload sshd # RHEL / Fedora (Debian also accepts this alias)
without-password in that output is the legacy spelling of prohibit-password; sshd -T prints the old name but they mean the same thing. Keep a root shell open in another session whenever you reload, until a fresh login works.
Listener, Connection and Timeout Options
| Option | Default | What it does |
|---|---|---|
| Port | 22 | TCP port; may be repeated. Not allowed in Match |
| ListenAddress | all addresses | Bind to specific IPs, optionally addr:port. Repeatable |
| AddressFamily | any | inet (IPv4 only), inet6, or any |
| LoginGraceTime | 120 | Seconds a client has to finish authenticating; 0 means no limit |
| MaxStartups | 10:30:100 | Unauthenticated connections: start dropping 30% at 10, rising to 100% at 100 |
| PerSourceMaxStartups | none | Cap on unauthenticated connections from one source address or netblock |
| PerSourceNetBlockSize | 32:128 | Prefix lengths that count as one source for the per-source limits |
| PerSourcePenalties | on (9.8+) | Temporarily refuse sources that fail auth, crash sshd or idle at login |
| ClientAliveInterval | 0 (off) | Seconds of silence before sshd sends a keepalive through the encrypted channel |
| ClientAliveCountMax | 3 | Unanswered keepalives before disconnecting |
| TCPKeepAlive | yes | Kernel TCP keepalives; spoofable, but detect dead peers |
| ChannelTimeout | none (9.2+) | Close channels idle for a time, e.g. session=30m |
| UnusedConnectionTimeout | none (9.2+) | Close connections that have no open channels for a time |
| UseDNS | no | Reverse-resolve client IPs; yes slows logins when DNS is broken |
ClientAlive is not an idle timeout β a connected client answers keepalives, so ClientAliveInterval 300 with ClientAliveCountMax 2 drops a session only after about ten minutes of the client being unreachable. To end sessions where nobody is typing, use ChannelTimeout session=30m plus UnusedConnectionTimeout, or the shell's TMOUT.
Ubuntu socket activation β since Ubuntu 22.10, sshd is started on demand by ssh.socket. On 24.04 a systemd generator copies Port and ListenAddress from sshd_config into the socket, so after changing them run systemctl daemon-reload and systemctl restart ssh.socket; reloading ssh.service alone does not move the listener.
Changing the port on RHEL β SELinux only allows sshd to bind labelled ports: semanage port -a -t ssh_port_t -p tcp 2222, then open it in firewalld before restarting.
Authentication and Access Control
| Option | Default | What it does |
|---|---|---|
| PermitRootLogin | prohibit-password | yes, prohibit-password (keys only), forced-commands-only, or no |
| PubkeyAuthentication | yes | Allow public key authentication |
| PasswordAuthentication | yes | Allow passwords sent through the encrypted channel |
| KbdInteractiveAuthentication | yes | Challenge-response via PAM (OTP, 2FA). Replaced ChallengeResponseAuthentication |
| UsePAM | no (distros set yes) | Use PAM for account and session checks, and for kbd-interactive auth |
| AuthenticationMethods | any | Require methods in sequence, e.g. publickey,keyboard-interactive |
| PermitEmptyPasswords | no | Allow accounts with empty passwords when using password auth |
| MaxAuthTries | 6 | Auth attempts per connection; failures past half are logged |
| MaxSessions | 10 | Shell, login or subsystem sessions multiplexed on one connection |
| AuthorizedKeysFile | .ssh/authorized_keys .ssh/authorized_keys2 | Where user keys live; %h, %u and %% tokens allowed |
| AuthorizedKeysCommand | none | Program that prints keys for a user (LDAP, IAM). Needs AuthorizedKeysCommandUser |
| TrustedUserCAKeys | none | CA public keys whose signed user certificates are accepted |
| AuthorizedPrincipalsFile | none | Which certificate principals may log in as each user |
| RevokedKeys | none | File of revoked keys or a KRL |
| StrictModes | yes | Refuse keys when home or ~/.ssh permissions are too open |
| GSSAPIAuthentication | no | Kerberos login; RHEL enables it in its drop-in |
Four keywords restrict who may log in at all: DenyUsers, AllowUsers, DenyGroups and AllowGroups, processed in that order. Each takes space-separated patterns with * and ?; the user keywords also accept USER@HOST. Once any Allow keyword is set, everyone not matched is refused.
# Restrict by group...
AllowGroups ssh-users sftp-only
# ...or by user: alice and bob from anywhere, deploy only from the bastion
# AllowUsers alice bob deploy@10.0.1.5
# Keys first, then a TOTP prompt through PAM
AuthenticationMethods publickey,keyboard-interactive
KbdInteractiveAuthentication yes
UsePAM yes
Allow keywords combine β with both AllowUsers and AllowGroups set, a user must pass both checks. That is easy to get wrong, so pick one mechanism and test with a real login from a second session before closing the first.
PasswordAuthentication no is not always enough β with UsePAM yes and KbdInteractiveAuthentication yes, PAM can still prompt for a password. Debian and Ubuntu ship kbd-interactive off for this reason; check yours with sshd -T.
Host Keys and Cryptography
Algorithm lists take a comma-separated value. A leading + appends to the default list, - removes entries (wildcards allowed), and ^ moves entries to the front. List what your build supports with ssh -Q cipher, ssh -Q mac, ssh -Q kex and ssh -Q key.
| Option | Default | What it does |
|---|---|---|
| HostKey | rsa, ecdsa, ed25519 files | Private host key files offered to clients; repeatable |
| HostCertificate | none | Host certificate signed by your CA, so clients can skip TOFU prompts |
| KexAlgorithms | post-quantum hybrids first | Key exchange. 10.0 prefers mlkem768x25519-sha256; 9.x sntrup761x25519 |
| Ciphers | chacha20-poly1305, aes-ctr, aes-gcm | Symmetric ciphers for the session |
| MACs | etm variants first | Integrity algorithms; AEAD ciphers ignore this |
| HostKeyAlgorithms | ed25519, ecdsa, rsa-sha2 (+ certs) | Host key signature algorithms offered |
| PubkeyAcceptedAlgorithms | same set | User key types accepted. Renamed from PubkeyAcceptedKeyTypes in 8.5 |
| CASignatureAlgorithms | no ssh-rsa (SHA-1) | Algorithms a CA may use to sign certificates |
| RequiredRSASize | 1024 (9.1+) | Minimum RSA key size accepted for user and host keys |
| RekeyLimit | 0 0 | Rekey after this much data or time; 0 means the cipher's default |
# Remove a family from the defaults without restating the whole list
KexAlgorithms -ecdh-sha2-*,diffie-hellman-group14-sha256
MACs -*-sha1*,umac-64*
# Raise the RSA floor
RequiredRSASize 3072
# Confirm what is offered now
$ sudo sshd -T | grep -E '^(kexalgorithms|macs) '
RHEL uses crypto policies β on RHEL and Fedora, the algorithm lists come from /etc/crypto-policies/back-ends/opensshserver.config, pulled in by /etc/ssh/sshd_config.d/50-redhat.conf. Change them system-wide with update-crypto-policies --set FUTURE rather than in sshd_config, or set your own lists in a drop-in that sorts before 50-redhat.conf.
Forwarding, Sessions, Environment and Logging
| Option | Default | What it does |
|---|---|---|
| AllowTcpForwarding | yes | yes/all, no, local (-L only) or remote (-R only) |
| AllowAgentForwarding | yes | Allow ssh -A agent forwarding |
| AllowStreamLocalForwarding | yes | Unix domain socket forwarding |
| X11Forwarding | no (Debian sets yes) | Allow ssh -X |
| GatewayPorts | no | Whether -R ports bind to all interfaces: no, yes, clientspecified |
| PermitTunnel | no | tun device forwarding: yes, point-to-point, ethernet, no |
| PermitOpen / PermitListen | any | Restrict -L destinations and -R listen addresses |
| DisableForwarding | no | One switch that disables all of the above, including X11 and agent |
| PermitTTY | yes | Allow a pseudo-terminal |
| PermitUserEnvironment | no | Honour ~/.ssh/environment and environment= in authorized_keys |
| AcceptEnv | none (Debian: LANG LC_*) | Client variables accepted via SendEnv |
| SetEnv | none | Variables the server sets for every session |
| ForceCommand | none | Run this instead of whatever the client asked for |
| ChrootDirectory | none | chroot after auth; path must be root-owned and not group/world-writable |
| Subsystem | sftp (path varies) | internal-sftp, or /usr/lib/openssh/sftp-server (Debian), /usr/libexec/openssh/sftp-server (RHEL) |
| Banner | none | File shown before authentication |
| PrintMotd / PrintLastLog | yes / yes | Debian sets PrintMotd no because pam_motd prints it |
| Compression | yes | Compression after authentication; yes, delayed (legacy) or no |
| LogLevel | INFO | VERBOSE also logs the fingerprint of the key used to log in |
| SyslogFacility | AUTH | RHEL sets AUTHPRIV |
Forwarding limits need a shell limit too β sshd's own manual points out that disabling TCP forwarding does not stop a user who has a shell from running their own forwarder. Restrictions only bite when combined with ForceCommand or a restricted shell.
What LogLevel VERBOSE adds β INFO already logs Accepted publickey for deploy from 10.0.1.5 port 51022 ssh2: ED25519 SHA256:β¦. VERBOSE adds the incoming connection line, Accepted key ED25519 SHA256:β¦ found at /home/deploy/.ssh/authorized_keys:3 (which file and line matched), and the session start. Search with journalctl -u ssh (Debian/Ubuntu) or -u sshd (RHEL).
Match Blocks in Practice
Match takes one or more criteria: User, Group, Host, Address, LocalAddress, LocalPort, RDomain or All. Patterns can be negated with ! and addresses can be CIDR ranges. For each keyword, a matching block overrides the global value, and the first matching block that sets it wins. Only a subset of keywords is allowed inside Match; sshd -t tells you when you use one that is not.
# /etc/ssh/sshd_config.d/90-match.conf
# Global: PasswordAuthentication no. Passwords only from the management network
Match Address 10.0.0.0/8
PasswordAuthentication yes
# SFTP-only accounts, jailed to their own directory
Match Group sftp-only
ChrootDirectory /srv/sftp/%u
ForceCommand internal-sftp
DisableForwarding yes
PermitTTY no
# Administrators may forward agents; nobody else may
Match Group wheel,sudo
AllowAgentForwarding yes
$ sudo sshd -t && sudo sshd -T -C user=alice,host=x,addr=10.0.5.7 | grep passwordauth
passwordauthentication yes
Chroot ownership β /srv/sftp/alice must be owned by root and not writable by alice, or sshd closes the connection after authenticating. Give her a writable subdirectory such as /srv/sftp/alice/upload.
Global default first, exceptions in Match β set the strict value globally (AllowAgentForwarding no) and loosen it per group. The opposite, loose globally and strict in Match, fails open when a Match does not apply.
Client side β the client has its own Host and Match blocks in ~/.ssh/config; our SSH config generator builds those. Also block port 22 at the network edge with the firewall rules generator.
Frequently Asked Questions
Why is my sshd_config change being ignored?
Most likely an earlier line set the same keyword, because sshd uses the first value it reads. Drop-ins in /etc/ssh/sshd_config.d are included at the top of the main file, so a file such as 50-cloud-init.conf can override your edit. Run sudo sshd -T to see the effective value, then grep the drop-in directory to find which file set it.
What is the default value of PermitRootLogin?
Since OpenSSH 7.0 the default is prohibit-password, which allows root to log in with a key but not a password. sshd -T prints it as without-password, the older name for the same setting. Some distributions and images override it, so always check the effective value.
How do I see the effective sshd configuration?
Run sudo sshd -T. It prints every keyword in lowercase with its effective value after includes and defaults. Add -C user=NAME,host=HOST,addr=IP to evaluate Match blocks for a specific connection, and use sudo sshd -t to check syntax before reloading.
Do I need to restart sshd after changing sshd_config?
A reload is enough for most changes and keeps existing sessions open: systemctl reload ssh on Debian and Ubuntu, or systemctl reload sshd on RHEL and Fedora. On Ubuntu 22.10 and later, changing Port or ListenAddress also needs systemctl daemon-reload and systemctl restart ssh.socket.
Does ClientAliveInterval disconnect idle users?
No. It sends keepalive messages that a connected client answers automatically, so it only disconnects clients that have become unreachable. To close sessions with no activity, use ChannelTimeout and UnusedConnectionTimeout on OpenSSH 9.2 or later, or set TMOUT in the shell.