add docs

2026-03-05 13:58:29 +08:00
parent 8d9f52a180
commit 07f086b55d
4 changed files with 212 additions and 0 deletions
@@ -0,0 +1,59 @@
+--- /dev/null
+++ b/docs/configuration/inbound/mysql.md
+@@ -0,0 +1,56 @@
+// OMV
+
+### Structure
+
+```json
+{
+  "type": "mysql",
+  "tag": "mysql-in",
+
+  ... // Listen Fields
+
+  "users": [
+    {
+      "user": "root",
+      "password": "my_password"
+    }
+  ],
+  "tls": {},
+  "multiplex": {}
+}
+```
+
+### Listen Fields
+
+See [Listen Fields](/configuration/shared/listen/) for details.
+
+### Fields
+
+#### users
+
+MySQL users for authentication during the handshake.
+
+#### tls
+
+==Required==
+
+TLS configuration, see [TLS](/configuration/shared/tls/#inbound).
+
+TLS must be enabled because the MySQL protocol uses TLS negotiation during the handshake phase.
+
+#### multiplex
+
+See [Multiplex](/configuration/shared/multiplex#inbound) for details.
+
+### Description
+
+The MySQL inbound uses the MySQL protocol handshake for TLS negotiation, then runs smux multiplexing over the encrypted connection.
+
+The connection flow is:
+
+1. Client connects and performs a standard MySQL handshake (using [go-mysql](https://github.com/go-mysql-org/go-mysql))
+2. TLS is negotiated as part of the MySQL handshake
+3. After handshake, smux sessions are multiplexed over the TLS connection
+4. Each smux stream carries a 1-byte command (`0x01` for TCP, `0x03` for UDP) followed by a SOCKS address header
+
+This makes the traffic appear as a normal MySQL TLS connection to network observers.
@@ -0,0 +1,58 @@
+--- /dev/null
+++ b/docs/configuration/omv.md
+@@ -0,0 +1,55 @@
+# OMV Modifications
+
+This page documents all modifications made by OMV (omv-dijiang) on top of upstream sing-box.
+
+## MySQL Protocol
+
+A custom proxy protocol that disguises traffic as MySQL TLS connections.
+
+- [MySQL Inbound](/configuration/inbound/mysql/)
+- [MySQL Outbound](/configuration/outbound/mysql/)
+
+### How it works
+
+1. The client and server perform a standard MySQL handshake using [go-mysql](https://github.com/go-mysql-org/go-mysql)
+2. TLS is negotiated as part of the MySQL protocol (the same way a real MySQL client upgrades to TLS)
+3. After the handshake, [smux](https://github.com/sagernet/smux) multiplexing runs over the encrypted connection
+4. Each smux stream carries a command byte and destination address, then proxies the connection
+
+To network observers, the traffic appears as a normal MySQL TLS session on port 3306.
+
+## Subscription Support
+
+The `sing-box run` command supports fetching configuration from a remote URL via environment variables.
+
+### Usage
+
+```bash
+SING_SUBSCRIPTION_LINK="https://example.com/config.json" \
+SING_SUBSCRIPTION_CACHE="/path/to/cache.json" \
+sing-box run -c env
+```
+
+### Environment Variables
+
+#### `SING_SUBSCRIPTION_LINK`
+
+The URL to fetch the configuration from. Only used when the config path is set to `env` (i.e. `-c env`).
+
+#### `SING_SUBSCRIPTION_CACHE`
+
+Optional. Path to a local file for caching the fetched configuration.
+
+- On successful fetch, the configuration is saved to this file
+- If the fetch fails (network error or non-200 status), the cached file is used as a fallback
+- If not set and the fetch fails, the command returns an error
+
+## URLTest Costs
+
+The `urltest` outbound group supports a `costs` field to add artificial latency penalties to specific outbounds.
+
+See [URLTest Outbound](/configuration/outbound/urltest/#costs) for details.
+
+## Log Level Adjustments
+
+Process path lookup logs (e.g. "found process path: ...", "found user: ...") are demoted from `info` to `debug` level to reduce log noise.
@@ -0,0 +1,68 @@
+--- /dev/null
+++ b/docs/configuration/outbound/mysql.md
+@@ -0,0 +1,65 @@
+// OMV
+
+### Structure
+
+```json
+{
+  "type": "mysql",
+  "tag": "mysql-out",
+
+  "server": "127.0.0.1",
+  "server_port": 3306,
+  "username": "root",
+  "password": "my_password",
+  "tls": {},
+  "multiplex": {},
+
+  ... // Dial Fields
+}
+```
+
+### Fields
+
+#### server
+
+==Required==
+
+The server address.
+
+#### server_port
+
+The server port.
+
+Default `3306`.
+
+#### username
+
+The MySQL username for authentication.
+
+Default `root`.
+
+#### password
+
+The MySQL password for authentication.
+
+#### tls
+
+TLS configuration, see [TLS](/configuration/shared/tls/#outbound).
+
+If not set or disabled, an insecure TLS config will be used (since TLS is required for the MySQL handshake tunnel).
+
+#### multiplex
+
+See [Multiplex](/configuration/shared/multiplex#outbound) for details.
+
+The `max_connections` option controls how many parallel smux sessions (each over a separate MySQL+TLS connection) are maintained. Streams are round-robin distributed across sessions.
+
+### Dial Fields
+
+See [Dial Fields](/configuration/shared/dial/) for details.
+
+### Description
+
+The MySQL outbound connects to a MySQL inbound server. It performs a MySQL client handshake (using [go-mysql](https://github.com/go-mysql-org/go-mysql)) to negotiate TLS, then establishes smux sessions over the encrypted connection.
+
+Each proxied connection opens a new smux stream with a 1-byte command header (`0x01` for TCP, `0x03` for UDP) followed by the destination address. UDP connections use UDP-over-TCP (UoT).
@@ -0,0 +1,27 @@
+--- a/docs/configuration/outbound/urltest.md
+++ b/docs/configuration/outbound/urltest.md
+@@ -10,6 +10,9 @@
+     "proxy-b",
+     "proxy-c"
+   ],
+  "costs": {
+    "proxy-c": 100
+  },
+   "url": "",
+   "interval": "",
+   "tolerance": 0,
+@@ -26,6 +29,14 @@
+ 
+ List of outbound tags to test.
+ 
+#### costs
+
+A map of outbound tag to additional latency penalty in milliseconds.
+
+The penalty is added to the measured latency when selecting the best outbound. This allows deprioritizing certain outbounds without removing them from the test group.
+
+For example, `{"proxy-c": 100}` adds 100ms to `proxy-c`'s measured latency, making it less likely to be selected unless it is significantly faster than other outbounds.
+
+ #### url
+ 
+ The URL to test. `https://www.gstatic.com/generate_204` will be used if empty.