From fa54a080fac977157454beb0853daf0ac0e6af66 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sat, 2 May 2026 17:25:47 +0300 Subject: feat(swap): import .md files and webp transition from myst/current MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Selective import from origin/myst/current (cf9c9b34): - Add/update 255 .md files (full MyST conversion plus webp ref updates) - Delete 175 PNG/JPG from docs/_static/images (webp twins already present) - Delete 5 autotest topology.png (webp twins already present) Preserved on swap (untouched): - All .rst files (incremental swap pattern) - conf.py, _ext/, _include/*.txt, .gitignore - 115 canary md-*.md files - 7 superpowers/specs/*.md design docs - Logos vyos-logo.png / vyos-logo-icon.png (referenced by conf.py) 🤖 Generated by [robots](https://vyos.io) --- docs/configuration/service/ssh.md | 366 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 366 insertions(+) create mode 100644 docs/configuration/service/ssh.md (limited to 'docs/configuration/service/ssh.md') 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 \ + +Enabling SSH only requires you to specify the port ```` you want SSH to +listen on. By default, SSH runs on port 22. +``` + + +```{cfgcmd} set service ssh listen-address \ + +Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be +defined. +``` + + +```{cfgcmd} set service ssh 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 '' +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 \ + +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 \ \ \ + +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 \ + +Specify timeout interval for keepalive message in seconds. +``` + + +```{cfgcmd} set service ssh key-exchange \ + +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 \ + +Set the ``sshd`` log level. The default is ``info``. +``` + + +```{cfgcmd} set service ssh vrf \ + +Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + + +```{cfgcmd} set service ssh pubkey-accepted-algorithm \ + +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 \ + +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 \
+ +Whitelist of addresses and networks. Always allow inbound connections from +these systems. +``` +```{cfgcmd} set service ssh dynamic-protection block-time \ + +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 \ + +Remember source IP in seconds before reset their score. The default is 1800. +``` +```{cfgcmd} set service ssh dynamic-protection threshold \ + +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 \ path \ + +> Generate the configuration mode commands to add a public key for +> {ref}`ssh_key_based_authentication`. +> ```` 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 -- cgit v1.2.3