How to Enable Hot Reload for Xray Core

Xray Core supports hot configuration reload through API and special CLI commands, which allows adding and removing users without service restart and connection interruption.

Table of Contents

• Basic hot reload methods
• Setting up gRPC API for user management
• Using CLI commands for dynamic management
• Optimization for large number of inbounds
• Automating management processes
• Conclusion and recommendations

Basic hot reload methods

Xray Core provides several ways to update configuration without restarting the service:

1. Via gRPC API - the main method for dynamic management
2. Via CLI commands - for adding/removing inbounds and users
3. Via external scripts - for automating processes

It’s worth noting that Xray Core initially planned to support the “Certificate Hot Update” feature, which automatically identifies certificate updates and reloads them without manual restart [source]. This concept can be extended to other aspects of configuration as well.

Setting up gRPC API for user management

To use hot reload, you first need to enable gRPC API in the Xray configuration:

{
  "inbounds": [...],
  "outbounds": [...],
  "api": {
    "services": [
      "HandlerService",
      "LoggerService",
      "StatsService"
    ]
  },
  "stats": {}
}

After setting up the API, you can use various management methods:

Adding a user via API

# Using CLI command
xray api adduser --email user@example.com --inbound-tag your-inbound-tag --user-id 12345678-1234-1234-1234-123456789012

Removing a user via API

xray api removeuser --email user@example.com --inbound-tag your-inbound-tag

As noted in GitHub discussions, you can add new users via API without reloading, by adding to a temporary inbound and then replacing the active inbound [source].

Using CLI commands for dynamic management

Xray Core provides a set of CLI commands for managing configuration without restarting:

For user management, there are specialized commands:

# Adding a user
xray api inbounduseradd --email newuser@example.com --inbound-tag main-inbound --user-id $(uuidgen)

# Removing a user  
xray api inbounduserremove --email olduser@example.com --inbound-tag main-inbound

# Getting user list
xray api inbounduserlist --inbound-tag main-inbound

These commands allow dynamic user management in a running Xray instance without needing to restart the service.

Optimization for large number of inbounds

When working with 25 inbounds with 9 users each (total ~225 users), the following approach is recommended:

1. Grouping users by inbounds

{
  "inbounds": [
    {
      "tag": "users-group-1",
      "listen": "0.0.0.0", 
      "port": 443,
      "protocol": "vless",
      "settings": {
        "clients": [
          {"id": "user1-id", "email": "user1@example.com"},
          {"id": "user2-id", "email": "user2@example.com"},
          ...
        ]
      }
    }
  ]
}

2. Using scripts for mass management

#!/bin/bash
# Script for adding a user without restart

EMAIL=$1
USER_ID=$(uuidgen)
INBOUND_TAG="users-group-1"

# Adding user via API
xray api inbounduseradd --email $EMAIL --inbound-tag $INBOUND_TAG --user-id $USER_ID

echo "User $EMAIL added to $INBOUND_TAG with ID: $USER_ID"

3. User migration strategy

For mass changes, it’s recommended to:

1. Create a new inbound with updated configuration
2. Migrate users to the new inbound via API
3. Redirect traffic to the new inbound
4. Remove the old inbound

Automating management processes

For convenience, you can use the Python library xtlsapi:

from xtlsapi import XrayClient

# Initialize client
xray_client = XrayClient('localhost', 10085)  # gRPC API port

# Adding a user
user = xray_client.add_client('main-inbound', 'user-id', 'user@example.com')

# Removing a user  
xray_client.remove_client('main-inbound', 'user@example.com')

# Restarting logger
xray_client.restart_logger()

You can also use systemd timers for automatic configuration updates:

# /etc/systemd/system/xray-user-update.timer
[Unit]
Description=Update Xray users automatically

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Conclusion and recommendations

To solve the problem of connection interruption when adding/removing users in Xray Core, it’s recommended to:

1. Enable gRPC API in the configuration for dynamic management capabilities
2. Use CLI commands inbounduseradd and inbounduserremove instead of editing config.json
3. Develop automation scripts for user management via API
4. For mass changes, use migration strategy through temporary inbounds
5. Monitor statistics using Xray’s built-in statistics services

With proper API setup and use of appropriate CLI commands, you can completely avoid restarting the Xray Core service when managing users, which ensures continuous operation for all clients.

Sources

1. GitHub Discussion - Reload configuration without restart
2. Official Documentation - Command Parameters
3. Official Documentation - Xray Server
4. Python library xtlsapi
5. Go packages - inbound management
6. Issue 1378 - Add user to inbound via api in xray cli