From 582f98d18c72f49c8b262acd271ed0383bcab3f4 Mon Sep 17 00:00:00 2001
From: hwdsl2 <hwdsl2@users.noreply.github.com>
Date: Fri, 23 Nov 2018 11:52:38 -0600
Subject: [PATCH] Update docs

---
 docs/ikev2-howto-zh.md  | 36 ++++++++++++++++++++----------------
 docs/ikev2-howto.md     | 36 ++++++++++++++++++++----------------
 docs/manage-users-zh.md | 29 ++++++++++++++++-------------
 docs/manage-users.md    | 23 +++++++++++++----------
 4 files changed, 69 insertions(+), 55 deletions(-)

diff --git a/docs/ikev2-howto-zh.md b/docs/ikev2-howto-zh.md
index 5eaaddc..3273e8a 100644
--- a/docs/ikev2-howto-zh.md
+++ b/docs/ikev2-howto-zh.md
@@ -24,17 +24,19 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
 1. 获取 VPN 服务器的公共 IP 地址，将它保存到变量并检查。
 
    ```bash
-   $ PUBLIC_IP=$(wget -t 3 -T 15 -qO- http://ipv4.icanhazip.com)
-   $ printf '%s\n' "$PUBLIC_IP"
-   （检查显示的公共 IP）
+   PUBLIC_IP=$(dig @resolver1.opendns.com -t A -4 myip.opendns.com +short)
+   [ -z "$PUBLIC_IP" ] && PUBLIC_IP=$(wget -t 3 -T 15 -qO- http://ipv4.icanhazip.com)
+   printf '%s\n' "$PUBLIC_IP"
    ```
 
+   检查并确保以上命令的输出与服务器的公共 IP 一致。该变量将在以下步骤中使用。
+
    **注：** 另外，在这里你也可以指定 VPN 服务器的域名。例如： `PUBLIC_IP=myvpn.example.com`。
 
 1. 在 `/etc/ipsec.conf` 文件中添加一个新的 IKEv2 连接：
 
    ```bash
-   $ cat >> /etc/ipsec.conf <<EOF
+   cat >> /etc/ipsec.conf <<EOF
 
    conn ikev2-cp
      left=%defaultroute
@@ -65,13 +67,13 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
    还需要在该文件中添加一些行。首先查看你的 Libreswan 版本，然后运行以下命令之一：
 
    ```bash
-   $ ipsec --version
+   ipsec --version
    ```
 
    如果是 Libreswan 3.23 或更新版本：
 
    ```bash
-   $ cat >> /etc/ipsec.conf <<EOF
+   cat >> /etc/ipsec.conf <<EOF
      modecfgdns="8.8.8.8, 8.8.4.4"
      encapsulation=yes
      mobike=no
@@ -83,7 +85,7 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
    如果是 Libreswan 3.19-3.22：
 
    ```bash
-   $ cat >> /etc/ipsec.conf <<EOF
+   cat >> /etc/ipsec.conf <<EOF
      modecfgdns1=8.8.8.8
      modecfgdns2=8.8.4.4
      encapsulation=yes
@@ -93,7 +95,7 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
    如果是 Libreswan 3.18 或更早版本：
 
    ```bash
-   $ cat >> /etc/ipsec.conf <<EOF
+   cat >> /etc/ipsec.conf <<EOF
      modecfgdns1=8.8.8.8
      modecfgdns2=8.8.4.4
      forceencaps=yes
@@ -105,7 +107,7 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
    **注：** 使用 "-v" 参数指定证书的有效期（单位：月），例如 "-v 36"。
 
    ```bash
-   $ certutil -z <(head -c 1024 /dev/urandom) \
+   certutil -z <(head -c 1024 /dev/urandom) \
      -S -x -n "IKEv2 VPN CA" \
      -s "O=IKEv2 VPN,CN=IKEv2 VPN CA" \
      -k rsa -g 4096 -v 36 \
@@ -125,7 +127,7 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
    **注：** 如果你在上面的第一步指定了服务器的域名（而不是 IP 地址），则必须将以下命令中的 `--extSAN "ip:$PUBLIC_IP,dns:$PUBLIC_IP"` 换成 `--extSAN "dns:$PUBLIC_IP"`。
 
    ```bash
-   $ certutil -z <(head -c 1024 /dev/urandom) \
+   certutil -z <(head -c 1024 /dev/urandom) \
      -S -c "IKEv2 VPN CA" -n "$PUBLIC_IP" \
      -s "O=IKEv2 VPN,CN=$PUBLIC_IP" \
      -k rsa -g 4096 -v 36 \
@@ -142,7 +144,7 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
 1. 生成客户端证书，然后导出 `.p12` 文件，该文件包含客户端证书，私钥以及 CA 证书：
 
    ```bash
-   $ certutil -z <(head -c 1024 /dev/urandom) \
+   certutil -z <(head -c 1024 /dev/urandom) \
      -S -c "IKEv2 VPN CA" -n "vpnclient" \
      -s "O=IKEv2 VPN,CN=vpnclient" \
      -k rsa -g 4096 -v 36 \
@@ -156,7 +158,7 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
    ```
 
    ```bash
-   $ pk12util -o vpnclient.p12 -n "vpnclient" -d sql:/etc/ipsec.d
+   pk12util -o vpnclient.p12 -n "vpnclient" -d sql:/etc/ipsec.d
    ```
 
    ```
@@ -172,13 +174,13 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
 1. （适用于 macOS 和 iOS 客户端） 导出 CA 证书到 `vpnca.cer`：
 
    ```bash
-   $ certutil -L -d sql:/etc/ipsec.d -n "IKEv2 VPN CA" -a -o vpnca.cer
+   certutil -L -d sql:/etc/ipsec.d -n "IKEv2 VPN CA" -a -o vpnca.cer
    ```
 
 1. 证书数据库现在应该包含以下内容：
 
    ```bash
-   $ certutil -L -d sql:/etc/ipsec.d
+   certutil -L -d sql:/etc/ipsec.d
    ```
 
    ```
@@ -195,10 +197,12 @@ Libreswan 支持通过使用 RSA 签名算法的 X.509 Machine Certificates 来
 1. **（重要）重启 IPsec 服务**：
 
    ```bash
-   $ service ipsec restart
+   service ipsec restart
    ```
 
-1. 按照下面你的操作系统对应的步骤操作。**注：** 如果你在上面的第一步指定了服务器的域名（而不是 IP 地址），则必须在 **服务器地址** 和 **远程 ID** 字段中输入该域名。
+1. 按照下面你的操作系统对应的步骤操作。
+
+   **注：** 如果你在上面的第一步指定了服务器的域名（而不是 IP 地址），则必须在 **服务器地址** 和 **远程 ID** 字段中输入该域名。
 
    #### Windows 7, 8.x 和 10
 
diff --git a/docs/ikev2-howto.md b/docs/ikev2-howto.md
index 8f77c6e..5bb91d9 100644
--- a/docs/ikev2-howto.md
+++ b/docs/ikev2-howto.md
@@ -24,17 +24,19 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
 1. Find the VPN server's public IP, save it to a variable and check.
 
    ```bash
-   $ PUBLIC_IP=$(wget -t 3 -T 15 -qO- http://ipv4.icanhazip.com)
-   $ printf '%s\n' "$PUBLIC_IP"
-   (Check the displayed public IP)
+   PUBLIC_IP=$(dig @resolver1.opendns.com -t A -4 myip.opendns.com +short)
+   [ -z "$PUBLIC_IP" ] && PUBLIC_IP=$(wget -t 3 -T 15 -qO- http://ipv4.icanhazip.com)
+   printf '%s\n' "$PUBLIC_IP"
    ```
 
+   Check to make sure the output matches the server's public IP. This variable is required in the steps below.
+
    **Note:** Alternatively, you may specify the server's DNS name here. e.g. `PUBLIC_IP=myvpn.example.com`.
 
 1. Add a new IKEv2 connection to `/etc/ipsec.conf`:
 
    ```bash
-   $ cat >> /etc/ipsec.conf <<EOF
+   cat >> /etc/ipsec.conf <<EOF
 
    conn ikev2-cp
      left=%defaultroute
@@ -65,13 +67,13 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
    We need to add a few more lines to that file. First check your Libreswan version, then run one of the following commands:
 
    ```bash
-   $ ipsec --version
+   ipsec --version
    ```
 
    For Libreswan 3.23 and newer:
 
    ```bash
-   $ cat >> /etc/ipsec.conf <<EOF
+   cat >> /etc/ipsec.conf <<EOF
      modecfgdns="8.8.8.8, 8.8.4.4"
      encapsulation=yes
      mobike=no
@@ -83,7 +85,7 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
    For Libreswan 3.19-3.22:
 
    ```bash
-   $ cat >> /etc/ipsec.conf <<EOF
+   cat >> /etc/ipsec.conf <<EOF
      modecfgdns1=8.8.8.8
      modecfgdns2=8.8.4.4
      encapsulation=yes
@@ -93,7 +95,7 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
    For Libreswan 3.18 and older:
 
    ```bash
-   $ cat >> /etc/ipsec.conf <<EOF
+   cat >> /etc/ipsec.conf <<EOF
      modecfgdns1=8.8.8.8
      modecfgdns2=8.8.4.4
      forceencaps=yes
@@ -105,7 +107,7 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
    **Note:** Specify the certificate validity period (in months) with "-v". e.g. "-v 36".
 
    ```bash
-   $ certutil -z <(head -c 1024 /dev/urandom) \
+   certutil -z <(head -c 1024 /dev/urandom) \
      -S -x -n "IKEv2 VPN CA" \
      -s "O=IKEv2 VPN,CN=IKEv2 VPN CA" \
      -k rsa -g 4096 -v 36 \
@@ -125,7 +127,7 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
    **Note:** If you specified the server's DNS name (instead of its IP address) in step 1 above, you must replace `--extSAN "ip:$PUBLIC_IP,dns:$PUBLIC_IP"` in the command below with `--extSAN "dns:$PUBLIC_IP"`.
 
    ```bash
-   $ certutil -z <(head -c 1024 /dev/urandom) \
+   certutil -z <(head -c 1024 /dev/urandom) \
      -S -c "IKEv2 VPN CA" -n "$PUBLIC_IP" \
      -s "O=IKEv2 VPN,CN=$PUBLIC_IP" \
      -k rsa -g 4096 -v 36 \
@@ -142,7 +144,7 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
 1. Generate client certificate(s), then export the `.p12` file that contains the client certificate, private key, and CA certificate:
 
    ```bash
-   $ certutil -z <(head -c 1024 /dev/urandom) \
+   certutil -z <(head -c 1024 /dev/urandom) \
      -S -c "IKEv2 VPN CA" -n "vpnclient" \
      -s "O=IKEv2 VPN,CN=vpnclient" \
      -k rsa -g 4096 -v 36 \
@@ -156,7 +158,7 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
    ```
 
    ```bash
-   $ pk12util -o vpnclient.p12 -n "vpnclient" -d sql:/etc/ipsec.d
+   pk12util -o vpnclient.p12 -n "vpnclient" -d sql:/etc/ipsec.d
    ```
 
    ```
@@ -172,13 +174,13 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
 1. (For macOS and iOS clients) Export the CA certificate as `vpnca.cer`:
 
    ```bash
-   $ certutil -L -d sql:/etc/ipsec.d -n "IKEv2 VPN CA" -a -o vpnca.cer
+   certutil -L -d sql:/etc/ipsec.d -n "IKEv2 VPN CA" -a -o vpnca.cer
    ```
 
 1. The database should now contain:
 
    ```bash
-   $ certutil -L -d sql:/etc/ipsec.d
+   certutil -L -d sql:/etc/ipsec.d
    ```
 
    ```
@@ -195,10 +197,12 @@ Before continuing, make sure you have successfully <a href="https://github.com/h
 1. **(Important) Restart IPsec service**:
 
    ```bash
-   $ service ipsec restart
+   service ipsec restart
    ```
 
-1. Follow instructions below for your operating system. **Note:** If you specified the server's DNS name (instead of its IP address) in step 1 above, you must enter the DNS name in the **Server** and **Remote ID** fields.
+1. Follow instructions below for your operating system.
+
+   **Note:** If you specified the server's DNS name (instead of its IP address) in step 1 above, you must enter the DNS name in the **Server** and **Remote ID** fields.
 
    #### Windows 7, 8.x and 10
 
diff --git a/docs/manage-users-zh.md b/docs/manage-users-zh.md
index ec32cb9..3a8c406 100644
--- a/docs/manage-users-zh.md
+++ b/docs/manage-users-zh.md
@@ -6,11 +6,13 @@
 
 ## 使用辅助脚本
 
-你可以使用这些脚本来更方便地管理 VPN 用户：[add_vpn_user.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/add_vpn_user.sh), [del_vpn_user.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/del_vpn_user.sh) 和 [update_vpn_users.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/update_vpn_users.sh)。它们将同时更新 IPsec/L2TP 和 IPsec/XAuth (Cisco IPsec) 模式的用户。如果你需要更新 IPsec PSK，请阅读下一节。
+你可以使用这些脚本来更方便地管理 VPN 用户：[add_vpn_user.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/add_vpn_user.sh), [del_vpn_user.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/del_vpn_user.sh) 和 [update_vpn_users.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/update_vpn_users.sh)。它们将同时更新 IPsec/L2TP 和 IPsec/XAuth (Cisco IPsec) 模式的用户。如果你需要更改 IPsec PSK，请阅读下一节。
 
-### 添加或者更新一个 VPN 用户
+**注：** VPN 用户信息保存在文件 `/etc/ppp/chap-secrets` 和 `/etc/ipsec.d/passwd`。脚本在修改这些文件之前会先做备份，使用 `.old-日期-时间` 为后缀。
 
-添加一个新 VPN 用户，或者为一个已有的 VPN 用户更新密码。
+### 添加或更改一个 VPN 用户
+
+添加一个新 VPN 用户，或者为一个已有的 VPN 用户更改密码。
 
 ```bash
 # 下载脚本
@@ -73,7 +75,7 @@ sh update_vpn_users.sh
 
 ## 手动管理 VPN 用户和 PSK
 
-首先，IPsec PSK (预共享密钥) 保存在文件 `/etc/ipsec.secrets` 中。如果要更换一个新的 PSK，可以编辑此文件。完成后必须重启服务（见下面）。所有的 VPN 用户将共享同一个 IPsec PSK。
+首先，IPsec PSK （预共享密钥）保存在文件 `/etc/ipsec.secrets`。如果要更换一个新的 PSK，可以编辑此文件。完成后必须重启服务（见下面）。所有的 VPN 用户将共享同一个 IPsec PSK。
 
 ```bash
 %any  %any  : PSK "你的IPsec预共享密钥"
@@ -82,29 +84,30 @@ sh update_vpn_users.sh
 对于 `IPsec/L2TP`，VPN 用户信息保存在文件 `/etc/ppp/chap-secrets`。该文件的格式如下：
 
 ```bash
-"你的VPN用户名1"  l2tpd  "你的VPN密码1"  *
-"你的VPN用户名2"  l2tpd  "你的VPN密码2"  *
+"用户名1"  l2tpd  "密码1"  *
+"用户名2"  l2tpd  "密码2"  *
 ... ...
 ```
 
-你可以添加更多用户，每个用户对应文件中的一行。**不要** 在用户名，密码或 PSK 中使用这些字符：`\ " '`
+你可以添加更多用户，每个用户对应文件中的一行。**不要**在用户名，密码或 PSK 中使用这些字符：`\ " '`
 
-对于 `IPsec/XAuth ("Cisco IPsec")`， VPN 用户信息保存在文件 `/etc/ipsec.d/passwd`。该文件的格式如下：
+对于 `IPsec/XAuth ("Cisco IPsec")`，VPN 用户信息保存在文件 `/etc/ipsec.d/passwd`。该文件的格式如下：
 
 ```bash
-你的VPN用户名1:你的VPN密码1的加盐哈希值:xauth-psk
-你的VPN用户名2:你的VPN密码2的加盐哈希值:xauth-psk
+用户名1:密码1的加盐哈希值:xauth-psk
+用户名2:密码2的加盐哈希值:xauth-psk
 ... ...
 ```
 
 这个文件中的密码以加盐哈希值的形式保存。该步骤可以借助比如 `openssl` 工具来完成：
 
 ```bash
-# 以下命令的输出为：你的VPN密码1的加盐哈希值
-openssl passwd -1 '你的VPN密码1'
+# 以下命令的输出为：密码1的加盐哈希值
+# 将你的密码用 '单引号' 括起来
+openssl passwd -1 '密码1'
 ```
 
-最后，如果你更换了新的 PSK，则必须重启服务。对于添加，更改或者删除 VPN 用户，一般不需重启。
+最后，如果你更改了 PSK，则必须重启服务。对于添加，更改或者删除 VPN 用户，一般不需重启。
 
 ```bash
 service ipsec restart
diff --git a/docs/manage-users.md b/docs/manage-users.md
index 409ded3..52f6e0a 100644
--- a/docs/manage-users.md
+++ b/docs/manage-users.md
@@ -6,11 +6,13 @@ By default, a single user account for VPN login is created. If you wish to add,
 
 ## Using helper scripts
 
-You may use these scripts to more easily manage VPN users: [add_vpn_user.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/add_vpn_user.sh), [del_vpn_user.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/del_vpn_user.sh) and [update_vpn_users.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/update_vpn_users.sh). They will update users for both IPsec/L2TP and IPsec/XAuth (Cisco IPsec) modes. For updating the IPsec PSK, read the next section.
+You may use these scripts to more easily manage VPN users: [add_vpn_user.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/add_vpn_user.sh), [del_vpn_user.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/del_vpn_user.sh) and [update_vpn_users.sh](https://github.com/hwdsl2/setup-ipsec-vpn/blob/master/extras/update_vpn_users.sh). They will update users for both IPsec/L2TP and IPsec/XAuth (Cisco IPsec). For changing the IPsec PSK, read the next section.
 
-### Add or update a VPN user
+**Note:** VPN users are stored in `/etc/ppp/chap-secrets` and `/etc/ipsec.d/passwd`. The scripts will backup these files before making changes, with `.old-date-time` suffix.
 
-Add a new VPN user or update an existing user with a new password.
+### Add or edit a VPN user
+
+Add a new VPN user or update an existing VPN user with a new password.
 
 ```bash
 # Download the script
@@ -82,8 +84,8 @@ First, the IPsec PSK (pre-shared key) is stored in `/etc/ipsec.secrets`. To chan
 For `IPsec/L2TP`, VPN users are specified in `/etc/ppp/chap-secrets`. The format of this file is:
 
 ```bash
-"your_vpn_username_1"  l2tpd  "your_vpn_password_1"  *
-"your_vpn_username_2"  l2tpd  "your_vpn_password_2"  *
+"username1"  l2tpd  "password1"  *
+"username2"  l2tpd  "password2"  *
 ... ...
 ```
 
@@ -92,19 +94,20 @@ You can add more users, use one line for each user. DO NOT use these special cha
 For `IPsec/XAuth ("Cisco IPsec")`, VPN users are specified in `/etc/ipsec.d/passwd`. The format of this file is:
 
 ```bash
-your_vpn_username_1:your_vpn_password_1_hashed:xauth-psk
-your_vpn_username_2:your_vpn_password_2_hashed:xauth-psk
+username1:password1hashed:xauth-psk
+username2:password2hashed:xauth-psk
 ... ...
 ```
 
 Passwords in this file are salted and hashed. This step can be done using e.g. the `openssl` utility:
 
 ```bash
-# The output will be your_vpn_password_1_hashed
-openssl passwd -1 'your_vpn_password_1'
+# The output will be password1hashed
+# Put your password inside 'single quotes'
+openssl passwd -1 'password1'
 ```
 
-Finally, you must restart services if changing to a new PSK. For adding, editing or removing VPN users, this is normally not required.
+Finally, you must restart services if changing the PSK. For add/edit/remove VPN users, this is normally not required.
 
 ```bash
 service ipsec restart