update documents: add config details.

ConfigFileDetails-zhCN.md

@@ -0,0 +1,41 @@
+# BTCAgent 配置文件详解
+
+## 所有选项
+
+```json
+{
+    "agent_type": "btc",
+    "always_keep_downconn": false,
+    "disconnect_when_lost_asicboost": true,
+    "use_ip_as_worker_name": false,
+    "ip_worker_name_format": "{1}x{2}x{3}x{4}",
+    "submit_response_from_server": false,
+    "agent_listen_ip": "0.0.0.0",
+    "agent_listen_port": 3333,
+    "pool_use_tls": false,
+    "use_iocp": false,
+    "fixed_worker_name": "",
+    "pools": [
+        ["us.ss.btc.com", 1800, "YourSubAccountName"],
+        ["us.ss.btc.com", 443, "YourSubAccountName"],
+        ["us.ss.btc.com", 3333, "YourSubAccountName"]
+    ]
+}
+```
+
+## 选项列表
+
+| 配置项 | 名称 | 使用说明 |
+| ----- | ---- | ----------- |
+| agent_type | 代理类型 | 保留用于未来支持其他币种，目前只能为`"btc"`。如果你手动编写配置文件，建议直接省略该选项。 |
+| always_keep_downconn | 矿池断开时向矿机发送虚假任务 | 正常情况下，如果智能代理与矿池服务器断开连接，它会停止向矿机发送任务，然后矿机收不到任务，就会切换到备用池。<br><br>但是如果您遇到外网故障，矿机也就连不上备用池，一段时间后矿机就会停止挖矿。在某些环境中，矿机突然停止挖矿可能会导致矿机损坏，或者在网络恢复正常后矿机无法自行恢复挖矿（比如因为温度太低而无法启动）。此时您就可以启用该选项。<br><br>启用该选项后，如果智能代理与矿池服务器断开连接，它不会停止向矿机发送任务，而是会产生一些虚假任务发送给矿机，这样矿机就能持续挖矿。等网络恢复后，智能代理就可以向矿机发送真实任务了。<br><br>但是请注意：虚假任务产生的算力不会提交到矿池（就算提交也只是徒增拒绝率），所以也无法产生收益。并且，如果智能代理是矿机的首选矿池，那么启用该选项也会让矿机失去切换到备用池的机会，因为在它看来，首选矿池始终是活跃的。 |
+| disconnect_when_lost_asicboost | 自动重连ASICBoost失效的矿机 | 某些支持ASICBoost的矿机，在挖矿过程中ASICBoost可能会突然失效，这会导致矿机算力降低，或者功耗上升。<br><br>启用该选项可以让智能代理自动断开这些矿机的连接，矿机会立即自动重连，并且重连后ASICBoost通常可以恢复正常。<br><br>建议始终启用该选项，因为它没有什么副作用。就算矿机不支持ASICBoost，启用该选项也不会导致任何问题。 |
+| use_ip_as_worker_name | 使用矿机IP作为矿机名 | 启用该选项可以让智能代理把矿机的IP地址作为矿机名，填写在矿机控制面板中的矿机名会被忽略。<br><br>例如，IP地址为“192.168.1.23”的矿机，矿机名就会变成“192x168x1x23”。矿机名的具体格式可以通过`ip_worker_name_format`选项设置。 |
+| ip_worker_name_format | IP地址矿机名的格式 | 设置IP地址矿机名的格式。<br><br>可用变量：<br>{1} 表示IP地址的第一段。<br>{2} 表示IP地址的第二段。<br>{3} 表示IP地址的第三段。<br>{4} 表示IP地址的第四段。<br><br>举例：<br>{1}x{2}x{3}x{4}<br>IP地址“192.168.1.23”的矿机名为“192x168x1x23”。<br><br>{2}x{3}x{4}<br>IP地址“192.168.1.23”的矿机名为“168x1x23”。<br><br>{3}x{4}<br>IP地址“192.168.1.23”的矿机名为“1x23”。 |
+| submit_response_from_server | **[高级选项]**<br>向矿机发送矿池响应 | 向矿机发送矿池服务器的真实响应。<br><br>如果该选项未启用，智能代理在收到矿机提交后会立即发送“成功”响应，这样一来，矿机控制面板的“拒绝率”就会始终为0。<br><br>如果想在矿机控制面板看到真实拒绝率，可以启用该选项。但是启用该选项可能会增加网络带宽开销以及提交延迟。 |
+| agent_listen_ip | BTCAgent监听IP | BTCAgent代理的监听IP，矿机需要通过这个IP来连接到代理。需要填写已经分配给运行代理的电脑的IP，或者填写`0.0.0.0`。建议填写`0.0.0.0`，它表示“所有可用的IP”。 |
+| agent_listen_port | BTCAgent监听端口 | BTCAgent代理的监听端口，矿机需要通过这个端口来连接到代理。如果你在同一台电脑上运行多个代理，每个代理的端口都应该不同。<br><br>可用的端口范围是1到65535，但是建议使用2000到5000范围内的端口。因为使用低于1024的端口需要root权限（管理员权限），高于5000的端口容易被其他程序随机占用。 |
+| pool_use_tls | 连接矿池时启用SSL/TLS加密 | 连接到SSL/TLS加密的矿池服务器，防止中间人进行网络窃听。<br><br>注意：支持SSL/TLS加密的矿池服务器的地址和端口与普通服务器不同，如果您填写的矿池地址端口不支持SSL/TLS加密，启用该选项会导致智能代理连不上矿池。<br><br>此外，启用该选项只会加密到矿池的连接，不会加密到矿机的连接，所以不需要修改矿机的设置。 |
+| use_iocp | **[仅限Windows]**<br>**[实验性功能]**<br>联网时启用IOCP | 让智能代理在联网时使用Windows I/O完成端口（IOCP）。<br><br>启用该选项可能可以提升智能代理的吞吐量，可以让更多矿机同时连接到同一个智能代理。<br><br>但是该选项是高度实验性的。我们的测试表明，启用该选项后智能代理的内存占用会显著增加，并且某些情况下可能会崩溃或者失去响应。<br><br>我们不建议普通用户启用该选项，除非您真的遇到吞吐量问题，并且没有其他解决方法。<br><br>如果启用了该选项，请务必给矿机配置备用矿池，以便在智能代理故障时自动切换。 |
+| fixed_worker_name | **[高级选项]**<br>使用固定矿机名 | 把所有矿机的矿机名都设为同一个值，这会模拟传统Stratum代理的行为，让矿池认为连接到BTCAgent的所有矿机都是同一台矿机。<br><br>留空（值设为`""`）或者省略该选项可以禁用这个功能。 |
+| pools | 矿池地址、端口、子账户名 | [<br>&nbsp;&nbsp;&nbsp;&nbsp;["矿池地址1", 矿池端口1, "子账户名1"],<br>&nbsp;&nbsp;&nbsp;&nbsp;["矿池地址2", 矿池端口2, "子账户名2"],<br>&nbsp;&nbsp;&nbsp;&nbsp;["矿池地址3", 矿池端口3, "子账户名3"]<br>] |

ConfigFileDetails.md

@@ -0,0 +1,41 @@
+# BTCAgent Config File Details
+
+## All Options
+
+```json
+{
+    "agent_type": "btc",
+    "always_keep_downconn": false,
+    "disconnect_when_lost_asicboost": true,
+    "use_ip_as_worker_name": false,
+    "ip_worker_name_format": "{1}x{2}x{3}x{4}",
+    "submit_response_from_server": false,
+    "agent_listen_ip": "0.0.0.0",
+    "agent_listen_port": 3333,
+    "pool_use_tls": false,
+    "use_iocp": false,
+    "fixed_worker_name": "",
+    "pools": [
+        ["us.ss.btc.com", 1800, "YourSubAccountName"],
+        ["us.ss.btc.com", 443, "YourSubAccountName"],
+        ["us.ss.btc.com", 3333, "YourSubAccountName"]
+    ]
+}
+```
+
+## Option Table
+
+| Field | Name | Description |
+| ----- | ---- | ----------- |
+| agent_type | Agent Type | Reserved for the future, currently it can only be `"btc"`. It is recommended to omit this option. |
+| always_keep_downconn | Send fake jobs when lost pool connection | Under normal circumstances, if BTCAgent suddenly lost all connections of mining pool servers, it will stop sending jobs to miners so that they can switch to their backup mining pools.<br><br>But if you experience an ISP failure, the miner will not be able to connect to backup pools. And it may suddenly stop computing. For some deployments, a sudden shutdown may cause damage to the miner or fail to return to normal after the network is recovered (because the temperature is too low). At this point, you can enable this option.<br><br>If you enable this option, BTCAgent will not stop sending jobs when disconnected from the mining pool, but will create some fake jobs and send them to your miners, which will keep them running continuously. When the BTCAgent reconnects to the mining pool, the fake job will be replaced by the real job.<br><br>But please note: fake jobs will not be submitted to the mining pool server (if submitted, server will only reject them), so they will not be paid. And if BTCAgent is a miner&apos;s preferred pool, enabling this option will also make it lose the opportunity to switch to its backup pool, because it will think that the preferred pool is always active. |
+| disconnect_when_lost_asicboost | Automatically reconnect the miner to fix ASICBoost failure | Some miners with ASICBoost enabled will accidentally disable ASICBoost during operation. This will cause their hashrate to decrease or power consumption to increase.<br><br>Enabling this option can make BTCAgent automatically disconnect from such miners. Then the miner will automatically reconnect immediately and can usually resume ASICBoost again.<br><br>It is recommended to enable this option, as it usually has no side effects. Even if a miner does not support ASICBoost, no bad things will happen if this option is enabled. |
+| use_ip_as_worker_name | Use miner's IP as its worker name | Enable this option to let BTCAgent use your miner&apos;s IP address as its  worker name. The name that filled in the miner&apos;s control panel will be  ignored. <br> <br>A typical IP address worker name is: &quot;192x168x1x23&quot;, which means the miner  whose IP address is 192.168.1.23. The format of the name can be set with `ip_worker_name_format`. |
+| ip_worker_name_format | IP address worker name format | Set the format of the IP address worker name.<br><br>Available variables:<br>{1} represents the first number in the IP address.<br>{2} represents the second number in the IP address.<br>{3} represents the third number in the IP address.<br>{4} represents the 4th number in the IP address.<br><br>Examples:<br>{1}x{2}x{3}x{4}<br>If the IP address is &quot;192.168.1.23&quot;, the worker name is &quot;192x168x1x23&quot;.<br><br>{2}x{3}x{4}<br>If the IP address is &quot;192.168.1.23&quot;, the worker name is &quot;168x1x23&quot;.<br><br>{3}x{4}<br>If the IP address is &quot;192.168.1.23&quot;, the worker name is &quot;1x23&quot;. |
+| submit_response_from_server | **[Advanced]**<br>Send the pool response to the miner | Send the real response from the mining pool server to the miner.<br><br>If this option is not enabled, BTCAgent will send a &quot;success&quot; response immediately upon receiving the miner&apos;s submission. This will keep the &quot;rejection rate&quot; in the miner&apos;s control panel always at 0.<br><br>If you want to see the real rejection rate in the miner control panel, you can enable this option. But this may increase network traffic and latency. |
+| agent_listen_ip | BTCAgent listen IP | The listen IP of BTCAgent, miners should connect to your BTCAgent via this IP. It should be an IP address assigned to the computer running BTCAgent, or `0.0.0.0`. The `0.0.0.0` means "all possible IP addresses" and we recommend using it. |
+| agent_listen_port | BTCAgent listen port | The listen port of BTCAgent, miners should connect to your BTCAgent via this port. If you run multiple BTCAgent processes on one computer, each process should use a different port.<br><br>The valid range of the port is 1 to 65535, and the recommended range is 2000 to 5000. Use of ports lower than 1024 requires root privileges, and ports higher than 5000 may be randomly occupied by other programs. |
+| pool_use_tls | Use SSL/TLS encrypted connection to pool | Connect to the mining pool server encrypted with SSL/TLS to prevent network traffic from being monitored by the middleman.<br><br>Note: The address and port of the server that supports SSL/TLS encryption may be different from the normal server. If the server address and port you fill in does not support SSL/TLS encryption, enabling this option will cause BTCAgent to fail to connect to the server.<br><br>In addition, after enabling this option, the connection from your miners to this BTCAgent is still in plain text and will not be encrypted by SSL/TLS. So you don&apos;t need to change the miner settings. |
+| use_iocp | **[Windows Only]**<br>**[Experimental]**<br>Use IOCP for network connection | Enable the Windows I/O Completion Port (IOCP) for BTCAgent.<br><br>This may increase the throughput of BTCAgent and allow more miners to connect to a single BTCAgent process at the same time.<br><br>But this option is highly experimental. Our tests show that it will increase the memory usage of BTCAgent, and BTCAgent may crash or be no response in some cases.<br><br>We do not recommend that you enable this option unless you do experience throughput issues and cannot be resolved by other methods.<br><br>If you enable this option, be sure to set up a backup mining pool for miners. |
+| fixed_worker_name | **[Advanced]**<br>Use fixed worker name | Set the worker names of all miners to this value. It can simulate the traditional Stratum proxy, so that all miners connected to the BTCAgent are treated as a single miner in the mining pool.<br><br>Leave the value blank (`""`) or delete the option to disable this feature. |
+| pools | Mining pool server host, port, sub-account | [<br>&nbsp;&nbsp;&nbsp;&nbsp;["pool-server-host-1", server-port1, "sub-account-1"],<br>&nbsp;&nbsp;&nbsp;&nbsp;["pool-server-host-2", server-port2, "sub-account-2"],<br>&nbsp;&nbsp;&nbsp;&nbsp;["pool-server-host-3", server-port3, "sub-account-3"]<br>] |

README-Windows.md

@@ -75,8 +75,9 @@ config json file example:
     "agent_listen_port": 3333,
     "pool_use_tls": false,
     "pools": [
-        ["us.ss.btc.com", 1800, "kevin"],
-        ["us.ss.btc.com", 1800, "kevin"]
+        ["us.ss.btc.com", 1800, "YourSubAccountName"],
+        ["us.ss.btc.com", 443, "YourSubAccountName"],
+        ["us.ss.btc.com", 3333, "YourSubAccountName"]
     ]
 }
 ```

README-zh_CN.md

@@ -83,8 +83,9 @@ mkdir -p log_btcagent
     "agent_listen_port": 3333,
     "pool_use_tls": false,
     "pools": [
-        ["cn.ss.btc.com", 1800, "testpool"],
-        ["cn.ss.btc.com", 1800, "testpool"]
+        ["us.ss.btc.com", 1800, "YourSubAccountName"],
+        ["us.ss.btc.com", 443, "YourSubAccountName"],
+        ["us.ss.btc.com", 3333, "YourSubAccountName"]
     ]
 }
 ```
@@ -103,6 +104,8 @@ mkdir -p log_btcagent
 
 **注意**：矿机的用户会被自动替换为agent配置里的用户名，例如矿机为 `john.a001`，则在矿池端为：`kevin.a001`，矿机名称保持不变。
 
+配置文件详解：[ConfigFileDetails-zhCN.md](ConfigFileDetails-zhCN.md)
+
 **启动 / 停止**
 
 ```
@@ -177,7 +180,7 @@ cp agent_conf.json agent_conf_3334.json
     "agent_listen_port": 3334,
     "pool_use_tls": false,
     "pools": [
-        ["cn.ss.btc.com", 1800, "testpool3334"]
+        ["us.ss.btc.com", 1800, "YourSubAccountName2"]
     ]
 }
 ```

README.md

@@ -74,8 +74,9 @@ mkdir -p log_btcagent
     "agent_listen_port": 3333,
     "pool_use_tls": false,
     "pools": [
-        ["us.ss.btc.com", 1800, "testus"],
-        ["us.ss.btc.com", 443, "testus"]
+        ["us.ss.btc.com", 1800, "YourSubAccountName"],
+        ["us.ss.btc.com", 443, "YourSubAccountName"],
+        ["us.ss.btc.com", 3333, "YourSubAccountName"]
     ]
 }
 ```
@@ -92,6 +93,8 @@ mkdir -p log_btcagent
 
   * `["<stratum_server_host>", <stratum_server_port>, "<pool_username>"]`
 
+More details see [ConfigFileDetails.md](ConfigFileDetails.md).
+
 **start / stop**
 
 ```
@@ -144,7 +147,7 @@ cp agent_conf.json agent_conf_3334.json
     "agent_listen_port": 3334,
     "pool_use_tls": false,
     "pools": [
-        ["us.ss.btc.com", 1800, "testus3334"]
+        ["us.ss.btc.com", 1800, "YourSubAccountName2"]
     ]
 }
 ```

src/agent/agent_conf.json

@@ -10,8 +10,8 @@
     "pool_use_tls": false,
     "use_iocp": false,
     "pools": [
-        ["cn.ss.btc.com", 1800, "testpool"],
-        ["cn.ss.btc.com", 443, "testpool"],
-        ["cn.ss.btc.com", 3333, "testpool"]
+        ["us.ss.btc.com", 1800, "YourSubAccountName"],
+        ["us.ss.btc.com", 443, "YourSubAccountName"],
+        ["us.ss.btc.com", 3333, "YourSubAccountName"]
     ]
 }

src/agent/agent_conf_fixed_worker_name.json

@@ -11,8 +11,8 @@
     "use_iocp": false,
     "fixed_worker_name": "myworker",
     "pools": [
-        ["cn.ss.btc.com", 1800, "testpool"],
-        ["cn.ss.btc.com", 443, "testpool"],
-        ["cn.ss.btc.com", 3333, "testpool"]
+        ["us.ss.btc.com", 1800, "YourSubAccountName"],
+        ["us.ss.btc.com", 443, "YourSubAccountName"],
+        ["us.ss.btc.com", 3333, "YourSubAccountName"]
     ]
 }