Update docs

- Add documentation for the static IP feature. Ref: hwdsl2#277
mutadecheng · Mar 5, 2022 · 051779e · 051779e
1 parent 87bf007
commit 051779e
Show file tree

Hide file tree

Showing 4 changed files with 66 additions and 0 deletions.
diff --git a/README-zh.md b/README-zh.md
@@ -300,6 +300,7 @@ docker exec -it ipsec-vpn-server ikev2.sh
 - [选择 VPN 模式](docs/advanced-usage-zh.md#选择-vpn-模式)
 - [访问 Docker 主机上的其它容器](docs/advanced-usage-zh.md#访问-docker-主机上的其它容器)
 - [指定 VPN 服务器的公有 IP](docs/advanced-usage-zh.md#指定-vpn-服务器的公有-ip)
+- [为 VPN 客户端指定静态 IP](docs/advanced-usage-zh.md#为-vpn-客户端指定静态-ip)
 - [关于 host network 模式](docs/advanced-usage-zh.md#关于-host-network-模式)
 - [启用 Libreswan 日志](docs/advanced-usage-zh.md#启用-libreswan-日志)
 - [查看服务器状态](docs/advanced-usage-zh.md#查看服务器状态)

diff --git a/README.md b/README.md
@@ -301,6 +301,7 @@ See [Advanced usage](docs/advanced-usage.md).
 - [Select VPN modes](docs/advanced-usage.md#select-vpn-modes)
 - [Access other containers on the Docker host](docs/advanced-usage.md#access-other-containers-on-the-docker-host)
 - [Specify VPN server's public IP](docs/advanced-usage.md#specify-vpn-servers-public-ip)
+- [Assign static IPs to VPN clients](docs/advanced-usage.md#assign-static-ips-to-vpn-clients)
 - [About host network mode](docs/advanced-usage.md#about-host-network-mode)
 - [Enable Libreswan logs](docs/advanced-usage.md#enable-libreswan-logs)
 - [Check server status](docs/advanced-usage.md#check-server-status)

diff --git a/docs/advanced-usage-zh.md b/docs/advanced-usage-zh.md
@@ -7,6 +7,7 @@
 - [选择 VPN 模式](#选择-vpn-模式)
 - [访问 Docker 主机上的其它容器](#访问-docker-主机上的其它容器)
 - [指定 VPN 服务器的公有 IP](#指定-vpn-服务器的公有-ip)
+- [为 VPN 客户端指定静态 IP](#为-vpn-客户端指定静态-ip)
 - [关于 host network 模式](#关于-host-network-模式)
 - [启用 Libreswan 日志](#启用-libreswan-日志)
 - [查看服务器状态](#查看服务器状态)
@@ -112,6 +113,37 @@ iptables -t nat -I POSTROUTING -s 172.17.0.2 ! -o docker0 -j SNAT --to 192.0.2.2
 
 要检查一个已连接的 VPN 客户端的 "出站 IP"，你可以在该客户端上打开浏览器并到 [这里](https://www.ipchicken.com) 检测 IP 地址。
 
+## 为 VPN 客户端指定静态 IP
+
+在使用 IPsec/L2TP 模式连接时，VPN 服务器（Docker 容器）在虚拟网络 `192.168.42.0/24` 内具有内网 IP `192.168.42.1`。为客户端分配的内网 IP 在这个范围内：`192.168.42.10` 到 `192.168.42.250`。要找到为特定的客户端分配的 IP，可以查看该 VPN 客户端上的连接状态。
+
+在使用 IPsec/XAuth ("Cisco IPsec") 或 IKEv2 模式连接时，VPN 服务器（Docker 容器）在虚拟网络 `192.168.43.0/24` 内 **没有** 内网 IP。为客户端分配的内网 IP 在这个范围内：`192.168.43.10` 到 `192.168.43.250`。
+
+高级用户可以将静态 IP 分配给 VPN 客户端。这是可选的。IKEv2 模式 **不支持** 此功能。要分配静态 IP，在你的 `env` 文件中定义 `VPN_ADDL_IP_ADDRS` 变量，然后重新创建 Docker 容器。例如：
+
+```
+VPN_ADDL_USERS=user1 user2 user3 user4 user5
+VPN_ADDL_PASSWORDS=pass1 pass2 pass3 pass4 pass5
+VPN_ADDL_IP_ADDRS=* * 192.168.42.2 192.168.43.2
+```
+
+在此示例中，我们为 IPsec/L2TP 模式的 `user3` 分配静态 IP `192.168.42.2`，并为 IPsec/XAuth ("Cisco IPsec") 模式的 `user4` 分配静态 IP `192.168.43.2`。`user1`, `user2` 和 `user5` 的内网 IP 将被自动分配。`user3` 在 IPsec/XAuth 模式下的内网 IP 和 `user4` 在 IPsec/L2TP 模式下的内网 IP 也将被自动分配。你可以使用 `*` 来指定自动分配的 IP，或者将这些用户放在列表的末尾。
+
+你为 IPsec/L2TP 模式指定的静态 IP 必须在 `192.168.42.2` 到 `192.168.42.9` 范围内。你为 IPsec/XAuth ("Cisco IPsec") 模式指定的静态 IP 必须在 `192.168.43.2` 到 `192.168.43.9` 范围内。
+
+如果你需要分配更多静态 IP，则必须缩小自动分配的 IP 地址池。示例如下：
+
+```
+VPN_L2TP_POOL=192.168.42.100-192.168.42.250
+VPN_XAUTH_POOL=192.168.43.100-192.168.43.250
+```
+
+这将允许你为 IPsec/L2TP 模式在 `192.168.42.2` 到 `192.168.42.99` 范围内分配静态 IP，并且为 IPsec/XAuth ("Cisco IPsec") 模式在 `192.168.43.2` 到 `192.168.43.99` 范围内分配静态 IP。
+
+请注意，如果你在 `env` 文件中指定了 `VPN_XAUTH_POOL`，并且在 Docker 容器中已经配置了 IKEv2，你 **必须** 在重新创建 Docker 容器之前手动编辑容器内的 `/etc/ipsec.d/ikev2.conf` 并将 `rightaddresspool=192.168.43.10-192.168.43.250` 替换为与 `VPN_XAUTH_POOL` **相同的值**。否则 IKEv2 可能会停止工作。
+
+**注：** 在你的 `env` 文件中，**不要**为变量值添加 `""` 或者 `''`，或在 `=` 两边添加空格。**不要**在值中使用这些字符： `\ " '`。
+
 ## 关于 host network 模式
 
 高级用户可以使用 [host network 模式](https://docs.docker.com/network/host/) 运行本镜像，通过为 `docker run` 命令添加 `--network=host` 参数来实现。另外，如果 [不启用 privileged 模式运行](#不启用-privileged-模式运行)，你可能还需要将 `eth0` 替换为你的 Docker 主机的网络接口名称。

diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md
@@ -7,6 +7,7 @@
 - [Select VPN modes](#select-vpn-modes)
 - [Access other containers on the Docker host](#access-other-containers-on-the-docker-host)
 - [Specify VPN server's public IP](#specify-vpn-servers-public-ip)
+- [Assign static IPs to VPN clients](#assign-static-ips-to-vpn-clients)
 - [About host network mode](#about-host-network-mode)
 - [Enable Libreswan logs](#enable-libreswan-logs)
 - [Check server status](#check-server-status)
@@ -112,6 +113,37 @@ iptables -t nat -I POSTROUTING -s 172.17.0.2 ! -o docker0 -j SNAT --to 192.0.2.2
 
 To check the "outgoing IP" for a connected VPN client, you may open a browser on the client and [look up the IP address on Google](https://www.google.com/search?q=my+ip).
 
+## Assign static IPs to VPN clients
+
+When connecting using IPsec/L2TP mode, the VPN server (Docker container) has internal IP `192.168.42.1` within the VPN subnet `192.168.42.0/24`. Clients are assigned internal IPs from `192.168.42.10` to `192.168.42.250`. To check which IP is assigned to a client, view the connection status on the VPN client.
+
+When connecting using IPsec/XAuth ("Cisco IPsec") or IKEv2 mode, the VPN server (Docker container) does NOT have an internal IP within the VPN subnet `192.168.43.0/24`. Clients are assigned internal IPs from `192.168.43.10` to `192.168.43.250`.
+
+Advanced users may optionally assign static IPs to VPN clients. IKEv2 mode does NOT support this feature. To assign static IPs, declare the `VPN_ADDL_IP_ADDRS` variable in your `env` file, then re-create the Docker container. Example:
+
+```
+VPN_ADDL_USERS=user1 user2 user3 user4 user5
+VPN_ADDL_PASSWORDS=pass1 pass2 pass3 pass4 pass5
+VPN_ADDL_IP_ADDRS=* * 192.168.42.2 192.168.43.2
+```
+
+In this example, we assign static IP `192.168.42.2` for `user3` for IPsec/L2TP mode, and assign static IP `192.168.43.2` for `user4` for IPsec/XAuth ("Cisco IPsec") mode. Internal IPs for `user1`, `user2` and `user5` will be auto-assigned. The internal IP for `user3` for IPsec/XAuth mode and the internal IP for `user4` for IPsec/L2TP mode will also be auto-assigned. You may use `*` to specify auto-assigned IPs, or put those user(s) at the end of the list.
+
+Static IPs that you specify for IPsec/L2TP mode must be within the range from `192.168.42.2` to `192.168.42.9`. Static IPs that you specify for IPsec/XAuth ("Cisco IPsec") mode must be within the range from `192.168.43.2` to `192.168.43.9`.
+
+If you need to assign more static IPs, you must shrink the pool of auto-assigned IP addresses. Example:
+
+```
+VPN_L2TP_POOL=192.168.42.100-192.168.42.250
+VPN_XAUTH_POOL=192.168.43.100-192.168.43.250
+```
+
+This will allow you to assign static IPs within the range from `192.168.42.2` to `192.168.42.99` for IPsec/L2TP mode, and within the range from `192.168.43.2` to `192.168.43.99` for IPsec/XAuth ("Cisco IPsec") mode.
+
+Note that if you specify `VPN_XAUTH_POOL` in the `env` file, and IKEv2 is already set up in the Docker container, you **must** manually edit `/etc/ipsec.d/ikev2.conf` inside the container and replace `rightaddresspool=192.168.43.10-192.168.43.250` with the **same value** as `VPN_XAUTH_POOL`, before re-creating the Docker container. Otherwise, IKEv2 may stop working.
+
+**Note:** In your `env` file, DO NOT put `""` or `''` around values, or add space around `=`. DO NOT use these special characters within values: `\ " '`.
+
 ## About host network mode
 
 Advanced users can run this image in [host network mode](https://docs.docker.com/network/host/), by adding `--network=host` to the `docker run` command. In addition, if [running without privileged mode](#run-without-privileged-mode), you may also need to replace `eth0` with the network interface name of your Docker host.