Sign inSign up

ariankeshavarz/xray

By ariankeshavarz

•Updated 1 day ago

Unmodified Xray Core with network, system, and Python debugging tools.

Image
Networking
0

267

ariankeshavarz/xray repository overview

⁠Xray Core Debug

A production-oriented Xray Core image based on Alpine Linux with an extended network, system, and Python debugging toolkit.

This image is intended for troubleshooting network connectivity directly from the same container or Pod where Xray is running.

⁠Important: Xray Core Is Not Modified

This image does not modify, patch, recompile, or otherwise alter Xray Core.

The Xray binary is copied directly from the official Xray Core image:

The only changes made by this image are the addition of debugging tools, Python packages, Geo/routing rule files, and the non-root runtime setup described below.

The Xray binary itself is used as provided by the upstream project.

⁠Base Image

FROM alpine:3.22

The image is based on:

  • Alpine Linux 3.22
  • Xray Core 26.9.9

⁠Geo / Routing Data

This image bundles four data files from the following project:

Iran-v2ray-rules

https://github.com/Chocolate4U/Iran-v2ray-rules⁠

The project provides enhanced V2Ray/Xray routing rules with Iranian domains and security/ad-blocking focused rules.

⁠Included files
⁠GeoSite
geosite.dat

Source:

https://raw.githubusercontent.com/Chocolate4U/Iran-v2ray-rules/release/geosite.dat⁠

Used by Xray for domain-based routing rules.

⁠GeoIP
geoip.dat

Source:

https://raw.githubusercontent.com/Chocolate4U/Iran-v2ray-rules/release/geoip.dat⁠

Used by Xray for IP-based routing rules.

⁠Security Rules
security.dat

Source:

https://raw.githubusercontent.com/Chocolate4U/Iran-v2ray-rules/release/security.dat⁠

Contains security-oriented routing data.

⁠Security IP Rules
security-ip.dat

Source:

https://raw.githubusercontent.com/Chocolate4U/Iran-v2ray-rules/release/security-ip.dat⁠

Contains IP-based security/routing data.

The files are stored in:

/usr/local/bin

and Xray uses:

XRAY_LOCATION_ASSET=/usr/local/bin

⁠What's Included

⁠Xray Core
  • Xray Core 26.9.9
  • Official upstream Xray binary
  • GeoIP / GeoSite assets
  • Security routing assets
  • XRAY_LOCATION_ASSET=/usr/local/bin
⁠Network Diagnostics
  • curl
  • wget
  • dig
  • nslookup
  • ping
  • traceroute
  • mtr
  • ip
  • ss
  • nc
  • openssl
  • tcpdump
  • iftop
  • iperf3
⁠System & Process Diagnostics
  • ps
  • top
  • free
  • vmstat
  • btop
  • htop
  • procps
⁠Shell & File Utilities
  • Bash
  • Coreutils
  • Findutils
  • grep
  • sed
  • awk
  • tar
  • unzip
  • gzip
  • tree
  • less
  • vim
  • nano
⁠JSON & Data Utilities
  • jq
⁠Python

Python 3 with:

  • requests
  • urllib3
  • httpx
  • aiohttp
  • psutil
  • rich
  • click
  • pyyaml
  • python-dateutil
  • dnspython
  • netaddr

⁠Network Debugging Capabilities

The image can be used to troubleshoot:

  • DNS resolution
  • ICMP connectivity
  • Routing and path changes
  • Packet loss
  • TCP connectivity
  • TLS connectivity
  • HTTP/HTTPS connectivity
  • Network throughput
  • Active connections
  • Listening ports
  • Interface traffic
  • Packet capture
⁠DNS
dig google.com

nslookup google.com
⁠ICMP
ping 1.1.1.1
⁠Routing
ip route

mtr -r -c 10 1.1.1.1

traceroute 1.1.1.1
⁠TCP
nc -zv example.com 443

ss -lntup
⁠TLS
openssl s_client \
  -connect example.com:443 \
  -servername example.com
⁠HTTP / HTTPS
curl -Iv https://example.com
⁠Packet Capture
tcpdump -ni eth0
⁠Interface Traffic
iftop -i eth0
⁠Network Throughput
iperf3 -c <server>

Reverse throughput testing:

iperf3 -c <server> -R

⁠Packet Capture Capabilities

tcpdump and iftop are configured with the following file capabilities:

cap_net_raw
cap_net_admin

This allows these tools to request the capabilities required for packet and interface-level diagnostics while the main Xray process runs as a non-root user.

For Docker environments, start the container with:

cap_add:
  - NET_ADMIN
  - NET_RAW

Example:

docker run --rm -it \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  ariankeshavarz/xray:26.9.9

Kubernetes and KaaS environments may additionally restrict or remove these capabilities at runtime.

⁠Runtime Security

The image runs Xray as a dedicated non-root user:

xray

The Xray configuration and log directories are owned by this user:

/usr/local/etc/xray
/var/log/xray

The default runtime is:

USER xray
WORKDIR /usr/local/etc/xray
ENTRYPOINT ["/usr/local/bin/xray"]
CMD ["-confdir", "/usr/local/etc/xray"]

No root wrapper is used for Xray startup.

⁠Python Network Troubleshooting

Python can be used directly inside the container for custom diagnostics, automation, and troubleshooting.

Example:

python3

Installed networking and system libraries include:

import requests
import urllib3
import httpx
import aiohttp
import psutil
import dns
import netaddr

⁠Docker Usage

Pull the image:

docker pull ariankeshavarz/xray:26.9.9

Run:

docker run --rm -it \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  ariankeshavarz/xray:26.9.9

The default Xray configuration directory is:

/usr/local/etc/xray

Logs:

/var/log/xray

⁠Docker Compose

Example:

services:
  xray:
    image: ariankeshavarz/xray:26.9.9

    cap_add:
      - NET_ADMIN
      - NET_RAW

    volumes:
      - ./config:/usr/local/etc/xray
      - ./logs:/var/log/xray

    restart: unless-stopped

⁠Kubernetes / KaaS

The image is useful for troubleshooting Xray from inside the same Pod and network namespace.

Example:

kubectl exec -it <pod-name> -- /bin/bash

Once inside the Pod:

dig example.com

mtr -r -c 10 example.com

ss -lntup

tcpdump -ni eth0

iftop -i eth0

iperf3 -c <server>

This avoids deploying a separate troubleshooting container just to investigate DNS, routing, packet loss, TCP, TLS, or throughput issues.

Note: Kubernetes/KaaS security policies may prevent packet capture or interface-level diagnostics even when the required tools are present in the image.

⁠Tested

The following components have been tested inside the image:

ComponentStatus
Xray Core 26.9.9✅
Python 3✅
requests✅
urllib3✅
httpx✅
aiohttp✅
psutil✅
PyYAML✅
dnspython✅
netaddr✅
curl✅
wget✅
DNS / dig✅
nslookup✅
ping✅
traceroute✅
mtr✅
ip / iproute2✅
ss✅
netcat✅
TLS / OpenSSL✅
HTTP / HTTPS✅
tcpdump✅
iftop✅
iperf3✅
jq✅
btop✅
htop✅
vim✅
nano✅
⁠Real Network Tests

The image has been tested with:

  • DNS resolution against public DNS
  • ICMP connectivity
  • MTR route analysis
  • HTTP/HTTPS requests
  • TLS connections
  • TCP connectivity
  • Packet capture with tcpdump
  • Interface monitoring with iftop
  • Network throughput testing with iperf3

Example observed throughput:

iperf3 reverse test
~1.52 Gbit/s

⁠Why This Image?

A minimal Xray image is usually enough when everything works.

The problem starts when the container itself becomes the thing you need to troubleshoot.

Without debugging tools, you may end up with:

Xray container
      ↓
Network problem
      ↓
kubectl exec
      ↓
No curl
No dig
No tcpdump
No mtr
No iperf3

This image provides the troubleshooting toolkit directly inside the same container and network namespace.

It is useful for:

  • Kubernetes
  • KaaS
  • Docker
  • HA deployments
  • NOC troubleshooting
  • Network path debugging
  • Connectivity investigations
  • Packet-loss analysis
  • TCP/TLS troubleshooting
  • Performance testing

The goal is simple:

Keep the original Xray Core unchanged, while making the container much more useful when something goes wrong.

⁠Changelog

⁠26.9.9

⁠Base
  • Built on Alpine Linux 3.22.
  • Xray Core 26.9.9 is copied directly from the official upstream image ghcr.io/xtls/xray-core:26.9.9.
  • No changes were made to the Xray Core binary itself.
  • No custom Xray build or patching is used.
⁠Added Network Tools
  • curl
  • wget
  • dig / nslookup
  • ping
  • traceroute
  • mtr
  • ip / ss
  • netcat
  • OpenSSL
  • tcpdump
  • iftop
  • iperf3
⁠Added System Tools
  • procps
  • btop
  • htop
  • coreutils
  • findutils
  • grep
  • sed
  • gawk
  • tar
  • unzip
  • gzip
  • tree
  • vim
  • nano
  • less
  • jq
⁠Added Python
  • Python 3
  • requests
  • urllib3
  • httpx
  • aiohttp
  • psutil
  • rich
  • click
  • pyyaml
  • python-dateutil
  • dnspython
  • netaddr
⁠Added Geo / Security Data

Bundled from:

https://github.com/Chocolate4U/Iran-v2ray-rules⁠

Included:

  • geoip.dat
  • geosite.dat
  • security.dat
  • security-ip.dat
⁠Runtime / Security
  • Xray runs as a non-root xray user.
  • tcpdump and iftop receive the required file capabilities.
  • Xray keeps its original entrypoint and command model.
  • Debugging tools are not executed during Xray startup.
  • Runtime network capabilities remain controlled by the container runtime.
⁠Tested
  • Xray startup
  • Python imports
  • DNS resolution
  • ICMP connectivity
  • MTR route analysis
  • TCP connectivity
  • TLS connectivity
  • HTTP/HTTPS connectivity
  • Packet capture with tcpdump
  • Interface monitoring with iftop
  • Network throughput with iperf3

Tag summary

Content type

Image

Digest

sha256:18063137c…

Size

80.3 MB

Last updated

1 day ago

docker pull ariankeshavarz/xray:26.9.9