chore(ssh): improve configuration notes and examples

examples/ssh/sshd_config

@@ -1,17 +1,30 @@
 ################################################################################
 ## /etc/ssh/sshd_config
 ##
-## SSHD server system-wide configuration file.
+## OpenSSH daemon system-wide configuration file.
+## Last updated: see file modification date.
 ##
-## This sshd was compiled with PATH='/usr/bin:/bin:/usr/sbin:/sbin'.
+## Uncommented options override the default value.
-## The strategy used for options in the default sshd_config shipped with OpenSSH
+## Unless noted otherwise, for each keyword, the *first* obtained value will be
-## is to specify options with their default value where possible, but leave them
+## used in a first-come-first-served fashion.
-## commented.  Uncommented options override the default value.
+## Keywords are case-*in*sensitive, and arguments are case-*sensitive*.
 ##
 ## Sources:
 ## - https://man.openbsd.org/sshd_config
 ################################################################################
 
+# To modify the system-wide sshd configuration, create a "*.conf" file under
+# "/etc/ssh/sshd_config.d/" which will be automatically included below.
+# Don't edit this configuration file itself if possible to avoid update
+# problems.
+Include /etc/ssh/sshd_config.d/*.conf
+
+# The strategy used for options in the default sshd_config shipped with
+# OpenSSH is to specify options with their default value where
+# possible, but leave them commented.  Uncommented options override the
+# default value.
+Include /usr/etc/ssh/sshd_config.d/*.conf
+
 #Port 22
 #AddressFamily any
 #ListenAddress 0.0.0.0
@@ -40,7 +53,7 @@ PermitRootLogin yes
 
 # The default is to check both .ssh/authorized_keys and .ssh/authorized_keys2
 # but this is overridden so installations will only check .ssh/authorized_keys
-AuthorizedKeysFile	.ssh/authorized_keys
+AuthorizedKeysFile      .ssh/authorized_keys
 
 #AuthorizedPrincipalsFile none
 
@@ -60,7 +73,7 @@ AuthorizedKeysFile	.ssh/authorized_keys
 #PermitEmptyPasswords no
 
 # Change to no to disable s/key passwords
-#ChallengeResponseAuthentication yes
+#KbdInteractiveAuthentication yes
 
 # Kerberos options
 #KerberosAuthentication no
@@ -76,13 +89,13 @@ AuthorizedKeysFile	.ssh/authorized_keys
 
 # Set this to 'yes' to enable PAM authentication, account processing,
 # and session processing. If this is enabled, PAM authentication will
-# be allowed through the ChallengeResponseAuthentication and
+# be allowed through the KbdInteractiveAuthentication and
 # PasswordAuthentication.  Depending on your PAM configuration,
-# PAM authentication via ChallengeResponseAuthentication may bypass
+# PAM authentication via KbdInteractiveAuthentication may bypass
-# the setting of "PermitRootLogin without-password".
+# the setting of "PermitRootLogin prohibit-password".
 # If you just want the PAM account and session checks to run without
 # PAM authentication, then enable this but set PasswordAuthentication
-# and ChallengeResponseAuthentication to 'no'.
+# and KbdInteractiveAuthentication to 'no'.
 UsePAM yes
 
 #AllowAgentForwarding yes
@@ -92,8 +105,7 @@ X11Forwarding yes
 #X11DisplayOffset 10
 #X11UseLocalhost yes
 #PermitTTY yes
-#PrintMotd yes
+PrintMotd no
-#PrintLastLog yes
 #TCPKeepAlive yes
 #PermitUserEnvironment no
 #Compression delayed
@@ -110,7 +122,7 @@ X11Forwarding yes
 #Banner none
 
 # override default of no subsystems
-Subsystem	sftp	/usr/lib/ssh/sftp-server
+Subsystem       sftp    /usr/lib/ssh/sftp-server
 
 # This enables accepting locale enviroment variables LC_* LANG, see sshd_config(5).
 AcceptEnv LANG LC_CTYPE LC_NUMERIC LC_TIME LC_COLLATE LC_MONETARY LC_MESSAGES
@@ -119,7 +131,7 @@ AcceptEnv LC_IDENTIFICATION LC_ALL
 
 # Example of overriding settings on a per-user basis
 #Match User anoncvs
-#	X11Forwarding no
+#       X11Forwarding no
-#	AllowTcpForwarding no
+#       AllowTcpForwarding no
-#	PermitTTY no
+#       PermitTTY no
-#	ForceCommand cvs server
+#       ForceCommand cvs server

examples/ssh/sshd_config.defaults

@@ -0,0 +1,113 @@
+################################################################################
+## /etc/ssh/sshd_config
+##
+## OpenSSH daemon system-wide configuration file stating only default values.
+## Last updated: see file modification date.
+##
+## Uncommented options override the default value.
+## Unless noted otherwise, for each keyword, the *first* obtained value will be
+## used in a first-come-first-served fashion.
+## Keywords are case-*in*sensitive, and arguments are case-*sensitive*.
+##
+## Sources:
+## - https://man.openbsd.org/sshd_config
+################################################################################
+
+# AcceptEnv <none>
+AddressFamily any
+AllowAgentForwarding yes
+# AllowGroups <none>
+AllowStreamLocalForwarding yes
+AllowTcpForwarding yes
+# AllowUsers <none>
+AuthenticationMethods any
+# AuthorizedKeysCommand <none>
+# AuthorizedKeysCommandUser <none>
+AuthorizedKeysFile ".ssh/authorized_keys .ssh/authorized_keys2"
+# AuthorizedPrincipalsCommand <none>
+# AuthorizedPrincipalsCommandUser <none>
+# AuthorizedPrincipalsFile <none>
+# Banner <none>
+CASignatureAlgorithms ssh-ed25519,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,sk-ssh-ed25519@openssh.com,sk-ecdsa-sha2-nistp256@openssh.com,rsa-sha2-512,rsa-sha2-256
+# ChannelTimeout <none>
+ChrootDirectory none
+Ciphers chacha20-poly1305@openssh.com,aes128-ctr,aes192-ctr,aes256-ctr,aes128-gcm@openssh.com,aes256-gcm@openssh.com
+ClientAliveCountMax 3
+ClientAliveInterval 0
+Compression yes
+# DenyGroups <none>
+# DenyUsers <none>
+DisableForwarding no
+ExposeAuthInfo no
+FingerprintHash sha256
+ForceCommand none
+GatewayPorts no
+GSSAPIAuthentication no
+GSSAPICleanupCredentials yes
+GSSAPIStrictAcceptorCheck yes
+HostbasedAcceptedAlgorithms ssh-ed25519-cert-v01@openssh.com,ecdsa-sha2-nistp256-cert-v01@openssh.com,ecdsa-sha2-nistp384-cert-v01@openssh.com,ecdsa-sha2-nistp521-cert-v01@openssh.com,sk-ssh-ed25519-cert-v01@openssh.com,sk-ecdsa-sha2-nistp256-cert-v01@openssh.com,rsa-sha2-512-cert-v01@openssh.com,rsa-sha2-256-cert-v01@openssh.com,ssh-ed25519,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,sk-ssh-ed25519@openssh.com,sk-ecdsa-sha2-nistp256@openssh.com,rsa-sha2-512,rsa-sha2-256
+HostbasedAuthentication no
+HostbasedUsesNameFromPacketOnly no
+# HostCertificate <none>
+HostKey "/etc/ssh/ssh_host_ecdsa_key /etc/ssh/ssh_host_ed25519_key /etc/ssh/ssh_host_rsa_key"
+# HostKeyAgent <none>
+HostKeyAlgorithms ssh-ed25519-cert-v01@openssh.com,ecdsa-sha2-nistp256-cert-v01@openssh.com,ecdsa-sha2-nistp384-cert-v01@openssh.com,ecdsa-sha2-nistp521-cert-v01@openssh.com,sk-ssh-ed25519-cert-v01@openssh.com,sk-ecdsa-sha2-nistp256-cert-v01@openssh.com,rsa-sha2-512-cert-v01@openssh.com,rsa-sha2-256-cert-v01@openssh.com,ssh-ed25519,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,sk-ssh-ed25519@openssh.com,sk-ecdsa-sha2-nistp256@openssh.com,rsa-sha2-512,rsa-sha2-256
+IgnoreRhosts yes
+IgnoreUserKnownHosts no
+# Include <none>
+IPQoS "af21 cs1"
+KbdInteractiveAuthentication yes
+KerberosAuthentication no
+KerberosGetAFSToken no
+KerberosOrLocalPasswd yes
+KerberosTicketCleanup yes
+KexAlgorithms sntrup761x25519-sha512@openssh.com,curve25519-sha256,curve25519-sha256@libssh.org,ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group-exchange-sha256,diffie-hellman-group16-sha512,diffie-hellman-group18-sha512,diffie-hellman-group14-sha256
+ListenAddress 0.0.0.0
+LoginGraceTime 120
+LogLevel INFO
+# LogVerbose <none>
+MACs umac-64-etm@openssh.com,umac-128-etm@openssh.com,hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,hmac-sha1-etm@openssh.com,umac-64@openssh.com,umac-128@openssh.com,hmac-sha2-256,hmac-sha2-512,hmac-sha1
+MaxAuthTries 6
+MaxSessions 10
+MaxStartups 10:30:100
+ModuliFile /etc/moduli
+PasswordAuthentication yes
+PermitEmptyPasswords no
+PermitListen any
+PermitOpen any
+PermitRootLogin prohibit-password
+PermitTTY yes
+PermitTunnel no
+PermitUserEnvironment no
+PermitUserRC yes
+PerSourceMaxStartups none
+PerSourceNetBlockSize 32:128
+PerSourcePenalties "crash:90s authfail:5s noauth:1s grace-exceeded:20s max:10m min:15s max-sources4:65536 max-sources6:65536 overflow:permissive overflow6:permissive"
+# PerSourcePenaltyExemptList <none>
+PidFile /var/run/sshd.pid
+Port 22
+PrintLastLog yes
+PrintMotd yes
+PubkeyAcceptedAlgorithms ssh-ed25519-cert-v01@openssh.com,ecdsa-sha2-nistp256-cert-v01@openssh.com,ecdsa-sha2-nistp384-cert-v01@openssh.com,ecdsa-sha2-nistp521-cert-v01@openssh.com,sk-ssh-ed25519-cert-v01@openssh.com,sk-ecdsa-sha2-nistp256-cert-v01@openssh.com,rsa-sha2-512-cert-v01@openssh.com,rsa-sha2-256-cert-v01@openssh.com,ssh-ed25519,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,sk-ssh-ed25519@openssh.com,sk-ecdsa-sha2-nistp256@openssh.com,rsa-sha2-512,rsa-sha2-256
+PubkeyAuthOptions none
+PubkeyAuthentication yes
+RekeyLimit "default none"
+RequiredRSASize 1024
+RevokedKeys none
+# RDomain <none>
+# SecurityKeyProvider <none>
+# SetEnv <none>
+StreamLocalBindMask 0177
+StreamLocalBindUnlink no
+StrictModes yes
+# Subsystem <none>
+SyslogFacility AUTH
+TCPKeepAlive no
+TrustedUserCAKeys none
+UnusedConnectionTimeout none
+UseDNS no
+VersionAddendum none
+X11DisplayOffset 10
+X11Forwarding no
+X11UseLocalhost yes
+XAuthLocation /usr/X11R6/bin/xauth

knowledge base/ssh.md

@@ -1,7 +1,5 @@
 # SSH
 
-## Table of contents <!-- omit in toc -->
-
 1. [TL;DR](#tldr)
 1. [Server installation on Windows](#server-installation-on-windows)
 1. [Key Management](#key-management)
@@ -182,8 +180,21 @@ When connecting to a host, the SSH client will use settings:
 1. from the user's `~/.ssh/config` file,
 1. from the `/etc/ssh/ssh_config` file
 
-Settings are loaded in a **first-come-first-served** way. They should hence appear from the most specific to the most
+Unless noted otherwise, for each parameter, only the **first** obtained value will be used
-generic, both by file and by position in those files:
+(_first-come-first-served_).<br/>
+Values should hence appear from the most **specific** to the most **generic**, both by file and by position in those
+files.
+
+The configuration files contain sections separated by `Host` specifications<br/>
+Those sections are only applied to hosts that match one of the patterns given in each specification.
+
+The file contains keyword-argument pairs, one per line.<br/>
+Lines starting with `#` and empty lines are interpreted as comments.<br/>
+Arguments may optionally be enclosed in **double** quotes (`"`) in order to represent arguments containing spaces.<br/>
+Configuration options may be separated by whitespace, or optional whitespace and exactly one `=`. The latter format is
+useful to avoid the need to quote whitespace when specifying configuration options using the ssh, scp, and sftp `-o`
+option.<br/>
+Keywords are case-**in**sensitive and arguments are case-**sensitive**.
 
 ```ssh-config
 Host targaryen
@@ -253,8 +264,34 @@ IdentityAgent ~/.gnupg/S.gpg-agent.ssh
 
 ## Server configuration
 
-Config file defaults to `/etc/ssh/sshd_config`.<br/>
+The daemon's default configuration file is `/etc/ssh/sshd_config`.<br/>
-Restart the server upon config file change.
+Reload the server upon config file change. No need to restart it.
+
+The configuration file contains keyword-argument pairs, one per line.<br/>
+Unless noted otherwise, for each keyword, the **first** obtained value is used (_first-come-first-served_).<br/>
+Lines starting with `#` and empty lines are interpreted as comments.<br/>
+Arguments may optionally be enclosed in **double** quotes (`"`) in order to represent arguments containing spaces.<br/>
+Keywords are case-**in**sensitive and arguments are case-**sensitive**.
+
+**Some** Linux distributions (e.g., Debian, OpenSUSE) started including `.conf` files in `/etc/ssh/sshd_config.d/` and
+`/usr/etc/ssh/sshd_config.d/` as first thing in the base configuration file:
+
+```ssh-config
+# To modify the system-wide sshd configuration, create a "*.conf" file under
+# "/etc/ssh/sshd_config.d/" which will be automatically included below.
+# Don't edit this configuration file itself if possible to avoid update
+# problems.
+Include /etc/ssh/sshd_config.d/*.conf
+
+# The strategy used for options in the default sshd_config shipped with
+# OpenSSH is to specify options with their default value where
+# possible, but leave them commented.  Uncommented options override the
+# default value.
+Include /usr/etc/ssh/sshd_config.d/*.conf
+```
+
+This avoids issues from updates overwriting the default file and allows user configurations to override defaults in a
+cleaner way.
 
 ### Change port
 
@@ -333,21 +370,22 @@ PubkeyAcceptedAlgorithms +ssh-rsa
 to your `~/.ssh/config` like so:
 
 ```diff
-Host  azure-devops
+ Host  azure-devops
-    IdentityFile              ~/.ssh/id_rsa
+     IdentityFile              ~/.ssh/id_rsa
-    IdentitiesOnly            yes
+     IdentitiesOnly            yes
-+   HostkeyAlgorithms         +ssh-rsa
++    HostkeyAlgorithms         +ssh-rsa
-+   PubkeyAcceptedAlgorithms  +ssh-rsa
++    PubkeyAcceptedAlgorithms  +ssh-rsa
 ```
 
 Solution: update the SSH server.
 
 ## Further readings
 
-- [`SSH_CONFIG(5)`][ssh_config man page] man page
+- [`SSH_CONFIG(5)` man page][ssh_config man page]
-- [`ssh_config`][ssh_config example] example
+- [`ssh_config` example][ssh_config example]
-- [`SSHD_CONFIG(5)`][sshd_config man page] man page
+- [`SSHD_CONFIG(5)` man page][sshd_config man page]
-- [`sshd_config`][sshd_config example] example
+- [`sshd_config` defaults][sshd_config defaults]
+- [`sshd_config` example][sshd_config example]
 - [ssh-agent]
 - [Use GPG keys for SSH authentication]
 
@@ -366,15 +404,16 @@ Solution: update the SSH server.
 - [How to check if an RSA public / private key pair match]
 
 <!--
-  References
+  Reference
+  ═╬═Time══
   -->
 
-<!-- In-article sections -->
 <!-- Knowledge base -->
 [use gpg keys for ssh authentication]: gnupg.md#use-gpg-keys-for-ssh-authentication
 
 <!-- Files -->
 [ssh_config example]: ../examples/ssh/ssh_config
+[sshd_config defaults]: ../examples/ssh/sshd_config.defaults
 [sshd_config example]: ../examples/ssh/sshd_config
 
 <!-- Upstream -->