Skip to content

Xray Checker

The Xray Checker module sets up external node monitoring: the checker lives on a separate server, fetches a real subscription from the panel and walks every proxy the way a regular user would. A dead node, a datacenter failure or a suffocating network is visible from the outside at once, and the status page and Telegram bot report it to subscribers.

The module assembles two open-source projects:

Checker

Walks every proxy of the subscription on a schedule and decides whether the host is alive, sending the result into metrics and onto the status page.

Intervalfrom 30 seconds, 300 by defaultMethodsIP, HTTP status, downloadMetricsPrometheus on 127.0.0.1:2112

Status page and Telegram bot

The public state page and the Telegram bot living in it: host uptime, incidents, maintenance, alerts and subscription management.

Domaine.g. status.example.comNo domainlocalhost or an SSH tunnelCommands/start, then /menuAlertsto chats by ID from the settingsDatahistory and secret.key in a Docker volume
paneluser · xray-checkersubscriptionXray Checkerseparate server · Dockerchecker127.0.0.1:2112status page:8080Telegram botalertschecks via proxynode · de-fra-01every host of the subnode · nl-ams-02checked from outsideTelegramalerts · /menuthe checker probes nodes from the outside, like a regular user

The checker gets its subscription one of two ways:

  • Dedicated panel user (recommended). The module creates a xray-checker user in the panel, adds it to the internal groups and takes its subscription: new nodes enter monitoring on their own.
  • Manual URL. Any https://... subscription link works. When the node set changes, you renew the address yourself.

Every cycle the checker walks the proxies of the subscription with the chosen method and records the result into metrics. The status page shows the history and the bot sends alerts.

  • Free ports 2112, 8080 and 8081.
  • Docker: when it is missing, the module offers to install the server components itself.
  • A domain for the public status page, for example status.example.com. Without a domain the page is reachable only from the server or through an SSH tunnel.

Run on the monitoring server:

root@server: ~
remnawave_reverse
  1. In the main menu select 8:

    root@server: ~
    REMNAWAVE REVERSE-PROXY by eGames
    Wiki: https://wiki.egam.es/
    
    4.Node extensions (templates, plugins, core)
    
    8.Xray Checker — subscription monitoring
    
    0.Exit
    
    Select action (0-13):
  2. The module menu opens. Nothing is installed yet, so it holds a single entry:

    root@server: ~
    Xray Checker
     Details in the wiki: https://wiki.egam.es/configuration/xray-checker
    
     Xray Checker: not installed
    
    1.Install
    
    0.Exit
    
    Select action (0-1): 
  3. The install starts with the red separate-server reminder, then asks for the deployment mode:

    root@server: ~
    Installing Xray Checker
    Monitoring must be installed on a separate server.
    The checker probes the nodes from the outside, like a regular user, so it detects not only a node failure but also datacenter or network problems
    
    Deployment mode
    
    1.Checker + status page (recommended)
    2.Checker only
    0.Exit
    
    Select action (0-2): 
  4. Choose which page becomes public:

    root@server: ~
    Which page will be public
    
    1.Status page by Mrvibecodic (recommended)
        Telegram bot: alerts, incidents, maintenance, subscription management
    2.The checker's own web UI by kutovoys
        Proxy tiles and Prometheus metrics behind basic auth (login and password generated)
    0.Exit
    
    Select action (0-2): 
  5. Subscription source. When this server runs the panel with its subscription page, auto wiring is available:

    root@server: ~
    Subscription source
    
    1.Dedicated panel user "xray-checker" (recommended: the subscription picks up new nodes automatically)
    2.Enter a subscription URL manually
    0.Exit
    
    Select action (0-2): 1
    [ * ] Creating the dedicated panel user "xray-checker"...
    [ ✓ ] User "xray-checker" created in the panel.
    [ * ] Adding the user to the panel's internal squads...

    With the manual variant the module asks for the Subscription URL (https://...): and validates the address.

  6. Telegram bot setup: a token from @BotFather, admin IDs and alert chat IDs. Every step is skippable with Enter, and the bot is optional:

    root@server: ~
    Telegram bot token to manage the page (Enter - no bot, page only): 7481203945:AAH3k2QvLpR9tXmZwYb5C1dE
    Bot admin IDs, comma-separated (e.g. 123456789): 123456789
    Alert chat IDs, comma-separated (skippable - Enter): 
    Checking the bot token...
    Sending a test message to the first admin...
    The bot responds.
  7. Check interval and method:

    root@server: ~
    Check interval in seconds (default 300): 
    
    Check method
    
    1.IP: light request through every proxy (recommended)
    2.HTTP status: response code check
    3.Test file download (~1 MB per proxy per cycle!)
    0.Exit
    
    Select action (0-3): 1
  8. The public page domain, then the install runs on its own:

    root@server: ~
    Status page domain by Mrvibecodic (e.g. status.example.com, Enter - localhost only): status.example.com
    [ * ] Writing the config to /opt/xray-checker...
    [ * ] Downloading images (Docker Hub / ghcr.io)...
    [ * ] Starting Xray Checker...
    [ * ] Waiting for the containers to answer...
    [ ✓ ] The checker answers on 127.0.0.1:2112.
    
    === Xray Checker is ready ===
    
    Status page:
    https://status.example.com
    
    The subscription of user "xray-checker" is wired automatically. Others can be added via the bot (/menu → Subscriptions); they replace the automatic one. Subscription for the bot:
    https://sub.example.com/d41d8cd98f00b204e9800998ecf8427e
    
    Write /start and /menu to the bot: page management, alerts, incidents, maintenance.

When the test message to the bot is not delivered, that is normal the first time: Telegram forbids bots from writing first. Send the bot /start (then /menu), after which it can answer and send alerts.

After installation the menu shows the state, the public address and the authors:

root@server: ~
Xray Checker
 Details in the wiki: https://wiki.egam.es/configuration/xray-checker

 Xray Checker: running
 Public page: https://status.example.com
 Xray Checker by kutovoys (github.com/kutovoys/xray-checker) · status page by Mrvibecodic (github.com/Mrvibecodic/xray-checker-statuspage)

1.Status and recent logs
2.Restart
3.Update images

4.Configure the Telegram bot
5.Uninstall

0.Exit

Select action (0-5): 

The Publish a public page (domain) entry exists only while the page lives on localhost: once published it disappears, and the address moves into the menu header.

root@server: ~
=== Xray Checker status ===

 Xray Checker: running
 (127.0.0.1:2112)
 Deployment: Checker + status page (recommended)
 Status page: running
 (127.0.0.1:8080)
 Public page: https://status.example.com

Recent lines of xray-checker:
  …

The Configure the Telegram bot entry repeats the install steps: a new token, admins, alert chats. Leaving the token empty makes the module ask whether to drop the bot entirely: the page stays, managed only through this menu.

Update images pulls fresh versions of the checker and the page and restarts the stack. Restart recreates the containers, keeping the page data. Removal wipes the containers and the status page volume together with its history and secret.key, while the xray-checker user stays in the panel:

root@server: ~
[ * ] Updating images...
[ ✓ ] Images updated, Xray Checker restarted.
root@server: ~
Uninstall Xray Checker? The containers and the status page volume (history, secret.key) will be wiped, while user "xray-checker" stays in the panel (y/n): y
[ * ] Removing...
[ ✓ ] Xray Checker removed.
  • IP (default): a light request through the proxy, the exit address change is verified. The cheapest way, but only for a checker on a separate server: next to a node it would forever mark it down, and the module warns about that immediately.
  • HTTP status: a page is requested through the proxy and the response code is checked. Works with any server layout.
  • Download: downloads a test file of about 1 MB through every proxy every cycle. The most honest channel check, but watch the traffic.

When installing on a server that also runs a node, the module flags “IP” with a warning and recommends “HTTP status”.