XRay Configuration Documentation

This document explains how PasarGuard validates and processes XRay configuration files. It's designed to help beginners understand the validation process, default values, and API limitations.

Table of Contents

1. Overview
2. Configuration Validation
3. Default Values
4. Supported Protocols
5. Network Types
6. Security Settings
7. Viewing Connected IPs
8. API Limits and Constraints
9. Common Validation Errors

Overview

The XRayConfig class is responsible for:

• Validating XRay configuration JSON files
• Extracting default values from configuration
• Processing inbound and outbound settings
• Handling special configurations like fallbacks and TLS/Reality

Configuration Validation

Required Fields

Your XRay configuration must include:

1. inbounds - Array of inbound configurations

   • Cannot be empty or missing
   • Each inbound must have a unique tag
   • Each inbound must have a protocol field

2. outbounds - Array of outbound configurations

   • Cannot be empty or missing
   • Each outbound must have a unique tag

Inbound Tag Rules

Inbound tags have strict rules:

• ✅ Must be unique - No two inbounds can have the same tag
• ✅ Must be present - Every inbound requires a tag
• ❌ Cannot contain comma (,) - The character , is not allowed
• ❌ Cannot contain <=> - This sequence is reserved for fallback handling

{
  "inbounds": [
    {
      "tag": "vless-ws-443",
      "port": 443,
      "protocol": "vless"
    },
    {
      "tag": "trojan-tls-8443",
      "port": 8443,
      "protocol": "trojan"
    },
    {
      "tag": "vmess-grpc",
      "port": 443,
      "protocol": "vmess"
    }
  ]
}

{
  "inbounds": [
    {
      "tag": "inbound,fallback",  // ❌ Contains comma
      "port": 443,
      "protocol": "vless"
    },
    {
      "tag": "inbound<=>fallback",  // ❌ Contains <=>
      "port": 8443,
      "protocol": "trojan"
    }
  ]
}

Port Requirements

Most inbounds must have a port field. The only exception is when:

• The inbound is used as a fallback destination (referenced by another inbound's fallback settings)
• The inbound has its own fallbacks array in settings

Example:

{
  "tag": "main-inbound",
  "port": 443,  // ✅ Required for most inbounds
  "protocol": "vless"
}

Default Values

When processing your configuration, PasarGuard extracts and sets default values for various settings. Here's what gets set automatically:

Base Settings (All Inbounds)

These defaults are applied to every inbound:

Protocol-Specific Defaults

Supported Protocols

PasarGuard processes and validates these protocols:

1. Vmess
2. Vless
3. Trojan
4. Shadowsocks

Network Types

The following network/transport types are supported:

Network-Specific Rules

{
  "streamSettings": {
    "network": "tcp",
    "tcpSettings": {
      "header": {
        "type": "http",
        "request": {
          "path": ["/path"],  // ✅ Array
          "headers": {
            "Host": ["example.com"]  // ✅ Array
          }
        }
      }
    }
  }
}

{
  "streamSettings": {
    "network": "ws",
    "wsSettings": {
      "path": "/path",  // ✅ String
      "host": "example.com"  // ✅ String
    }
  }
}

{
  "streamSettings": {
    "network": "grpc",
    "grpcSettings": {
      "serviceName": "my-service",  // Used as path
      "authority": "example.com"     // Used as host
    }
  }
}

Security Settings

{
  "streamSettings": {
    "security": "tls",
    "tlsSettings": {
      "certificates": [{
        "certificateFile": "/path/to/cert.pem",
        "keyFile": "/path/to/key.pem"
      }]
    }
  }
}

{
  "streamSettings": {
    "security": "reality",
    "realitySettings": {
      "serverNames": ["example.com"],
      "privateKey": "your-private-key-here",
      "shortIds": [""]
    }
  }
}

Viewing Connected IPs

You can enable tracking of user online statistics to see the latest IP addresses connected to your core. This feature allows you to monitor which IPs are currently connected to your XRay core.

Enabling User Online Statistics

To enable this feature, you need to add a policy section to the root of your XRay configuration JSON file. Add the following configuration:

{
  "policy": {
    "levels": {
      "0": {
        "statsUserOnline": true
      }
    }
  },
  "inbounds": [
    // ... your inbound configurations
  ],
  "outbounds": [
    // ... your outbound configurations
  ]
}

Viewing Connected IPs

After enabling the statsUserOnline policy and restarting your node:

1. First Connection Required: The IP tracking will start working after the first user connection is established
2. Access Statistics: Once enabled and after the first connection, you can view the latest connected IPs through your panel's statistics interface

Complete Example

Here's a complete example configuration with the policy section enabled:

{
  "policy": {
    "levels": {
      "0": {
        "statsUserOnline": true
      }
    }
  },
  "inbounds": [
    {
      "tag": "vless-ws-443",
      "port": 443,
      "protocol": "vless",
      "settings": {
        "clients": []
      },
      "streamSettings": {
        "network": "ws",
        "wsSettings": {
          "path": "/path"
        }
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    }
  ]
}

API Limits and Constraints

When creating or modifying core configurations through the API, these limits apply:

Field Limits

Special Rules

1. Default Core Protection

   • Core configuration with id = 1 cannot be deleted
   • This is the default/core system configuration

2. Tag String Length

   • When exclude_inbound_tags and fallbacks_inbound_tags are combined into a comma-separated string, the total length must not exceed 2048 characters
   • Example: If you have 100 tags of 20 characters each, that's 2000 characters (plus 99 commas = 2099) which would exceed the limit

3. Config Validation

   • The config dictionary cannot be empty {}
   • Must pass all XRay validation rules (inbounds, outbounds, tags, etc.)

API Endpoints

The following endpoints are available for core configuration management:

• POST /api/core - Create new core configuration
• GET /api/core/{core_id} - Get core configuration by ID
• PUT /api/core/{core_id} - Modify existing core configuration
• DELETE /api/core/{core_id} - Delete core configuration (except id=1)
• GET /api/cores - List all core configurations
• POST /api/core/{core_id}/restart - Restart nodes using this core

Common Validation Errors

Here are common errors you might encounter and how to fix them:

{
  "inbounds": [
    {
      "tag": "my-inbound",
      "port": 443,
      "protocol": "vless"
    }
  ],
  "outbounds": []
}

{
  "inbounds": [
    {"tag": "inbound-1", "port": 443, "protocol": "vless"},
    {"tag": "inbound-2", "port": 8443, "protocol": "trojan"}  // ✅ Different tag
  ]
}

{
  "inbounds": [
    {
      "tag": "inbound,fallback",  // ❌ Invalid
      "port": 443,
      "protocol": "vless"
    },
    {
      "tag": "inbound-fallback",  // ✅ Valid
      "port": 443,
      "protocol": "vless"
    }
  ]
}

{
  "tag": "my-inbound",
  "port": 443,  // ✅ Add this
  "protocol": "vless"
}

{
  "protocol": "shadowsocks",
  "settings": {
    "method": "2022-blake3-aes-128-gcm"  // ✅ Supported
    // "method": "2022-blake3-chacha20-poly1305"  // ❌ Not supported
  }
}

{
  "settings": {
    "method": "2022-blake3-aes-128-gcm",
    "password": "base64-encoded-password-here"  // ✅ Must be base64
  }
}

{
  "streamSettings": {
    "security": "reality",
    "realitySettings": {
      "privateKey": "your-private-key-here",  // ✅ Required
      "shortIds": [""],
      "serverNames": ["example.com"]
    }
  }
}

{
  "realitySettings": {
    "shortIds": [""],  // ✅ At least one element (can be empty string)
    // "shortIds": []  // ❌ Empty array not allowed
  }
}

{
  "streamSettings": {
    "network": "tcp",
    "tcpSettings": {
      "header": {
        "type": "http",
        "request": {
          "path": ["/path"],  // ✅ Array, not string
          "headers": {
            "Host": ["example.com"]  // ✅ Array, not string
          }
        }
      }
    }
  }
}

{
  "streamSettings": {
    "network": "ws",
    "wsSettings": {
      "path": "/path",  // ✅ String, not array
      "host": "example.com"  // ✅ String, not array
    }
  }
}

Summary

For more information about XRay configuration format, refer to the official XRay documentation.