dandri/mycelium
1
0
Fork 0
mirror of https://github.com/threefoldtech/mycelium.git synced 2026-03-29 07:39:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add proxy docs

Browse Source 
Signed-off-by: Lee Smet <lee.smet@hotmail.com>
This commit is contained in:
Lee Smet
2025-09-18 15:38:38 +02:00
parent 93dd8452a5
commit 152ee4d297
2 changed files with 81 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@@ -158,6 +158,17 @@ Messages can be categorized by topics, which can be configured with whitelisted
For detailed information on how to configure topics, see the [Topic Configuration Guide](/docs/topic_configuration.md).
use the message system, see [the message docs](/docs/message.md).
## SOCKS5 Proxy
Mycelium can expose a local SOCKS5 listener and forward all traffic to a remote SOCKS5 server running on a peer in the overlay. This enables applications to use a local proxy while the actual SOCKS handshake and traffic termination happen on the selected remote node.
- Discovery: the node can probe peers for open SOCKS5 services on port 1080 (no-auth). Start/stop scanning via the API (startProxyProbe / stopProxyProbe).
- Connect: choose the best discovered proxy automatically or connect to a specific remote with connectProxy(remote?).
- Local listener: once connected, Mycelium binds [::]:1080 and proxies connections bidirectionally to the remote SOCKS5 server.
- Disconnect: stop forwarding with disconnectProxy.
See the detailed guide in [docs/proxy.md](docs/proxy.md). API references: [docs/api.yaml](docs/api.yaml) and [docs/openrpc.json](docs/openrpc.json).
## Inspecting node keys
Using the `inspect` subcommand, you can view the address associated with a public key. If no public key is provided, the node will show

70
docs/proxy.md Normal file
View File

@@ -0,0 +1,70 @@
# SOCKS5 proxy
Mycelium can forward a local TCP port to a remote SOCKS5 server running on another node in the overlay. This lets applications on your machine use a local SOCKS5 endpoint while all traffic to the SOCKS server is transparently tunneled over the Mycelium network to a selected peer.
High level:
- Discovery: the node periodically probes known peers for an open SOCKS5 service on port 1080.
- Connect: you can connect to the “best” discovered proxy automatically, or to a specific remote address.
- Forwarding: once connected, the node binds a local listener on [::]:1080 and forwards all connections bidirectionally to the chosen remote SOCKS5 service.
- Disconnect: stop forwarding and clear the target.
## How it works
- Discovery and probe cycle
- Interval: every 60s the node scans the currently selected routes and attempts a TCP connection to each peer’s address on port 1080.
- Probe handshake: it sends a SOCKS5 client greeting [0x05, 0x01, 0x00] and expects the server choice [0x05, 0x00] (no authentication).
- Classification:
- Valid: responds with version 5 and method 0x00 (no auth).
- AuthenticationRequired: responds with 0xFF (no acceptable methods). These proxies are discovered but not auto-selected.
- NotAProxy / NotListening: anything else or no response within 5s.
- The discovery status is cached per IPv6 address.
- Selecting and connecting
- Auto-select: if you call “connect” without a remote, Mycelium races all “Valid” proxies and picks the one that successfully responds first to the SOCKS5 greeting.
- Explicit remote: you can provide a specific socket address (e.g. [407:…]:1080). In this case the system does not probe or validate it first; it will forward to that destination directly.
- Local listener and forwarding
- Bind: after connecting, the node spawns a TCP listener on [::]:1080.
- Behavior: each inbound connection is proxied bidirectionally to the chosen remote (“copy_bidirectional”). The local node itself does not implement the SOCKS protocol; it merely forwards bytes to the remote SOCKS5 server. From the application perspective, talking to localhost:1080 works because the real SOCKS server is at the remote node.
- Lifetime: all active forwarded streams are cancelled when you disconnect or when the node is asked to stop.
- Disconnect
- Cancels the proxy listener and all active streams, and clears the selected remote target.
## Using the local SOCKS endpoint
Once connected, point your applications to the local listener:
- Host: 127.0.0.1 or ::1
- Port: 1080
- Protocol: SOCKS5
Because the local listener just forwards bytes to the remote SOCKS server:
- If the remote SOCKS server requires authentication, your application must authenticate; the local node does not terminate SOCKS.
- Auto-selection only considers “no-authentication” servers; to use an auth-required proxy, connect explicitly with the remote address.
## Security considerations
- Binding to all interfaces: the listener binds to [::]:1080 (all interfaces). This can expose the SOCKS endpoint to your local network. Use OS firewalling to restrict access to localhost only if desired.
- Trust model: SOCKS5 is terminated on the remote node you connect to. Ensure you trust that node and understand the network path from it to the ultimate destinations.
- Discovery bandwidth: probes are lightweight (short handshake) and run every 60s. You can stop probing to reduce background activity.
## Limitations and notes
- Fixed local port: the listener uses port 1080 and cannot be changed via the current API. If another process occupies 1080, the listener fails to start.
- IPv6 bind: binding is performed on IPv6 “::”. Whether this socket also accepts IPv4-mapped connections depends on OS configuration; connecting to [::1]:1080 (or 127.0.0.1:1080 on systems that map v4) is recommended.
- Auto-selection filters: only “Valid” (no-auth) proxies are candidates for auto-selection. “AuthenticationRequired” proxies are discovered and listed, but not auto-picked.
- Forwarding only: the node does not implement SOCKS5 locally; it forwards your application’s SOCKS conversation to the remote SOCKS server.
## Troubleshooting
- “Could not bind TCP listener” on port 1080
- Another process is using the port. Stop that process or reconfigure your environment. The local port is fixed in this version.
- “No valid proxy available or connection failed”
- The network has no discovered “Valid” proxies. Start probing, verify connectivity to peers, or connect to a specific known remote address explicitly.
- Local apps cannot reach the listener
- Ensure you are connecting to ::1:1080 or 127.0.0.1:1080, and that firewall rules allow local connections. Check logs to confirm that the listener started successfully.
- Authentication-required remote
- Auto-select won’t pick it. Use explicit connect with its socket address and configure your app to authenticate over SOCKS as needed.