killdns/xray-socks5-router repository overview

⁠Xray SOCKS5 Router

GitHub source and full documentation⁠ · Russian documentation⁠

A multi-platform Docker image that provides an L3 gateway for routed IPv4 traffic through Xray and a HevSocks5Server frontend with TCP CONNECT and UDP ASSOCIATE.

Platforms: linux/amd64 (x86_64), linux/arm64 (AArch64), and linux/arm/v7 (32-bit ARMv7, including compatible MikroTik devices).

⁠Routing modes

tproxy is the default. tun avoids netfilter interception and is intended for RouterOS kernels that do not expose the TPROXY target to containers.

This is an L3 next hop, not an L2 bridge. Route selected networks or a policy table to the container IP. It does not bridge VLANs, Ethernet frames, broadcast domains, or Docker networks.

routed client/network
        |
        | iif policy rule -> table 100
        v
xray0 (Xray TUN inbound) -> Xray outbound

container-local process except Xray
        |
        | inverted Xray-UID rule -> table 100
        v
xray0 -> Xray outbound

SOCKS5 client -> HevSocks5Server :1080
        |
        | process-UID policy rule -> table 200
        v
xray0 -> Xray outbound

Xray runs under a dedicated UID with only ambient CAP_NET_ADMIN. All other container-local traffic enters TUN, while Xray's own upstream sockets keep using the main table to avoid a loop.

In tproxy mode, SOCKS traffic instead re-enters Xray through an internal VRF/veth loop and the TPROXY inbound. That loop is not a VLAN or Docker network, and TUN mode does not create it.

⁠Quick start

docker pull killdns/xray-socks5-router:0.3.0

TUN example:

services:
  gateway:
    image: killdns/xray-socks5-router:0.3.0
    cap_add: [NET_ADMIN, NET_RAW]
    devices:
      - /dev/net/tun:/dev/net/tun
    sysctls:
      net.ipv4.ip_forward: "1"
      net.ipv4.conf.all.rp_filter: "0"
      net.ipv4.conf.default.rp_filter: "0"
    environment:
      VLESS_URI: ${VLESS_URI}
      ROUTING_MODE: tun
      SOCKS_ALLOW_NO_AUTH: "1"

On RouterOS, set ROUTING_MODE=tun in the envlist and confirm that the container sees /dev/net/tun.

⁠Connection configuration

Set VLESS_URI to generate an ephemeral Xray configuration automatically at container startup. The selected routing-mode and TUN/TPROXY environment values are applied to the generated config. VLESS_URI takes precedence when a mounted XRAY_CONFIG is also present.

The URI is passed to the embedded generator through stdin, is not logged, and is removed from Xray's child-process environment. It is still visible to Docker administrators through container inspection and remains stored in a RouterOS envlist. Use a read-only mounted config.json instead when that exposure is not acceptable.

RouterOS example:

/container/envs/add list=xray-router key=VLESS_URI value="vless://..."
/container/envs/add list=xray-router key=ROUTING_MODE value=tun

The host-side generator remains available when a file is preferred.

The GitHub repository includes a Python 3.10+ generator for one vless:// URI:

python3 tools/vless_to_config.py \
  --uri-file ./vless-link.txt \
  --routing-mode tun \
  --tun-interface xray0 \
  --tun-mtu 1400 \
  --output ./config/config.json

Use --routing-mode tproxy for TPROXY. With ROUTING_MODE=tun, the entrypoint can also convert an existing TPROXY dokodemo-door inbound to an ephemeral TUN config under /run; the mounted file remains unchanged.

Never commit the URI or generated configuration.

⁠Environment reference

Without credentials, startup fails unless SOCKS_ALLOW_NO_AUTH=1 is explicitly set. Never expose unauthenticated SOCKS to an untrusted network.

The image requires NET_ADMIN and NET_RAW, not privileged mode. Mount the Xray config read-only. TUN is fail-closed for traffic selected by its policy table. This release configures IPv4 transit routing; IPv6 transit is out of scope.

See the GitHub README⁠ for full examples, tests, source code, and upstream links.