ssh: More on connection muxing

Author: iBug

docs/dev/ssh.md

@@ -205,7 +205,7 @@ Host realhost
 
 ### 高级功能：连接复用 {#connection-reuse}
 
-SSH 协议允许在一条连接内运行多个 channel，其中每个 channel 可以是一个 shell session、端口转发、scp 命令等。OpenSSH 支持连接复用，即一个 SSH 进程在后台保持连接，其他客户端在连接同一个主机时可以复用这个连接，而不需要重新握手认证等，可以显著减少连接时间。这在频繁连接同一个主机时非常有用，尤其是当主机的延迟较大、常用操作所需的 RTT 较多时（例如从 GitHub 拉取仓库，或者前文所述的跳板机使用方式）。
+SSH 协议允许在一条连接内运行多个 channel，其中每个 channel 可以是一个 shell session、端口转发、scp 命令等。OpenSSH 支持连接复用，即一个 SSH 进程在后台保持连接（称为 master 进程），其他客户端在连接同一个主机时可以复用这个连接，而不需要重新握手认证等，可以显著减少连接时间。这在频繁连接同一个主机时非常有用，尤其是当主机的延迟较大、常用操作所需的 RTT 较多时（例如从 GitHub 拉取仓库，或者前文所述的跳板机使用方式）。
 
 启用连接复用需要在配置文件中同时指定 `ControlMaster`、`ControlPath` 和 `ControlPersist` 三个选项（它们的默认值都是禁用或者很不友好的值）：
 
@@ -217,8 +217,32 @@ Host *
 ```
 
 其中 `%C` 是 `%l%h%p%r` 的 hash，因此连接不同主机的 control socket 不会冲突。
-**但是**如果你尝试用相同的用户名和不同的公钥连接同一个目标（例如 `git@github.com`），由于没有新建连接的过程，你指定的公钥并不会生效。
-解决此问题的方法是再单独指定另一个 `ControlPath`，或者设置 `ControlPath=none` 暂时禁用连接复用功能。
+
+!!! bug "连接复用的标识符"
+
+    如果你尝试用相同的用户名和不同的公钥连接同一个目标（例如 `git@github.com`），由于没有新建连接的过程，你指定的公钥并不会生效。
+    解决此问题的方法是再单独指定另一个 `ControlPath`，或者设置 `ControlPath=none` 暂时禁用连接复用功能。
+
+!!! bug "连接复用时的端口转发"
+
+    当启用连接复用时，所有的端口转发等 SSH 连接特性都将由 master 进程管理，此时新的 `ssh <host> -L <forwarding>` 会将一个新的端口转发请求发送给 master 进程，并在当前 ssh 命令结束后持续转发。
+
+    例如：
+
+    ```shell
+    ssh host # do something
+    ssh host -L <forwarding_1>
+    ssh host -R <forwarding_2>
+    ```
+
+    在以上所有 ssh 命令都退出后，`forwarding_1` 和 `forwarding_2` 将仍然在后台持续进行端口转发。
+
+    若要停止这些端口转发，可以使用 [`~C` 命令](#escape-sequences)或 `-O` 指令（见下）使后台的 master 进程停止进行端口转发。
+
+启用连接复用后，可以通过 `ssh <host> -O <command>` 的方式向后台监听新连接的 master 进程发送一些控制指令，例如：
+
+- `ssh host -O exit` 可以使 master 进程退出，后续的 `ssh host` 命令将重新建立连接。
+- `ssh host -O cancel` 可以在保持的后台连接中取消所有的端口转发。
 
 ## 文件传输 {#file-transfer}
 
@@ -566,11 +590,17 @@ SSH 连接由本地的 ssh 客户端发起，建立连接后，你在终端输
 - `~.`：立刻断开当前 SSH 连接。在命令行输入回车后，直接输入 `~.`，无需等待远端响应，适用于远端卡死或网络异常时强制断开。
 - `~^Z`：挂起 SSH 客户端（发送 SIGTSTP），回到本地 shell，可以用 `fg` 恢复 SSH 会话。回车后输入 `~`，再按下 `Ctrl+Z`。
 - `~C`：打开 SSH 客户端的命令行，可以用 `-L` `-R` `-D` 参数配置端口转发。`-KL` `-KR` `-KD` 参数关闭端口转发。
+
+    !!! warning
+
+        OpenSSH 9.2 新增了 `EnableEscapeCommandline` 设置项，且默认为 no。如果需要使用 `~C` 命令行，需要先启用该设置项。OpenSSH &le; 9.1 的版本默认允许 `~C`。
+
 - `~#`：列出当前所有转发的连接（如端口转发、X11 转发等），便于排查端口转发问题。
 - `~?`：显示所有可用的转义序列及其说明，遇到不确定的情况可以先用这个命令查看帮助。
 
 如果开启了[连接复用](#connection-reuse)功能，那么一部分转义序列无法使用，例如 `~^Z` 和 `~C` 等。
 
 !!! note "注意事项"
-    - 转义序列必须在新的一行输入（即前面不能有其他字符），否则会被当作普通输入传给远端。
-    - 在多层 SSH 跳板（多次 ssh 嵌套）时，每多一层，需要多输入一个 ~，例如 `~~.` 指令会断开第二层的 SSH 连接。
+
+    - 转义序列必须在按下回车后立即输入（即当前行前面不能有其他字符），否则会被当作普通输入传给远端。
+    - 在多层 SSH 跳板（多次 ssh 嵌套）时，每多一层，需要输入的 `~` 会翻倍。例如，`~~.` 指令会断开第二层的 SSH 连接，而 `~~~~.` 指令会断开第三层的 SSH 连接。

docs/ops/network-service/intranet.md

@@ -1,3 +1,7 @@
+---
+icon: material/tunnel-outline
+---
+
 # 隧道组网
 
 !!! note "主要作者"