usmo 0.6.2__tar.gz → 0.7.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {usmo-0.6.2 → usmo-0.7.0}/PKG-INFO +3 -1
- {usmo-0.6.2 → usmo-0.7.0}/README.md +2 -0
- usmo-0.7.0/docs/commands/clash.md +208 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/index.md +2 -0
- usmo-0.7.0/docs/commands/proxy.md +213 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/index.md +2 -0
- {usmo-0.6.2 → usmo-0.7.0}/mkdocs.yml +2 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/_config.json +25 -2
- usmo-0.7.0/scripts/clash.py +1499 -0
- usmo-0.7.0/scripts/proxy.py +1140 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/serve.py +4 -4
- {usmo-0.6.2 → usmo-0.7.0}/src/usmo/_version.py +2 -2
- {usmo-0.6.2 → usmo-0.7.0}/.github/workflows/docs.yml +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/.github/workflows/release.yml +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/.gitignore +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/.pre-commit-config.yaml +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/dev/bump_version.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/architecture.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/bench.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/blobmount.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/builtin.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/clip.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/cp.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/cu122.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/gpu.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/init.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/inject-alias.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/notify.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/openai-proxy.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/port.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/rsync.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/secret.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/serve.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/share.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/sysinfo.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/tunnel.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/commands/wait.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/development.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/docs/installation.md +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/pyproject.toml +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/bench.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/blobmount.sh +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/check_py.sh +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/clip.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/cp.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/cu122.sh +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/gpu.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/init.sh +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/inject_alias.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/install.sh +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/notify.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/openai_proxy.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/port.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/rsync.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/secret.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/share.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/sysinfo.sh +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/tunnel.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/scripts/wait.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/src/usmo/__init__.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/src/usmo/cli.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/src/usmo/core.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/tests/conftest.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/tests/test_core_autocheck.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/tests/test_core_hash.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/tests/test_core_script.py +0 -0
- {usmo-0.6.2 → usmo-0.7.0}/tests/test_openai_proxy.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: usmo
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.0
|
|
4
4
|
Summary: Bootstrap machines and run cached utility scripts from one CLI.
|
|
5
5
|
Project-URL: Homepage, https://github.com/HSPK/usm
|
|
6
6
|
Project-URL: Repository, https://github.com/HSPK/usm
|
|
@@ -91,6 +91,8 @@ changes required.
|
|
|
91
91
|
| `usm sysinfo` | Print system, GPU, CUDA, MPI, and distributed-ML environment summary. |
|
|
92
92
|
| `usm inject-alias [--shell bash\|zsh\|powershell] [--file PATH]` | Insert or update the managed `usm` alias block in your shell rc file. |
|
|
93
93
|
| `usm tunnel <local\|remote\|socks\|ls\|stop\|start\|restart\|rm\|enable\|disable\|show\|logs>` | Start and manage SSH tunnels with persistent state; `enable`/`disable` install/remove a systemd `--user` unit for boot-time autostart. |
|
|
94
|
+
| `usm proxy <server\|client\|ls\|url\|stop\|start\|restart\|rm\|enable\|disable\|show\|logs\|install>` | Turn a box into an HTTP/SOCKS (+Shadowsocks) proxy (`server`), or run a Clash client that routes rule-matched traffic through a remote proxy (`client`). Auto-installs `mihomo`; `enable`/`disable` manage a systemd `--user` unit. |
|
|
95
|
+
| `usm clash <sub\|use\|up\|down\|restart\|status\|mode\|proxies\|select\|test\|tun\|system-proxy\|lan\|logs\|conns\|dashboard\|enable\|disable\|install>` | ClashX-style CLI manager for the mihomo core: subscription/profile management, rule/global/direct mode, node selection, latency tests, TUN, system proxy, LAN sharing, live logs, and connection inspection. |
|
|
94
96
|
| `usm gpu [free\|watch\|kill]` | GPU inventory, free-picker (`CUDA_VISIBLE_DEVICES=$(usm gpu free 2)`), live watch, kill CUDA processes. |
|
|
95
97
|
| `usm port [PORT\|ls\|kill PORT]` | Show what's listening on a port; free a port by killing the holder. |
|
|
96
98
|
| `usm notify [config\|test] [-- CMD ARGS]` | Wrap a command and ping ntfy.sh / Telegram / generic webhook when it exits. |
|
|
@@ -78,6 +78,8 @@ changes required.
|
|
|
78
78
|
| `usm sysinfo` | Print system, GPU, CUDA, MPI, and distributed-ML environment summary. |
|
|
79
79
|
| `usm inject-alias [--shell bash\|zsh\|powershell] [--file PATH]` | Insert or update the managed `usm` alias block in your shell rc file. |
|
|
80
80
|
| `usm tunnel <local\|remote\|socks\|ls\|stop\|start\|restart\|rm\|enable\|disable\|show\|logs>` | Start and manage SSH tunnels with persistent state; `enable`/`disable` install/remove a systemd `--user` unit for boot-time autostart. |
|
|
81
|
+
| `usm proxy <server\|client\|ls\|url\|stop\|start\|restart\|rm\|enable\|disable\|show\|logs\|install>` | Turn a box into an HTTP/SOCKS (+Shadowsocks) proxy (`server`), or run a Clash client that routes rule-matched traffic through a remote proxy (`client`). Auto-installs `mihomo`; `enable`/`disable` manage a systemd `--user` unit. |
|
|
82
|
+
| `usm clash <sub\|use\|up\|down\|restart\|status\|mode\|proxies\|select\|test\|tun\|system-proxy\|lan\|logs\|conns\|dashboard\|enable\|disable\|install>` | ClashX-style CLI manager for the mihomo core: subscription/profile management, rule/global/direct mode, node selection, latency tests, TUN, system proxy, LAN sharing, live logs, and connection inspection. |
|
|
81
83
|
| `usm gpu [free\|watch\|kill]` | GPU inventory, free-picker (`CUDA_VISIBLE_DEVICES=$(usm gpu free 2)`), live watch, kill CUDA processes. |
|
|
82
84
|
| `usm port [PORT\|ls\|kill PORT]` | Show what's listening on a port; free a port by killing the holder. |
|
|
83
85
|
| `usm notify [config\|test] [-- CMD ARGS]` | Wrap a command and ping ntfy.sh / Telegram / generic webhook when it exits. |
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
# `usm clash`
|
|
2
|
+
|
|
3
|
+
A ClashX-style **command-line manager** for the [mihomo](https://github.com/MetaCubeX/mihomo)
|
|
4
|
+
(Clash.Meta) core: subscriptions, profile switching, rule/global/direct mode,
|
|
5
|
+
node selection, latency tests, TUN, system-proxy, LAN sharing, live logs and
|
|
6
|
+
traffic, and connection inspection — all from the terminal.
|
|
7
|
+
|
|
8
|
+
`usm clash` is the **client manager** (consume a subscription, route your
|
|
9
|
+
traffic out). For turning a box *into* a proxy, or a quick single-upstream
|
|
10
|
+
client, see [`usm proxy`](proxy.md).
|
|
11
|
+
|
|
12
|
+
The mihomo binary is auto-installed to `~/.cache/usm/bin/mihomo` on first use
|
|
13
|
+
(no sudo, no system packages); set `$USM_MIHOMO_BIN` to use your own.
|
|
14
|
+
|
|
15
|
+
## Mental model
|
|
16
|
+
|
|
17
|
+
- **Profiles** — Clash configs, usually fetched from a **subscription** URL.
|
|
18
|
+
You can have many; one is **active**.
|
|
19
|
+
- **The core** — a single mihomo process driven by the active profile, with a
|
|
20
|
+
handful of manager-controlled overrides (port, mode, TUN, LAN, controller).
|
|
21
|
+
- **Runtime control** — once running, `usm clash` talks to mihomo's RESTful
|
|
22
|
+
API to switch mode, select nodes, test latency, stream logs, etc.
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
subscription ─▶ profile (active) ─┐
|
|
26
|
+
├─▶ runtime.yaml ─▶ mihomo ─▶ RESTful API ◀─ usm clash mode/select/test/logs
|
|
27
|
+
manager overrides (port/mode/tun)─┘ │
|
|
28
|
+
127.0.0.1:7890 (http+socks) ◀─ your apps
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Subcommands
|
|
32
|
+
|
|
33
|
+
| Command | What it does |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| `sub add SOURCE [--name N] [--interval H]` | Add a subscription URL or a local config file. |
|
|
36
|
+
| `sub ls` | List profiles (active marker, type, last update, traffic, expiry). |
|
|
37
|
+
| `sub update [NAME]` | Re-fetch remote profiles (one or all). |
|
|
38
|
+
| `sub rm NAME` | Delete a profile. |
|
|
39
|
+
| `use NAME` | Set the active profile (hot-applies if running). |
|
|
40
|
+
| `up [NAME] [--tun] [--lan] [--system-proxy] [-p PORT]` | Start the core. |
|
|
41
|
+
| `down` | Stop the core (and restore system proxy). |
|
|
42
|
+
| `restart` | Restart the core. |
|
|
43
|
+
| `status` | Running state, ports, mode, toggles, uptime, traffic. |
|
|
44
|
+
| `mode [rule\|global\|direct]` | Get or set the routing mode. |
|
|
45
|
+
| `proxies [GROUP]` | List groups, members, current selection, last delay. |
|
|
46
|
+
| `select GROUP NODE` | Pick a node in a group. |
|
|
47
|
+
| `test [GROUP\|NODE] [--url U] [--timeout MS]` | Latency-test a group, a node, or every node. |
|
|
48
|
+
| `tun on\|off\|status` | Toggle TUN (transparent system-wide capture). |
|
|
49
|
+
| `system-proxy on\|off\|status` | Set/clear the OS HTTP/SOCKS proxy. |
|
|
50
|
+
| `lan on\|off\|status` | Toggle `allow-lan` (let other devices use this box). |
|
|
51
|
+
| `logs [-f] [-n N] [--level L]` | Tail the log file, or stream live via the API. |
|
|
52
|
+
| `conns [--close]` | Show (or close) active connections. |
|
|
53
|
+
| `dashboard` | Print a web dashboard URL wired to the running core. |
|
|
54
|
+
| `enable` / `disable` | Autostart at login via a systemd `--user` unit. |
|
|
55
|
+
| `install [--upgrade]` | Pre-download the mihomo binary. |
|
|
56
|
+
|
|
57
|
+
## Subscriptions & profiles
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
usm clash sub add https://provider.example/sub?token=… --name work
|
|
61
|
+
usm clash sub add ./my-clash.yaml --name local # a local Clash config file
|
|
62
|
+
usm clash sub ls
|
|
63
|
+
usm clash sub update work # re-fetch
|
|
64
|
+
usm clash use work # switch active profile
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Subscriptions are fetched with a Clash User-Agent, so providers return a
|
|
68
|
+
**Clash-format YAML** (this is what carries the node list, groups, and rules —
|
|
69
|
+
mihomo understands every node protocol inside it: ss, vmess, vless, trojan,
|
|
70
|
+
hysteria2, tuic, …). The `Subscription-Userinfo` header (traffic used / total,
|
|
71
|
+
expiry) is parsed and shown in `sub ls`.
|
|
72
|
+
|
|
73
|
+
!!! note "Use the Clash subscription link"
|
|
74
|
+
Point `sub add` at the provider's **Clash / Clash.Meta** subscription URL.
|
|
75
|
+
Raw base64 node-list links (the generic "v2ray" format) are not supported —
|
|
76
|
+
ask your provider for the Clash link (almost all offer one).
|
|
77
|
+
|
|
78
|
+
Remote profiles auto-refresh on `up`/`restart` once older than `--interval`
|
|
79
|
+
hours (default 12; `0` disables).
|
|
80
|
+
|
|
81
|
+
## Running & status
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
usm clash up # start with the active profile
|
|
85
|
+
usm clash up work --lan # switch profile + allow LAN in one go
|
|
86
|
+
usm clash status
|
|
87
|
+
usm clash down
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`status` shows the running state, mixed port, controller, mode, and the
|
|
91
|
+
TUN / LAN / system-proxy toggles, plus live traffic totals when running:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
status ● running (pid 12345)
|
|
95
|
+
profile work
|
|
96
|
+
mode rule
|
|
97
|
+
mixed port 127.0.0.1:7890
|
|
98
|
+
controller 127.0.0.1:9090
|
|
99
|
+
tun off
|
|
100
|
+
allow-lan on
|
|
101
|
+
system-proxy off
|
|
102
|
+
autostart off
|
|
103
|
+
uptime 3m12s
|
|
104
|
+
traffic: ↓ 1.2GiB ↑ 88.4MiB | active conns: 7
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Your apps connect to the **mixed port** (`127.0.0.1:7890` by default), which
|
|
108
|
+
speaks **HTTP and SOCKS5 on the same port**.
|
|
109
|
+
|
|
110
|
+
## Mode, node selection, latency tests
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
usm clash mode global # rule | global | direct (instant via API)
|
|
114
|
+
usm clash proxies # all groups, members, current pick, last delay
|
|
115
|
+
usm clash proxies PROXY # just one group
|
|
116
|
+
usm clash select PROXY hk-01 # choose a node
|
|
117
|
+
usm clash test PROXY # latency-test every node in the group
|
|
118
|
+
usm clash test hk-01 # test a single node
|
|
119
|
+
usm clash test # test all nodes
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Node selections persist across restarts (`profile.store-selected`).
|
|
123
|
+
|
|
124
|
+
## TUN — transparent, system-wide
|
|
125
|
+
|
|
126
|
+
TUN captures **all** OS traffic (not just apps that honor proxy settings) by
|
|
127
|
+
creating a virtual network interface. It needs `CAP_NET_ADMIN`:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
sudo setcap cap_net_admin,cap_net_bind_service+ep ~/.cache/usm/bin/mihomo
|
|
131
|
+
usm clash tun on # then this works without per-run sudo
|
|
132
|
+
usm clash tun off
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`usm clash tun on` prints the exact `setcap` line if the capability is missing.
|
|
136
|
+
When TUN is on, a sane DNS block (fake-ip) is injected if your profile doesn't
|
|
137
|
+
already define one.
|
|
138
|
+
|
|
139
|
+
## System proxy & LAN
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
usm clash system-proxy on # set the OS HTTP/HTTPS/SOCKS proxy to the core
|
|
143
|
+
usm clash system-proxy off # restore the previous setting
|
|
144
|
+
usm clash lan on # bind 0.0.0.0 so other LAN devices can use it
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
`system-proxy` integrates with GNOME (`gsettings`), macOS (`networksetup`), and
|
|
148
|
+
Windows (registry). On any system it also writes shell exports to
|
|
149
|
+
`~/.cache/usm/clash/proxy.env` for terminal apps:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
source ~/.cache/usm/clash/proxy.env # http_proxy/https_proxy/all_proxy
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Logs, connections, dashboard
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
usm clash logs -n 100 # tail the log file
|
|
159
|
+
usm clash logs -f # stream live logs via the API (Ctrl-C to stop)
|
|
160
|
+
usm clash conns # active connections (host, chain, rule, up/down)
|
|
161
|
+
usm clash conns --close # drop all connections
|
|
162
|
+
usm clash dashboard # prints a metacubexd URL wired to your core
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
The dashboard URL embeds your controller host/port/secret; mihomo serves the
|
|
166
|
+
API with CORS enabled, so the hosted UI connects straight to your local core.
|
|
167
|
+
|
|
168
|
+
## State & files
|
|
169
|
+
|
|
170
|
+
Everything lives under `~/.cache/usm/clash/`:
|
|
171
|
+
|
|
172
|
+
- `profiles/<name>.yaml` + `<name>.json` — the config and its metadata.
|
|
173
|
+
- `state.json` — active profile, port, mode, toggles, controller secret, pid.
|
|
174
|
+
- `runtime.yaml` — the composed config actually fed to mihomo (regenerated on
|
|
175
|
+
every start from the active profile + your overrides).
|
|
176
|
+
- `mihomo.log`, `cache.db` (node-selection persistence), `proxy.env`.
|
|
177
|
+
|
|
178
|
+
`runtime.yaml` always overrides `mixed-port`, `external-controller`, `secret`,
|
|
179
|
+
`mode`, `allow-lan`, and `tun` so the manager stays in control regardless of
|
|
180
|
+
what the subscription set.
|
|
181
|
+
|
|
182
|
+
## Autostart at boot (systemd)
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
usm clash enable # ~/.config/systemd/user/usm-clash.service + start now
|
|
186
|
+
usm clash disable
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The unit runs `usm clash run` in the foreground, restarts on failure, and
|
|
190
|
+
starts after `network-online.target`. As with [`usm tunnel`](tunnel.md), user
|
|
191
|
+
units only start at boot once linger is on:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
sudo loginctl enable-linger "$USER"
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
(System-proxy is a desktop-session setting and is not managed by the systemd
|
|
198
|
+
unit; toggle it interactively with `usm clash system-proxy on`.)
|
|
199
|
+
|
|
200
|
+
## `usm clash` vs `usm proxy`
|
|
201
|
+
|
|
202
|
+
| | `usm clash` | [`usm proxy`](proxy.md) |
|
|
203
|
+
| --- | --- | --- |
|
|
204
|
+
| Role | Full **client manager** (ClashX-style) | Lightweight **server** + simple **client** |
|
|
205
|
+
| Config source | Subscriptions / Clash profiles | A single upstream URL + a few rules |
|
|
206
|
+
| Runtime control | mode, node selection, delay tests, live logs (API) | none (static) |
|
|
207
|
+
| TUN / system-proxy / LAN | yes | no |
|
|
208
|
+
| Best for | Daily driver with many nodes & rules | Turning a box into a proxy, or a quick one-off client |
|
|
@@ -14,6 +14,8 @@ Every subcommand of `usm` falls into one of two buckets:
|
|
|
14
14
|
| Command | Page |
|
|
15
15
|
| --- | --- |
|
|
16
16
|
| `tunnel` | [SSH tunnel manager](tunnel.md) |
|
|
17
|
+
| `proxy` | [HTTP/SOCKS/Clash proxy (mihomo)](proxy.md) |
|
|
18
|
+
| `clash` | [ClashX-style mihomo manager](clash.md) |
|
|
17
19
|
| `gpu` | [GPU picker/watch](gpu.md) |
|
|
18
20
|
| `port` | [Port discovery/kill](port.md) |
|
|
19
21
|
| `notify` | [Long-task pings](notify.md) |
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# `usm proxy`
|
|
2
|
+
|
|
3
|
+
Turn a machine into a proxy other hosts dial into, **and/or** run a local
|
|
4
|
+
[Clash](https://github.com/MetaCubeX/mihomo) client that sends only
|
|
5
|
+
rule-matched traffic out through it. Both roles are driven by a single
|
|
6
|
+
auto-installed [mihomo](https://github.com/MetaCubeX/mihomo) (Clash.Meta)
|
|
7
|
+
binary, with the same persistent state, short ids, and optional systemd
|
|
8
|
+
autostart you get from [`usm tunnel`](tunnel.md).
|
|
9
|
+
|
|
10
|
+
## Two roles
|
|
11
|
+
|
|
12
|
+
| Role | What it does |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| `server` | Make **this** box a proxy: a mixed HTTP+SOCKS inbound (optionally password-protected) and/or an encrypted `ss://` (Shadowsocks) inbound. It forwards everything straight out (`mode: direct`). |
|
|
15
|
+
| `client` | Run a local mixed HTTP+SOCKS inbound for your apps; traffic that matches a rule goes out through a remote proxy, everything else stays direct. |
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
your apps ──▶ usm proxy client (127.0.0.1:7890)
|
|
19
|
+
│ rule match → PROXY
|
|
20
|
+
▼
|
|
21
|
+
usm proxy server (host:7890 / ss://host:8388)
|
|
22
|
+
│
|
|
23
|
+
▼
|
|
24
|
+
the internet
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Subcommands
|
|
28
|
+
|
|
29
|
+
| Command | What it does |
|
|
30
|
+
| --- | --- |
|
|
31
|
+
| `server [OPTIONS]` | Define + start a proxy server on this box. |
|
|
32
|
+
| `client UPSTREAM [OPTIONS]` | Define + start a client that routes through `UPSTREAM`. |
|
|
33
|
+
| `url <id>` | Print the connect URLs (`http://`, `socks5://`, `ss://`) for a server. |
|
|
34
|
+
| `ls [--prune]` | List proxies with role / route / PID / uptime / status / boot flag. |
|
|
35
|
+
| `start <id>` | Relaunch a stopped proxy (or `systemctl start` if enabled). |
|
|
36
|
+
| `stop <id\|all>` | Stop a proxy but **keep the definition** for later. |
|
|
37
|
+
| `restart <id>` | `stop` + `start` (or `systemctl restart` if enabled). |
|
|
38
|
+
| `rm <id\|all>` | Delete the definition (also disables systemd if enabled). |
|
|
39
|
+
| `enable <id>` | Install a `systemd --user` unit and start it. |
|
|
40
|
+
| `disable <id>` | Remove the unit (keeps the definition). |
|
|
41
|
+
| `show <id>` | Dump the definition as JSON (passwords redacted). |
|
|
42
|
+
| `logs <id> [-n N]` | Print the tail of the per-proxy log. |
|
|
43
|
+
| `install [--upgrade]` | Pre-download the mihomo binary. |
|
|
44
|
+
|
|
45
|
+
## Server
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
usm proxy server # mixed HTTP+SOCKS on 0.0.0.0:7890
|
|
49
|
+
usm proxy server --auth alice:s3cret # require username/password
|
|
50
|
+
usm proxy server --ss # also expose an encrypted ss:// inbound
|
|
51
|
+
usm proxy server --ss --no-mixed --host 1.2.3.4 # ss:// only, advertise a public IP
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
| Flag | Default | Meaning |
|
|
55
|
+
| --- | --- | --- |
|
|
56
|
+
| `-p`, `--port N` | `7890` | Mixed HTTP+SOCKS inbound port. |
|
|
57
|
+
| `--mixed / --no-mixed` | `--mixed` | Expose the mixed HTTP+SOCKS inbound. |
|
|
58
|
+
| `--listen ADDR` | `0.0.0.0` | Bind address for the inbounds. |
|
|
59
|
+
| `--auth USER:PASS` | — | Require credentials on the HTTP/SOCKS inbound. |
|
|
60
|
+
| `--ss` | off | Also expose an encrypted Shadowsocks inbound. |
|
|
61
|
+
| `--ss-port N` | `8388` | Shadowsocks port (implies `--ss`). |
|
|
62
|
+
| `--cipher NAME` | `aes-256-gcm` | Shadowsocks cipher. |
|
|
63
|
+
| `--password PW` | random | Shadowsocks password (a random one is generated if omitted). |
|
|
64
|
+
| `--host H` | auto | Host/IP advertised by `url` (set this to your public IP). |
|
|
65
|
+
| `--name NAME` | next integer | Custom id. |
|
|
66
|
+
|
|
67
|
+
After starting, `usm proxy url <id>` prints ready-to-paste connect strings:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
$ usm proxy url 0
|
|
71
|
+
http://alice:s3cret@1.2.3.4:7890
|
|
72
|
+
socks5://alice:s3cret@1.2.3.4:7890
|
|
73
|
+
ss://YWVzLTI1Ni1nY206…@1.2.3.4:8388#usm-0
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
!!! warning "Plain HTTP/SOCKS is unencrypted"
|
|
77
|
+
The mixed inbound carries traffic in the clear. Expose it only on a
|
|
78
|
+
trusted network, behind `--auth`, or tunneled (e.g. via
|
|
79
|
+
[`usm tunnel`](tunnel.md)). For the public internet, use the `ss://`
|
|
80
|
+
inbound (`--ss`), which is encrypted, and open the port in your firewall.
|
|
81
|
+
|
|
82
|
+
## Client
|
|
83
|
+
|
|
84
|
+
Feed `client` any proxy URL — including a line straight out of
|
|
85
|
+
`usm proxy url`:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
usm proxy client http://alice:s3cret@1.2.3.4:7890 # via HTTP
|
|
89
|
+
usm proxy client socks5://1.2.3.4:1080 # via SOCKS5
|
|
90
|
+
usm proxy client 'ss://YWVz…@1.2.3.4:8388' # via Shadowsocks
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Then point your apps at `http://127.0.0.1:7890` (HTTP **and** SOCKS on the
|
|
94
|
+
same port):
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
export http_proxy=http://127.0.0.1:7890 https_proxy=http://127.0.0.1:7890
|
|
98
|
+
curl https://ifconfig.me # comes out of the server
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
| Flag | Default | Meaning |
|
|
102
|
+
| --- | --- | --- |
|
|
103
|
+
| `-p`, `--port N` | `7890` | Local mixed HTTP+SOCKS inbound for your apps. |
|
|
104
|
+
| `--listen ADDR` | `127.0.0.1` | Bind address for the local inbound. |
|
|
105
|
+
| `--rule RULE` | — | Extra mihomo rule (repeatable), e.g. `'DOMAIN-SUFFIX,github.com,PROXY'`. |
|
|
106
|
+
| `--rules-file F` | — | Read rules from a file (one per line; `#` comments ignored). |
|
|
107
|
+
| `--final proxy\|direct` | `proxy` | Where **unmatched** traffic goes (the trailing `MATCH` rule). |
|
|
108
|
+
| `--controller [ADDR]` | off | Enable mihomo's RESTful API (default `127.0.0.1:9090`). |
|
|
109
|
+
| `--secret S` | — | Secret for the external controller. |
|
|
110
|
+
| `--name NAME` | next integer | Custom id. |
|
|
111
|
+
|
|
112
|
+
### How rules are assembled
|
|
113
|
+
|
|
114
|
+
The generated `rules:` block, top to bottom, is:
|
|
115
|
+
|
|
116
|
+
1. Private / loopback ranges (`127.0.0.0/8`, `10.0.0.0/8`, `192.168.0.0/16`,
|
|
117
|
+
`::1`, …) → `DIRECT`, so LAN and localhost never loop through the proxy.
|
|
118
|
+
2. Your `--rule` / `--rules-file` lines, verbatim, in order.
|
|
119
|
+
3. `MATCH,<final>` — the catch-all (`PROXY` by default, `DIRECT` with
|
|
120
|
+
`--final direct`).
|
|
121
|
+
|
|
122
|
+
Two common shapes fall out of this:
|
|
123
|
+
|
|
124
|
+
=== "Everything through the server (default)"
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
usm proxy client http://alice:s3cret@1.2.3.4:7890
|
|
128
|
+
# private ranges stay direct; everything else → the server
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
=== "Only specific traffic through the server"
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
usm proxy client http://1.2.3.4:7890 \
|
|
135
|
+
--rule 'DOMAIN-SUFFIX,github.com,PROXY' \
|
|
136
|
+
--rule 'DOMAIN-SUFFIX,openai.com,PROXY' \
|
|
137
|
+
--final direct
|
|
138
|
+
# only github.com / openai.com go through the server; the rest is direct
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Rules use mihomo's syntax — `DOMAIN-SUFFIX`, `DOMAIN-KEYWORD`, `IP-CIDR`,
|
|
142
|
+
`GEOIP`, `PROCESS-NAME`, etc. See the
|
|
143
|
+
[mihomo rules docs](https://wiki.metacubex.one/config/rules/). The config is
|
|
144
|
+
validated with `mihomo -t` before launch, so a typo fails fast with the exact
|
|
145
|
+
parser error.
|
|
146
|
+
|
|
147
|
+
## End-to-end example
|
|
148
|
+
|
|
149
|
+
On the server (a well-connected box):
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
usm proxy server --ss --auth alice:s3cret --host 203.0.113.10
|
|
153
|
+
usm proxy url 0 # copy the ss:// line
|
|
154
|
+
usm proxy enable 0 # optional: autostart at boot
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
On your laptop:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
usm proxy client 'ss://YWVz…@203.0.113.10:8388'
|
|
161
|
+
export https_proxy=http://127.0.0.1:7890
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Ids, state, and logs
|
|
165
|
+
|
|
166
|
+
`server` / `client` assign the next free non-negative integer as the id
|
|
167
|
+
(`0`, `1`, …); pass `--name foo` for a memorable one. Each proxy lives under
|
|
168
|
+
`~/.cache/usm/proxy/<id>/`:
|
|
169
|
+
|
|
170
|
+
- `state.json` — the definition (`stop` keeps it; `rm` deletes it).
|
|
171
|
+
- `config.yaml` — the mihomo config, regenerated from `state.json` on every start.
|
|
172
|
+
- `mihomo.log` — appended on each (re)start; read it with `usm proxy logs <id>`.
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
usm proxy ls
|
|
176
|
+
usm proxy show 0 # passwords shown as ***
|
|
177
|
+
usm proxy logs 0 -n 100
|
|
178
|
+
usm proxy rm all
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## The mihomo binary
|
|
182
|
+
|
|
183
|
+
The first run downloads a pinned mihomo release into
|
|
184
|
+
`~/.cache/usm/bin/mihomo` (`chmod +x`) — no system packages, no sudo, same
|
|
185
|
+
mechanism as [`usm serve`](serve.md). Pre-fetch it with `usm proxy install`,
|
|
186
|
+
refresh with `usm proxy install --upgrade`, or point `$USM_MIHOMO_BIN` at your
|
|
187
|
+
own build to bypass the download entirely.
|
|
188
|
+
|
|
189
|
+
## Autostart at boot (systemd)
|
|
190
|
+
|
|
191
|
+
`usm proxy enable <id>` writes
|
|
192
|
+
`~/.config/systemd/user/usm-proxy-<id>.service`, runs `daemon-reload`, then
|
|
193
|
+
`systemctl --user enable --now`. The unit runs `usm proxy up <id>` in the
|
|
194
|
+
foreground, restarts on failure, and starts after `network-online.target` —
|
|
195
|
+
exactly like [`usm tunnel`](tunnel.md#autostart-at-boot-systemd).
|
|
196
|
+
|
|
197
|
+
!!! warning "Linger for actual boot-time start"
|
|
198
|
+
User units only start at login unless linger is on:
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
sudo loginctl enable-linger "$USER"
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
`usm proxy enable` prints this hint when linger isn't set yet.
|
|
205
|
+
|
|
206
|
+
## How is this different from `usm tunnel socks`?
|
|
207
|
+
|
|
208
|
+
[`usm tunnel socks`](tunnel.md) gives you a SOCKS5 proxy over an **SSH**
|
|
209
|
+
connection — great when you already have SSH access and want all traffic to
|
|
210
|
+
exit through that host. `usm proxy` instead runs a **standalone proxy daemon**:
|
|
211
|
+
it supports HTTP and SOCKS together, an encrypted `ss://` transport for the
|
|
212
|
+
public internet, and — on the client side — Clash **rules** so only the
|
|
213
|
+
traffic you choose is routed through the server.
|
|
@@ -48,6 +48,8 @@ you want from the [Commands](commands/index.md) section.
|
|
|
48
48
|
| Command | What it does |
|
|
49
49
|
| --- | --- |
|
|
50
50
|
| [`usm tunnel`](commands/tunnel.md) | SSH tunnels (local / remote / SOCKS) with state + systemd autostart |
|
|
51
|
+
| [`usm proxy`](commands/proxy.md) | Turn a box into an HTTP/SOCKS (+Shadowsocks) proxy, or a Clash client routing rule-matched traffic through one (mihomo) |
|
|
52
|
+
| [`usm clash`](commands/clash.md) | ClashX-style CLI manager for mihomo: subscriptions, TUN, mode, node selection, system proxy, LAN, live logs, latency tests |
|
|
51
53
|
| [`usm gpu`](commands/gpu.md) | GPU inventory, free-picker, watch, kill (nvidia-smi wrapper) |
|
|
52
54
|
| [`usm port`](commands/port.md) | Show what's on a port; kill the holder |
|
|
53
55
|
| [`usm notify`](commands/notify.md) | Wrap a command and ping ntfy.sh / Telegram / webhook when it exits |
|
|
@@ -67,6 +67,8 @@ nav:
|
|
|
67
67
|
- Commands:
|
|
68
68
|
- Overview: commands/index.md
|
|
69
69
|
- tunnel — SSH tunnels: commands/tunnel.md
|
|
70
|
+
- proxy — HTTP/SOCKS/Clash proxy: commands/proxy.md
|
|
71
|
+
- clash — ClashX-style manager: commands/clash.md
|
|
70
72
|
- gpu — GPU picker/watch: commands/gpu.md
|
|
71
73
|
- port — Port discovery/kill: commands/port.md
|
|
72
74
|
- notify — Long-task pings: commands/notify.md
|
|
@@ -173,8 +173,31 @@
|
|
|
173
173
|
"click>=8.2.1",
|
|
174
174
|
"rich>=13.0"
|
|
175
175
|
],
|
|
176
|
-
"version": "1.0.
|
|
177
|
-
"hash": "sha256:
|
|
176
|
+
"version": "1.0.5",
|
|
177
|
+
"hash": "sha256:70321a5c70f82028df09fe8cdab2ab8b6da9e00dfcc968ee688beebd80e47e52"
|
|
178
|
+
},
|
|
179
|
+
"proxy": {
|
|
180
|
+
"description": "Turn a box into an HTTP/SOCKS (+Shadowsocks) proxy, or a Clash client routing rule-matched traffic through one (mihomo).",
|
|
181
|
+
"path": "proxy.py",
|
|
182
|
+
"requirements": [
|
|
183
|
+
"click>=8.2.1",
|
|
184
|
+
"pyyaml>=6.0.3",
|
|
185
|
+
"rich>=13.0"
|
|
186
|
+
],
|
|
187
|
+
"version": "1.0.1",
|
|
188
|
+
"hash": "sha256:c25c6135837d711225a4fa60159e4d44b7f3724f362fe57da8893a0c4db1bd14"
|
|
189
|
+
},
|
|
190
|
+
"clash": {
|
|
191
|
+
"description": "ClashX-style CLI manager for the mihomo core: subscriptions, TUN, rule/global/direct mode, node selection, system proxy, LAN, live logs, latency tests.",
|
|
192
|
+
"path": "clash.py",
|
|
193
|
+
"requirements": [
|
|
194
|
+
"click>=8.2.1",
|
|
195
|
+
"pyyaml>=6.0.3",
|
|
196
|
+
"requests>=2.32.4",
|
|
197
|
+
"rich>=13.0"
|
|
198
|
+
],
|
|
199
|
+
"version": "1.0.2",
|
|
200
|
+
"hash": "sha256:a8871d90263a5c6454e35c91c224ad26dcf0860255b529606b5a4a453bffebe6"
|
|
178
201
|
}
|
|
179
202
|
}
|
|
180
203
|
}
|