From 998a804be02dba6c6f09989bb2fbb35e6bf13e02 Mon Sep 17 00:00:00 2001 From: Tang Zaozao Date: Thu, 16 Apr 2026 16:17:20 +0800 Subject: [PATCH] docs: add SSH troubleshooting section for issue #1268 Add comprehensive SSH troubleshooting guide covering: - SSH service status verification - Network connectivity checks - Firewall (nftables/iptables) diagnostics - Password authentication configuration - Common error messages and solutions - Windows SSH client troubleshooting - Public key permission troubleshooting - SSH configuration reset with safety warning - GitHub Issue guidance Addresses connection failures reported in issue #1268. --- .../radxa-os/system-config/_ssh_remote.mdx | 195 ++++++++++++++++++ .../radxa-os/system-config/_ssh_remote.mdx | 195 ++++++++++++++++++ 2 files changed, 390 insertions(+) diff --git a/docs/common/radxa-os/system-config/_ssh_remote.mdx b/docs/common/radxa-os/system-config/_ssh_remote.mdx index fa87a4f82..628a36545 100644 --- a/docs/common/radxa-os/system-config/_ssh_remote.mdx +++ b/docs/common/radxa-os/system-config/_ssh_remote.mdx @@ -212,3 +212,198 @@ Tabby 是一款功能强大的跨平台串口调试工具，支持串口、SSH SSH 登录成功后，你就可以通过 SSH 运行命令控制系统。 + +## 故障排除 + +如果 SSH 连接失败，可按以下步骤逐一排查。 + +### 1. 确认 SSH 服务正常运行 + +在设备上执行： + + + +```bash +sudo systemctl status ssh +``` + + + +若服务未运行，执行： + + + +```bash +sudo systemctl start ssh +sudo systemctl enable ssh +``` + + + +:::tip +Debian/Ubuntu 中 `ssh` 是 `sshd` 的别名。如 `ssh` 服务名无效，可尝试 `sshd`。 +::: + +### 2. 确认网络连通性 + +在 PC 上 ping 设备 IP，确认网络可达： + + + +```bash +ping 192.168.x.x +``` + + + +若 ping 不通，请检查： +- 设备与 PC 是否在同一局域网 +- 设备 IP 地址是否正确（避免使用 `127.0.0.1`） + +### 3. 检查防火墙 + +Radxa OS 默认使用 `nftables`。执行以下命令确认端口 22 未被阻止： + + + +```bash +sudo iptables -L -n | grep -E "22|ssh" +sudo nft list ruleset 2>/dev/null | grep -E "22|ssh" +``` + + + +若防火墙规则阻塞了 SSH，可临时清除规则测试： + + + +```bash +sudo iptables -F +``` + + + +### 4. 检查密码认证配置 + +确认 SSH 服务允许密码认证： + + + +```bash +sudo grep -v "^#" /etc/ssh/sshd_config | grep PasswordAuthentication +``` + + + +预期输出为 `PasswordAuthentication yes`。若不是，编辑配置文件： + + + +```bash +sudo nano /etc/ssh/sshd_config +``` + + + +确保存在且未被注释的行： + +``` +PasswordAuthentication yes +``` + +然后重启 SSH 服务： + + + +```bash +sudo systemctl restart ssh +``` + + + +### 5. 确认用户名和密码 + +Radxa OS 默认用户名为 `radxa`，密码为 `radxa`。若密码错误，通过串口或连接显示器后重置： + + + +```bash +sudo passwd radxa +``` + + + +### 6. 检查 SSH 日志 + +查看 SSH 服务日志，获取具体错误信息： + + + +```bash +sudo journalctl -u ssh -b --no-pager | tail -30 +``` + + + +常见错误及含义： + +| 错误信息 | 可能原因 | +|----------|----------| +| `Connection refused` | SSH 服务未运行或端口 22 被阻止 | +| `Permission denied` | 密码错误或公钥认证失败 | +| `Connection timeout` | 网络不通或 IP 地址错误 | +| `No route to host` | 网络层路由不可达 | + +### 7. Windows 客户端特殊问题 + +若使用 Windows SSH 客户端遇到问题： + +1. 尝试使用 [Tabby](https://tabby.sh/)、[PuTTY](https://www.putty.org/) 或 [MobaXterm](https://mobaxterm.mobatek.net/) 替代 +2. 检查 Windows 防火墙是否阻止了 SSH 连接 +3. 确认使用的是密码认证而非仅公钥认证 + +### 8. 公钥认证失败 + +若配置了 SSH 公钥登录但失败，检查服务端权限： + + + +```bash +# .ssh 目录权限应为 700 +chmod 700 ~/.ssh + +# authorized_keys 文件权限应为 600 +chmod 600 ~/.ssh/authorized_keys +``` + + + +### 9. 重置 SSH 配置 + +:::warning +以下操作会中断当前 SSH 连接。若远程操作，请确保有串口或显示器等备用接入方式后再执行。 +::: + + + +```bash +# 备份当前配置 +sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.backup + +# 恢复默认配置 +sudo dpkg-reconfigure openssh-server + +# 重启服务 +sudo systemctl restart ssh +``` + + + +### 获取帮助 + +如问题仍未解决，请在 GitHub 提交 Issue，并提供以下信息： + +- `sudo systemctl status ssh` 输出 +- `sudo grep -v "^#" /etc/ssh/sshd_config | grep PasswordAuthentication` 输出 +- SSH 日志 `sudo journalctl -u ssh -b --no-pager | tail -30` +- 完整的连接错误信息 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_ssh_remote.mdx b/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_ssh_remote.mdx index ff14bc16a..08e324f6c 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_ssh_remote.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_ssh_remote.mdx @@ -212,3 +212,198 @@ After a successful connection, the remote interface will appear. After successfully logging in via SSH, you can run commands to control the system through the SSH connection. + +## Troubleshooting + +If SSH connection fails, follow these steps to diagnose the issue. + +### 1. Verify SSH Service is Running + +On the device, run: + + + +```bash +sudo systemctl status ssh +``` + + + +If the service is not running: + + + +```bash +sudo systemctl start ssh +sudo systemctl enable ssh +``` + + + +:::tip +On Debian/Ubuntu, `ssh` is an alias for `sshd`. If `ssh` does not work, try `sshd`. +::: + +### 2. Verify Network Connectivity + +From your PC, ping the device IP to confirm it is reachable: + + + +```bash +ping 192.168.x.x +``` + + + +If ping fails, check: +- The device and PC are on the same LAN +- The IP address is correct (avoid using `127.0.0.1`) + +### 3. Check Firewall + +Radxa OS uses `nftables` by default. Run the following to confirm port 22 is not blocked: + + + +```bash +sudo iptables -L -n | grep -E "22|ssh" +sudo nft list ruleset 2>/dev/null | grep -E "22|ssh" +``` + + + +To temporarily clear firewall rules for testing: + + + +```bash +sudo iptables -F +``` + + + +### 4. Check Password Authentication Configuration + +Confirm SSH service allows password authentication: + + + +```bash +sudo grep -v "^#" /etc/ssh/sshd_config | grep PasswordAuthentication +``` + + + +Expected output is `PasswordAuthentication yes`. If not, edit the configuration: + + + +```bash +sudo nano /etc/ssh/sshd_config +``` + + + +Ensure the following line exists and is uncommented: + +``` +PasswordAuthentication yes +``` + +Then restart the SSH service: + + + +```bash +sudo systemctl restart ssh +``` + + + +### 5. Confirm Username and Password + +Radxa OS default username is `radxa`, password is `radxa`. If the password is incorrect, reset it via serial connection or display: + + + +```bash +sudo passwd radxa +``` + + + +### 6. Check SSH Logs + +View SSH service logs for detailed error information: + + + +```bash +sudo journalctl -u ssh -b --no-pager | tail -30 +``` + + + +Common errors and their meanings: + +| Error Message | Possible Cause | +|---------------|----------------| +| `Connection refused` | SSH service not running or port 22 blocked | +| `Permission denied` | Wrong password or public key authentication failed | +| `Connection timeout` | Network unreachable or incorrect IP address | +| `No route to host` | Network layer routing unreachable | + +### 7. Windows SSH Client Issues + +If using a Windows SSH client and encountering problems: + +1. Try [Tabby](https://tabby.sh/), [PuTTY](https://www.putty.org/), or [MobaXterm](https://mobaxterm.mobatek.net/) as alternatives +2. Check Windows Firewall is not blocking SSH connections +3. Confirm password authentication is enabled (not public-key-only) + +### 8. Public Key Authentication Fails + +If you configured SSH public key login but it fails, check server-side permissions: + + + +```bash +# .ssh directory permissions should be 700 +chmod 700 ~/.ssh + +# authorized_keys file permissions should be 600 +chmod 600 ~/.ssh/authorized_keys +``` + + + +### 9. Reset SSH Configuration + +:::warning +The following operations will interrupt your current SSH connection. If you are accessing remotely, ensure you have an alternative access method (such as serial connection) before proceeding. +::: + + + +```bash +# Backup current configuration +sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.backup + +# Restore default configuration +sudo dpkg-reconfigure openssh-server + +# Restart service +sudo systemctl restart ssh +``` + + + +### Get Help + +If the issue persists, please submit a GitHub Issue with the following information: + +- Output of `sudo systemctl status ssh` +- Output of `sudo grep -v "^#" /etc/ssh/sshd_config | grep PasswordAuthentication` +- SSH logs: `sudo journalctl -u ssh -b --no-pager | tail -30` +- Complete error message when attempting to connect