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.

Checker

Walks every proxy of the subscription on a schedule and decides whether the host is alive.

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

Status page

Public state page by Mrvibecodic: host uptime, incidents, maintenance.

Domaine.g. status.example.comNo domainlocalhost or an SSH tunnelDatahistory and secret.key in a Docker volume

Telegram bot

Lives in the status page: failure alerts, incidents, maintenance and subscription management.

Commands/start, then /menuAlertsto chats by ID from the settingsSetupat install or from the menu

kutovoys

the checker itself: probes the proxies of the subscription on a schedule and records metrics

github.com/kutovoys/xray-checker

Mrvibecodic

status page and Telegram bot: alerts, incidents, maintenance, management

github.com/Mrvibecodic/xray-checker-statuspage

How it works

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.

A non-standard subscription page

The auto variant looks for the remnawave-subscription-page service in the panel’s compose. A subscription page installed outside the script (for example, 366-days by Mrvibecodic) works too: when its service carries the same name, auto wiring sees it as the regular one. With a different service name, pick “Enter a subscription URL manually”.

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

Page cache

The status page may start slower than the checker. The install is not considered failed for that: the checker answers on 127.0.0.1:2112, and the page catches up in a minute or two.

Requirements

Important

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. On a server that also runs a node the “IP” method does not work: the exit through that node comes from the same address.

• 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.

Installation

Run on the monitoring server:

remnawave_reverse

1. In the main menu select 5:

   root@server: ~

   REMNAWAVE REVERSE-PROXY by eGames
   Wiki: https://wiki.egam.es/
   
   4.Node extensions (templates, plugins, core)
   
   5.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; 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.

Module menu

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.

Status and recent logs

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:
  …

Telegram bot

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.

Updates and removal

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.

Check methods

• 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”.