Skip to content

sshd_config Explained: Every Option That Matters, With Defaults

A reference to sshd_config: how first-match parsing, drop-ins and Match blocks work, plus defaults and meaning for auth, crypto, forwarding, session and logging options.

●By 12 min read

/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

OptionDefaultWhat it does
Port22TCP port; may be repeated. Not allowed in Match
ListenAddressall addressesBind to specific IPs, optionally addr:port. Repeatable
AddressFamilyanyinet (IPv4 only), inet6, or any
LoginGraceTime120Seconds a client has to finish authenticating; 0 means no limit
MaxStartups10:30:100Unauthenticated connections: start dropping 30% at 10, rising to 100% at 100
PerSourceMaxStartupsnoneCap on unauthenticated connections from one source address or netblock
PerSourceNetBlockSize32:128Prefix lengths that count as one source for the per-source limits
PerSourcePenaltieson (9.8+)Temporarily refuse sources that fail auth, crash sshd or idle at login
ClientAliveInterval0 (off)Seconds of silence before sshd sends a keepalive through the encrypted channel
ClientAliveCountMax3Unanswered keepalives before disconnecting
TCPKeepAliveyesKernel TCP keepalives; spoofable, but detect dead peers
ChannelTimeoutnone (9.2+)Close channels idle for a time, e.g. session=30m
UnusedConnectionTimeoutnone (9.2+)Close connections that have no open channels for a time
UseDNSnoReverse-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

OptionDefaultWhat it does
PermitRootLoginprohibit-passwordyes, prohibit-password (keys only), forced-commands-only, or no
PubkeyAuthenticationyesAllow public key authentication
PasswordAuthenticationyesAllow passwords sent through the encrypted channel
KbdInteractiveAuthenticationyesChallenge-response via PAM (OTP, 2FA). Replaced ChallengeResponseAuthentication
UsePAMno (distros set yes)Use PAM for account and session checks, and for kbd-interactive auth
AuthenticationMethodsanyRequire methods in sequence, e.g. publickey,keyboard-interactive
PermitEmptyPasswordsnoAllow accounts with empty passwords when using password auth
MaxAuthTries6Auth attempts per connection; failures past half are logged
MaxSessions10Shell, login or subsystem sessions multiplexed on one connection
AuthorizedKeysFile.ssh/authorized_keys .ssh/authorized_keys2Where user keys live; %h, %u and %% tokens allowed
AuthorizedKeysCommandnoneProgram that prints keys for a user (LDAP, IAM). Needs AuthorizedKeysCommandUser
TrustedUserCAKeysnoneCA public keys whose signed user certificates are accepted
AuthorizedPrincipalsFilenoneWhich certificate principals may log in as each user
RevokedKeysnoneFile of revoked keys or a KRL
StrictModesyesRefuse keys when home or ~/.ssh permissions are too open
GSSAPIAuthenticationnoKerberos 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.

sponsored

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.

OptionDefaultWhat it does
HostKeyrsa, ecdsa, ed25519 filesPrivate host key files offered to clients; repeatable
HostCertificatenoneHost certificate signed by your CA, so clients can skip TOFU prompts
KexAlgorithmspost-quantum hybrids firstKey exchange. 10.0 prefers mlkem768x25519-sha256; 9.x sntrup761x25519
Cipherschacha20-poly1305, aes-ctr, aes-gcmSymmetric ciphers for the session
MACsetm variants firstIntegrity algorithms; AEAD ciphers ignore this
HostKeyAlgorithmsed25519, ecdsa, rsa-sha2 (+ certs)Host key signature algorithms offered
PubkeyAcceptedAlgorithmssame setUser key types accepted. Renamed from PubkeyAcceptedKeyTypes in 8.5
CASignatureAlgorithmsno ssh-rsa (SHA-1)Algorithms a CA may use to sign certificates
RequiredRSASize1024 (9.1+)Minimum RSA key size accepted for user and host keys
RekeyLimit0 0Rekey 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

OptionDefaultWhat it does
AllowTcpForwardingyesyes/all, no, local (-L only) or remote (-R only)
AllowAgentForwardingyesAllow ssh -A agent forwarding
AllowStreamLocalForwardingyesUnix domain socket forwarding
X11Forwardingno (Debian sets yes)Allow ssh -X
GatewayPortsnoWhether -R ports bind to all interfaces: no, yes, clientspecified
PermitTunnelnotun device forwarding: yes, point-to-point, ethernet, no
PermitOpen / PermitListenanyRestrict -L destinations and -R listen addresses
DisableForwardingnoOne switch that disables all of the above, including X11 and agent
PermitTTYyesAllow a pseudo-terminal
PermitUserEnvironmentnoHonour ~/.ssh/environment and environment= in authorized_keys
AcceptEnvnone (Debian: LANG LC_*)Client variables accepted via SendEnv
SetEnvnoneVariables the server sets for every session
ForceCommandnoneRun this instead of whatever the client asked for
ChrootDirectorynonechroot after auth; path must be root-owned and not group/world-writable
Subsystemsftp (path varies)internal-sftp, or /usr/lib/openssh/sftp-server (Debian), /usr/libexec/openssh/sftp-server (RHEL)
BannernoneFile shown before authentication
PrintMotd / PrintLastLogyes / yesDebian sets PrintMotd no because pam_motd prints it
CompressionyesCompression after authentication; yes, delayed (legacy) or no
LogLevelINFOVERBOSE also logs the fingerprint of the key used to log in
SyslogFacilityAUTHRHEL 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.

sponsored

Related Tools

See also