feat: flip swap mechanism — MD as primary, RST as override (Phase 1)

This is the first of three phases inverting the per-page swap mechanism
so MD becomes the canonical primary and RST becomes the rare override.

Phase 1 — file renames + conf.py exclude_patterns flip only:
- Rename docs/**/md-<stem>.md to docs/**/<stem>.md (drop md- prefix)
  for all 254 stems previously listed in docs/_swap.txt
- Rename docs/**/<stem>.rst to docs/**/rst-<stem>.rst (add rst- prefix)
  for the same 254 stems
- Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty
  comment-only since no pages need the RST fallback right now
- conf.py exclude_patterns flipped: rst-*.rst is now excluded by default
  instead of md-*.md
- conf.py runtime-artifact references updated to _rst_override_state.json
  and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce
  these names; for now no swap script runs because overrides list is empty)

Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py
with inverted rename direction, delete scripts/import_myst.py + tests, and
update tests/test_swap_sources.py for the new semantics.

Phase 3 will be the cleanup pass and ready-for-review flip.

Generated by robots https://vyos.io

1 files changed, 366 insertions, 0 deletions

diff --git a/docs/configuration/service/ssh.md b/docs/configuration/service/ssh.md
new file mode 100644
index 00000000..d873cbee
--- /dev/null
+++ b/docs/configuration/service/ssh.md
@@ -0,0 +1,366 @@
+(ssh)=
+
+# SSH
+
+{abbr}`SSH (Secure Shell)` is a cryptographic network protocol for operating
+network services securely over an unsecured network. The standard TCP port for
+SSH is 22. The best known example application is for remote login to computer
+systems by users.
+
+SSH provides a secure channel over an unsecured network in a client-server
+architecture, connecting an SSH client application with an SSH server. Common
+applications include remote command-line login and remote command execution,
+but any network service can be secured with SSH. The protocol specification
+distinguishes between two major versions, referred to as SSH-1 and SSH-2.
+
+The most visible application of the protocol is for access to shell accounts
+on Unix-like operating systems, but it sees some limited use on Windows as
+well. In 2015, Microsoft announced that they would include native support for
+SSH in a future release.
+
+SSH was designed as a replacement for Telnet and for unsecured remote shell
+protocols such as the Berkeley rlogin, rsh, and rexec protocols.
+Those protocols send information, notably passwords, in plaintext,
+rendering them susceptible to interception and disclosure using packet
+analysis. The encryption used by SSH is intended to provide confidentiality
+and integrity of data over an unsecured network, such as the Internet.
+
+:::{note}
+VyOS 1.1 supported login as user `root`. This has been removed due
+to tighter security in VyOS 1.2.
+:::
+
+:::{seealso}
+SSH {ref}`ssh_key_based_authentication`
+:::
+
+## Configuration
+
+```{cfgcmd} set service ssh port \<port\>
+
+Enabling SSH only requires you to specify the port ``<port>`` you want SSH to
+listen on. By default, SSH runs on port 22.
+```
+
+
+```{cfgcmd} set service ssh listen-address \<address\>
+
+Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be
+defined.
+```
+
+
+```{cfgcmd} set service ssh cipher \<cipher\>
+
+Define allowed ciphers used for the SSH connection. A number of allowed
+ciphers can be specified, use multiple occurrences to allow multiple ciphers.
+
+List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``,
+``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``,
+``aes128-gcm@openssh.com``, ``aes256-gcm@openssh.com``,
+``chacha20-poly1305@openssh.com``
+```
+
+
+```{cfgcmd} set service ssh disable-password-authentication
+
+Disable password based authentication. Login via SSH keys only. This hardens
+security!
+```
+
+
+```{cfgcmd} set service ssh fido pin-required
+
+Require FIDO2 keys to attest that a user has been verified (e.g. via a PIN).
+```
+
+
+````{cfgcmd} set service ssh fido touch-required
+
+Require FIDO2 keys to attest that a user is physically present.
+
+VyOS supports SSH authentication using FIDO2-backed keys generated by OpenSSH.
+Two FIDO2 key types are supported by OpenSSH: ``ed25519-sk``, ``ecdsa-sk``
+
+Generic FIDO2-backed SSH key generation example:
+
+:::{code-block} none
+ssh-keygen -t ecdsa-sk -O verify-required -C "fido2-ssh-key"
+:::
+
+```{eval-rst}
+During key generation, OpenSSH will:
+    * Request user presence (for example, a physical touch or confirmation)
+    * Optionally request user verification (PIN), if supported by the authenticator
+    * Create a local key handle file and a corresponding public key (``.pub``)
+```
+
+The private key material never leaves the authenticator device.
+
+VyOS configuration example:
+
+:::{code-block} none
+# Generate a FIDO2 SSH key on the client system
+# Copy the public key to the VyOS instance
+set system login user vyos authentication public-keys fido key '<public-key>'
+set system login user vyos authentication public-keys fido type 'sk-ecdsa-sha2-nistp256@openssh.com'
+set service ssh fido touch-required
+:::
+
+You can now log into the system using: ``ssh -i ~/.ssh/id_fido_key vyos@192.0.2.1``
+````
+
+
+```{cfgcmd} set service ssh disable-host-validation
+
+Disable the host validation through reverse DNS lookups - can speedup login
+time when reverse lookup is not possible.
+```
+
+
+```{cfgcmd} set service ssh mac \<mac\>
+
+Specifies the available {abbr}`MAC (Message Authentication Code)` algorithms.
+The MAC algorithm is used in protocol version 2 for data integrity protection.
+Multiple algorithms can be provided by using multiple commands, defining
+one algorithm per command.
+
+List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``,
+``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``,
+``umac-64@openssh.com``, ``umac-128@openssh.com``,
+``hmac-md5-etm@openssh.com``, ``hmac-md5-96-etm@openssh.com``,
+``hmac-ripemd160-etm@openssh.com``, ``hmac-sha1-etm@openssh.com``,
+``hmac-sha1-96-etm@openssh.com``, ``hmac-sha2-256-etm@openssh.com``,
+``hmac-sha2-512-etm@openssh.com``, ``umac-64-etm@openssh.com``,
+``umac-128-etm@openssh.com``
+```
+
+
+```{cfgcmd} set service ssh access-control \<allow | deny\> \<group | user\> \<name\>
+
+Add access-control directive to allow or deny users and groups. Directives
+are processed in the following order of precedence: ``deny-users``,
+``allow-users``, ``deny-groups`` and ``allow-groups``.
+```
+
+
+```{cfgcmd} set service ssh client-keepalive-interval \<interval\>
+
+Specify timeout interval for keepalive message in seconds.
+```
+
+
+```{cfgcmd} set service ssh key-exchange \<kex\>
+
+Specify allowed {abbr}`KEX (Key Exchange)` algorithms.
+
+List of supported algorithms: ``diffie-hellman-group1-sha1``,
+``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``,
+``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``,
+``diffie-hellman-group-exchange-sha1``,
+``diffie-hellman-group-exchange-sha256``,
+``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``,
+``curve25519-sha256`` and ``curve25519-sha256@libssh.org``.
+```
+
+
+```{cfgcmd} set service ssh loglevel \<quiet | fatal | error | info | verbose\>
+
+Set the ``sshd`` log level. The default is ``info``.
+```
+
+
+```{cfgcmd} set service ssh vrf \<name\>
+
+Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+
+```{cfgcmd} set service ssh pubkey-accepted-algorithm \<name\>
+
+Specifies the signature algorithms that will be accepted for public key
+authentication
+
+List of supported algorithms: ``ssh-ed25519``,
+``ssh-ed25519-cert-v01@openssh.com``, ``sk-ssh-ed25519@openssh.com``,
+``sk-ssh-ed25519-cert-v01@openssh.com``, ``ecdsa-sha2-nistp256``,
+``ecdsa-sha2-nistp256-cert-v01@openssh.com``, ``ecdsa-sha2-nistp384``,
+``ecdsa-sha2-nistp384-cert-v01@openssh.com``, ``ecdsa-sha2-nistp521``,
+``ecdsa-sha2-nistp521-cert-v01@openssh.com``,
+``sk-ecdsa-sha2-nistp256@openssh.com``,
+``sk-ecdsa-sha2-nistp256-cert-v01@openssh.com``,
+``webauthn-sk-ecdsa-sha2-nistp256@openssh.com``,
+``ssh-dss``, ``ssh-dss-cert-v01@openssh.com``, ``ssh-rsa``,
+``ssh-rsa-cert-v01@openssh.com``, ``rsa-sha2-256``,
+``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``,
+``rsa-sha2-512-cert-v01@openssh.com``
+```
+
+
+```{cfgcmd} set service ssh trusted-user-ca \<name\>
+
+Specify the name of the OpenSSH key-pair that acts as certificate authority
+and will be used to verify user certificates.
+
+You can use it by adding the OpenSSH key-pair under the PKI subsystem.
+
+Example:
+
+:::{code-block} none
+# Generate key-pair acting as CA
+$ ssh-keygen -f vyos-ssh-ca.key
+
+# Generate key for user: vyos_testca
+$ ssh-keygen -f vyos_testca  -C "vyos_tesca@vyos.net"
+
+# Sign public key from user vyos_testca and insert principal names: vyos, vyos_testca
+# with a key lifetime of two weeks - after which the key is unusable
+$ ssh-keygen -s vyos-ssh-ca.key -I vyos_testca@vyos.net -n vyos,vyos_testca -V +2w vyos_testca.pub
+
+$ set system login user vyos_testca
+$ set pki openssh test_ca public key AAAAB3N.....
+$ set pki openssh test_ca public type ssh-rsa
+$ set service ssh trusted-user-ca test_ca
+:::
+You can now log into the system using: ``ssh -i vyos_testca vyos_testca@vyos.test.com``
+```
+
+## Dynamic-protection
+
+Protects host from brute-force attacks against
+SSH. Log messages are parsed, line-by-line, for recognized patterns. If an
+attack, such as several login failures within a few seconds, is detected, the
+offending IP is blocked. Offenders are unblocked after a set interval.
+
+```{cfgcmd} set service ssh dynamic-protection
+
+Allow ``ssh`` dynamic-protection.
+```
+```{cfgcmd} set service ssh dynamic-protection allow-from \<address | prefix\>
+
+Whitelist of addresses and networks. Always allow inbound connections from
+these systems.
+```
+```{cfgcmd} set service ssh dynamic-protection block-time \<sec\>
+
+Block source IP in seconds. Subsequent blocks increase by a factor of 1.5
+The default is 120.
+```
+```{cfgcmd} set service ssh dynamic-protection detect-time \<sec\>
+
+Remember source IP in seconds before reset their score. The default is 1800.
+```
+```{cfgcmd} set service ssh dynamic-protection threshold \<sec\>
+
+Block source IP when their cumulative attack score exceeds threshold. The
+default is 30.
+```
+
+(ssh-operation)=
+
+## Operation
+
+```{opcmd} restart ssh
+
+Restart the SSH daemon process, the current session is not affected, only the
+background daemon is restarted.
+```
+```{opcmd} generate ssh server-key
+
+Re-generated the public/private keyportion which SSH uses to secure
+connections.
+
+:::{note}
+Already learned known_hosts files of clients need an update as the
+public key will change.
+:::
+```
+```{opcmd} generate ssh client-key /path/to/private_key
+
+Re-generated a known pub/private keyfile which can be used to connect to
+other services (e.g. RPKI cache).
+
+Example:
+
+:::{code-block} none
+vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki
+Generating public/private rsa key pair.
+Your identification has been saved in /config/auth/id_rsa_rpki.
+Your public key has been saved in /config/auth/id_rsa_rpki.pub.
+The key fingerprint is:
+SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos
+The key's randomart image is:
++---[RSA 2048]----+
+|         oo      |
+|          ..o    |
+|       . o.o.. o.|
+|       o+ooo  o.o|
+|        Eo*  =.o |
+|       o = +.o*+ |
+|        = o *.o.o|
+|       o * +.o+.+|
+|        =.. o=.oo|
++----[SHA256]-----+
+:::
+Two new files ``/config/auth/id_rsa_rpki`` and
+``/config/auth/id_rsa_rpki.pub``
+will be created.
+```
+```{opcmd} generate public-key-command user \<username\> path \<location\>
+
+> Generate the configuration mode commands to add a public key for
+> {ref}`ssh_key_based_authentication`.
+> ``<location>`` can be a local path or a URL pointing at a remote file.
+>
+> Supported remote protocols are FTP, FTPS, HTTP, HTTPS, SCP/SFTP and TFTP.
+
+Example:
+
+:::{code-block} none
+alyssa@vyos:~$ generate public-key-command user alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub
+# To add this key as an embedded key, run the following commands:
+configure
+set system login user alyssa authentication public-keys alyssa@example.net key AAA...
+set system login user alyssa authentication public-keys alyssa@example.net type ssh-rsa
+commit
+save
+exit
+
+ben@vyos:~$ generate public-key-command user ben path ~/.ssh/id_rsa.pub
+# To add this key as an embedded key, run the following commands:
+configure
+set system login user ben authentication public-keys ben@vyos key AAA...
+set system login user ben authentication public-keys ben@vyos type ssh-dss
+commit
+save
+exit
+:::
+```
+```{opcmd} show log ssh
+
+Show SSH server log.
+```
+```{opcmd} monitor log ssh
+
+Follow the SSH server log.
+```
+```{opcmd} show log ssh dynamic-protection
+
+Show SSH dynamic-protection log.
+```
+```{opcmd} monitor log ssh dynamic-protection
+
+Follow the SSH dynamic-protection log.
+```
+```{opcmd} show ssh dynamic-protection
+
+Show list of IPs currently blocked by SSH dynamic-protection.
+```
+```{opcmd} show ssh fingerprints
+
+Show SSH server public key fingerprints.
+```
+```{opcmd} show ssh fingerprints ascii
+
+Show SSH server public key fingerprints, including a visual ASCII art representation.
+```
\ No newline at end of file