@usex/mikrotik-mcp 4.8.0 → 4.9.0
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.
package/package.json
CHANGED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: setup-v2ray-container-proxy
|
|
3
|
+
title: Run V2Ray/Xray (VLESS·Reality·VMess·Trojan·Shadowsocks) in a MikroTik container and route traffic through it
|
|
4
|
+
description: Deploy an Xray / V2Ray / sing-box client inside a RouterOS /container, wire its VETH into the router, and selectively (or fully) route LAN traffic through the encrypted VLESS-Reality / VMess / Trojan / Shadowsocks / Hysteria tunnel — with device-mode, disk, MTU, DNS-leak and kill-switch handling. For lawful privacy / censorship circumvention on networks you are authorized to use.
|
|
5
|
+
arguments:
|
|
6
|
+
- name: device
|
|
7
|
+
description: Which configured MikroTik to run the proxy container on (config key or label from list_mikrotik_devices). Omit to discover and choose.
|
|
8
|
+
required: false
|
|
9
|
+
- name: protocol
|
|
10
|
+
description: V2Ray-family protocol the tunnel will use — vless-reality (recommended), vless-vision, vmess, trojan, shadowsocks, or (sing-box) hysteria2/tuic. This is configured INSIDE the container image, not on RouterOS.
|
|
11
|
+
required: false
|
|
12
|
+
- name: image
|
|
13
|
+
description: Container image to run (e.g. gritsenko/xray-mikrotik:latest, or a sing-box image). Omit to let you recommend one matching the device architecture and chosen protocol.
|
|
14
|
+
required: false
|
|
15
|
+
- name: scope
|
|
16
|
+
description: What to route through the tunnel — "selective" (only domains/IPs on an address-list, default and recommended) or "all" (default route via the tunnel, with a kill-switch).
|
|
17
|
+
required: false
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
You are deploying a **V2Ray / Xray-core (or sing-box) client inside a MikroTik
|
|
21
|
+
RouterOS `/container`** and routing LAN traffic through its encrypted tunnel. This
|
|
22
|
+
is the _native-RouterOS_ way to run the modern censorship-resistant protocols —
|
|
23
|
+
**VLESS (+Vision/XTLS), VLESS + Reality, VMess, Trojan, Shadowsocks**, and (with a
|
|
24
|
+
sing-box image) **Hysteria2 / TUIC** — that RouterOS has no built-in support for.
|
|
25
|
+
The router runs the client; a remote V2Ray/Xray **server (a VPS you control)** is
|
|
26
|
+
the other end. This flow configures the RouterOS side; the tunnel's crypto
|
|
27
|
+
parameters live in the container image's config/env.
|
|
28
|
+
|
|
29
|
+
**Legality & scope.** This is for **lawful privacy and accessibility** on networks
|
|
30
|
+
and services you are authorized to use — comply with local law and provider terms.
|
|
31
|
+
Confirm the user understands this before proceeding. Treat the remote server
|
|
32
|
+
address, UUIDs, keys and short-ids as **secrets** — never log or echo them back in
|
|
33
|
+
full; mask them in your reports.
|
|
34
|
+
|
|
35
|
+
Target device: {{device}}
|
|
36
|
+
Protocol: {{protocol}}
|
|
37
|
+
Image: {{image}}
|
|
38
|
+
Routing scope: {{scope}}
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 0. Discover the device and confirm it CAN run containers (do this FIRST)
|
|
43
|
+
|
|
44
|
+
- Call `list_mikrotik_devices`; resolve `{{device}}` (never substitute a similar
|
|
45
|
+
name). If omitted, present the inventory and ask which router. Pass `device=` on
|
|
46
|
+
every subsequent call.
|
|
47
|
+
- **Prerequisite check (read-only)** — containers have hard requirements; verify all
|
|
48
|
+
before proposing changes:
|
|
49
|
+
- `get_system_resources` (`device=<name>`) — confirm **architecture** is `arm`,
|
|
50
|
+
`arm64`, or `x86` (**MIPS/SMIPS cannot run containers** — stop and say so), and
|
|
51
|
+
that there is spare **RAM/CPU**.
|
|
52
|
+
- `list_containers` — if it errors, the **`container` package isn't installed**.
|
|
53
|
+
- Confirm an **external disk** (USB/NVMe, ext4) exists for the container root-dir —
|
|
54
|
+
running container images off internal flash wears it out fast. Check with
|
|
55
|
+
`run_routeros_command` `/disk print`.
|
|
56
|
+
- **Two prerequisites need out-of-band action — flag, do NOT silently attempt:**
|
|
57
|
+
1. **device-mode = container=yes.** Enabling it (`/system/device-mode/update
|
|
58
|
+
mode=advanced container=yes`) requires **physical confirmation** (press the
|
|
59
|
+
reset button or power-cycle within the timeout). You cannot complete this
|
|
60
|
+
remotely — tell the user they must do the physical step.
|
|
61
|
+
2. **Installing the `container` package** requires uploading the `.npk` and
|
|
62
|
+
`/system/package/apply-changes` (7.18+) which **reboots** the router. Get
|
|
63
|
+
explicit approval; note the device will drop offline during reboot.
|
|
64
|
+
|
|
65
|
+
Do not proceed to container creation until architecture, disk, package, and
|
|
66
|
+
device-mode are all satisfied.
|
|
67
|
+
|
|
68
|
+
## 1. Choose image and protocol
|
|
69
|
+
|
|
70
|
+
- **Protocol** (`{{protocol}}`): recommend **VLESS + Reality** as the default —
|
|
71
|
+
Reality forges the TLS handshake of a real public site (no certificate to obtain,
|
|
72
|
+
no domain to burn, strongest anti-DPI of the family). VLESS+Vision/XTLS, VMess,
|
|
73
|
+
Trojan, and Shadowsocks are alternatives; sing-box images add Hysteria2/TUIC
|
|
74
|
+
(QUIC-based, good on lossy/throttled links). The choice is realised in the
|
|
75
|
+
container's config — RouterOS just carries the encapsulated traffic.
|
|
76
|
+
- **Image** (`{{image}}`): pick one matching the device architecture (map:
|
|
77
|
+
`arm→linux/arm/v7`, `arm64→linux/arm64`, `x86→linux/amd64`). Community images
|
|
78
|
+
(e.g. `gritsenko/xray-mikrotik`) bundle **xray-core + tun2socks** so the
|
|
79
|
+
container's VETH acts directly as a routable gateway — simplest. Otherwise the
|
|
80
|
+
**two-container** pattern (below) is the general form. **Read the specific image's
|
|
81
|
+
README for its exact env-var names** — they differ per image; do not assume.
|
|
82
|
+
- **RouterOS local-import caveat:** `add_container remote_image=` pulls from a
|
|
83
|
+
registry (needs `set_container_config registry-url=... tmpdir=disk1/pull` and
|
|
84
|
+
internet). A local `.tar` must be **single-layer, uncompressed, Docker-v1** — most
|
|
85
|
+
people pull from a registry.
|
|
86
|
+
|
|
87
|
+
## 2. Two deployment shapes (pick one, explain to the user)
|
|
88
|
+
|
|
89
|
+
**A — All-in-one image (recommended, simplest).** One container running xray-core +
|
|
90
|
+
tun2socks. Its VETH IP becomes the gateway you route through. Example env schema
|
|
91
|
+
(gritsenko/xray-mikrotik — verify against the image):
|
|
92
|
+
`SERVER_ADDRESS`, `SERVER_PORT`, `USER_ID`, `ENCRYPTION`, `FINGERPRINT_FP`,
|
|
93
|
+
`SERVER_NAME_SNI`, `PUBLIC_KEY_PBK`, `SHORT_ID_SID`.
|
|
94
|
+
|
|
95
|
+
**B — Two-container (general, more control).** Container 1 = xray-core exposing a
|
|
96
|
+
**SOCKS5** inbound (e.g. `172.17.0.2:1080`); Container 2 = **tun2socks /
|
|
97
|
+
hev-socks5-tunnel** turning that SOCKS5 into a routable gateway on its own VETH.
|
|
98
|
+
Typical env — xray: `REMOTE_ADDRESS,REMOTE_PORT,ID,FLOW,PUBLIC_KEY,SHORT_ID,
|
|
99
|
+
SERVER_NAME`; tun: `SOCKS5_ADDR=172.17.0.2,SOCKS5_PORT=1080,LOCAL_ROUTE` (so LAN
|
|
100
|
+
subnets return via the router, not the tunnel). _Note: original tun2socks has arm64
|
|
101
|
+
issues — use an arm64-built image._
|
|
102
|
+
|
|
103
|
+
## 3. Container networking (VETH + NAT + DNS)
|
|
104
|
+
|
|
105
|
+
There is **no dedicated VETH tool** — create it with `run_routeros_command`
|
|
106
|
+
(approve each raw command). Example for shape A on a /30:
|
|
107
|
+
|
|
108
|
+
- `/interface veth add name=veth-xray address=172.18.20.6/30 gateway=172.18.20.5`
|
|
109
|
+
- `add_ip_address` `address=172.18.20.5/30 interface=veth-xray` (router side).
|
|
110
|
+
- `create_nat_rule` `chain=srcnat action=masquerade out-interface=veth-xray` (so the
|
|
111
|
+
container reaches the internet / the remote server).
|
|
112
|
+
- Container `dns` = the router's veth IP (`172.18.20.5`) or a resolver you trust.
|
|
113
|
+
(Shape B: put both VETHs on a `containers` bridge, `172.17.0.1/24` gateway.)
|
|
114
|
+
|
|
115
|
+
## 4. Create and start the container
|
|
116
|
+
|
|
117
|
+
- If pulling from a registry: `set_container_config` `registry-url=https://registry-1.docker.io tmpdir=disk1/pull`.
|
|
118
|
+
- Env vars: either inline via `add_container` `env="SERVER_ADDRESS=...,USER_ID=..."`
|
|
119
|
+
(7.21+) or as a named list with `add_container_env` (`envlists=`). **Mask the
|
|
120
|
+
secret values in anything you print back.**
|
|
121
|
+
- `add_container` (`device=<name>`) — `remote_image={{image}}`, `interface=veth-xray`,
|
|
122
|
+
`root_dir=disk1/xray`, `dns=172.18.20.5`, `logging=yes`, `start_on_boot=yes`,
|
|
123
|
+
`hostname=xray`, and the env.
|
|
124
|
+
- `start_container`; then `get_container` / `list_containers` until it shows
|
|
125
|
+
**running**, and read startup output with the container-log (it must show a
|
|
126
|
+
successful outbound handshake to your server before routing anything through it).
|
|
127
|
+
|
|
128
|
+
## 5. Route traffic through the tunnel
|
|
129
|
+
|
|
130
|
+
**Selective (`scope=selective`, recommended)** — only chosen destinations go through
|
|
131
|
+
the proxy; everything else uses the normal WAN (fast, low-risk, defeats geo-blocks
|
|
132
|
+
for the sites that need it):
|
|
133
|
+
|
|
134
|
+
1. `add_address_list_entry` — build a list `via_proxy` of the domains/IPs to tunnel
|
|
135
|
+
(RouterOS resolves domain entries to IPs automatically).
|
|
136
|
+
2. `add_routing_table` — `name=proxy fib`.
|
|
137
|
+
3. `create_mangle_rule` — `chain=prerouting action=mark-routing
|
|
138
|
+
new-routing-mark=proxy dst-address-list=via_proxy passthrough=no`
|
|
139
|
+
(add `src-address=<LAN>` to scope to LAN clients; exclude the router's own/ the
|
|
140
|
+
container subnet to avoid loops).
|
|
141
|
+
4. `add_route` — `dst-address=0.0.0.0/0 gateway=172.18.20.6 routing-table=proxy`
|
|
142
|
+
(gateway = the container's VETH IP, shape A; the tun container's IP, shape B).
|
|
143
|
+
|
|
144
|
+
**All traffic (`scope=all`)** — default route via the tunnel. Same routing table but
|
|
145
|
+
mark all LAN traffic (or set the container gateway as the main default). **Mandatory
|
|
146
|
+
kill-switch:** add a low-priority `forward` **drop** for the LAN when the tunnel
|
|
147
|
+
interface is down, so a container crash can't silently leak traffic out the clear
|
|
148
|
+
WAN. Also pin a **higher-priority route to the remote server's IP via the real WAN**
|
|
149
|
+
so the tunnel's own packets don't recurse into itself.
|
|
150
|
+
|
|
151
|
+
## 6. DNS-leak & MTU handling
|
|
152
|
+
|
|
153
|
+
- **DNS leaks:** if clients query a public resolver directly, the destination is
|
|
154
|
+
exposed even though the payload is tunnelled. Redirect LAN DNS (dst-nat UDP/TCP 53
|
|
155
|
+
to the router or the container's resolver) so lookups for proxied domains resolve
|
|
156
|
+
through the tunnel, or run the resolver inside/behind the container.
|
|
157
|
+
- **MTU/MSS:** encapsulation shrinks usable MTU — add a `create_mangle_rule`
|
|
158
|
+
`chain=forward action=change-mss new-mss=clamp-to-pmtu tcp-flags=syn` (and/or lower
|
|
159
|
+
the veth MTU). This is the #1 "handshake works, big pages hang" cause.
|
|
160
|
+
|
|
161
|
+
## 7. Firewall — safely
|
|
162
|
+
|
|
163
|
+
Under Safe Mode (`enable_safe_mode` `device=<name>` → edits → verify →
|
|
164
|
+
`commit_safe_mode`): allow the container subnet outbound, keep the masquerade from
|
|
165
|
+
step 3, and (scope=all) install the kill-switch drop. Do not expose the container's
|
|
166
|
+
SOCKS5 port to the WAN.
|
|
167
|
+
|
|
168
|
+
## 8. Verify end to end
|
|
169
|
+
|
|
170
|
+
- `get_container` shows **running**; the container log shows a completed handshake to
|
|
171
|
+
your server (no repeated dial errors).
|
|
172
|
+
- From a **marked** LAN source, check the **egress IP** changed: fetch an "what is my
|
|
173
|
+
IP" service from a proxied client (or `run_routeros_command` a `/tool fetch` bound
|
|
174
|
+
to the proxy path) — it should show the **VPS** IP, not the local WAN IP.
|
|
175
|
+
- Confirm a **non-proxied** destination still exits the normal WAN (selective scope).
|
|
176
|
+
- `ping`/`traceroute` a proxied target; test a large HTTPS page (MTU sanity).
|
|
177
|
+
- Reboot-persistence: `start_on_boot=yes` and the routing rules survive a reboot.
|
|
178
|
+
|
|
179
|
+
## 9. Family notes, hardening & honest caveats
|
|
180
|
+
|
|
181
|
+
- **VLESS + Reality**: no cert/domain needed; set a believable `SERVER_NAME_SNI`
|
|
182
|
+
(a real, unrelated HTTPS site the censor won't block) and matching public-key/
|
|
183
|
+
short-id from the server. Strongest default against active-probing DPI.
|
|
184
|
+
- **VMess/Trojan/Shadowsocks**: pair with TLS/WebSocket/gRPC transports on 443 for
|
|
185
|
+
camouflage; plain Shadowsocks is weaker against modern DPI.
|
|
186
|
+
- **Hysteria2/TUIC** (sing-box image): QUIC/UDP — great on lossy or throttled links,
|
|
187
|
+
but blocked where UDP is throttled.
|
|
188
|
+
- **Trust**: you are running a third-party image with your keys and all your traffic.
|
|
189
|
+
Prefer images you can inspect/build; pin a digest; keep it updated.
|
|
190
|
+
- **Reality/DPI is an arms race** — never present it as a guarantee. Keep a fallback
|
|
191
|
+
(a second protocol/port, or an SSTP/OpenVPN-443 transport per
|
|
192
|
+
`setup-sstp-tunnel-between-sites`).
|
|
193
|
+
- **Resource reality**: containers are RAM/CPU/disk heavy on small routers; on very
|
|
194
|
+
low-end boards run the client on a VPS/box and point the router at it instead.
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
Report: device, architecture, image + protocol, VETH/NAT, container status, the
|
|
199
|
+
routing-table + mangle + route rules and the address-list scope, DNS/MTU/kill-switch
|
|
200
|
+
handling, and the verification results (egress-IP proof) — with **all secrets
|
|
201
|
+
masked**, and a note of every `run_routeros_command` step used (VETH, device-mode).
|
|
202
|
+
Flag the physical device-mode step and any reboot explicitly. Never apply changes the
|
|
203
|
+
user hasn't approved.
|