Multi-file configuration

The Xray program supports the use of multiple configuration files.

The main purpose of using multiple configuration files is to distribute different module configurations, making it easier to manage and maintain.

This feature is mainly designed to enrich the Xray ecosystem. For example, for GUI-based clients, only fixed functions such as node selection are usually implemented, and complex configurations are difficult to implement graphically. By leaving a custom confdir configuration directory for complex functions, server deployment scripts can simply add files to confdir to implement multiple protocol configurations.

Multi-file startup

Tip

The startup information will indicate each configuration file being read in sequence. Please pay attention to whether the startup information matches the order you have set.

$ xray run -confdir /etc/xray/confs

You can also use Xray.location.confdir or Xray_LOCATION_CONFDIR to specify the confdir.

The -confdir parameter takes precedence over the environment variable. If a valid directory is specified by the parameter, the path in the environment variable will not be read.

Rule Explanation

Normal Objects（{}）

In the top-level object of JSON, the latter overrides or supplements the former.

For example：

• base.json

{
  "log": {},
  "api": {},
  "dns": {},
  "stats": {},
  "policy": {},
  "transport": {},
  "routing": {},
  "inbounds": []
}

• outbounds.json

{
  "outbounds": []
}

When starting Xray with multiple configurations, use the following command:

$ xray run -confdir /etc/xray/confs

These two configuration files are equivalent to a single combined configuration. If you need to modify the outbound nodes, simply modify the content of outbounds.json.

If you need to change the log level for debugging purposes, there is no need to modify base.json. You can add an additional configuration file:

• debuglog.json

{
  "log": {
    "loglevel": "debug"
  }
}

Start the program in sequence after base.json to output logs at the debug level.

Arrays（[]）

In the JSON configuration, inbounds and outbounds are array structures with special rules:

• When there are two or more elements in the array, the latter overrides the former for inbounds/outbounds.
• When there is only one element in the array, it searches for an existing element with the same tag to override. If it cannot be found:
  • For inbounds, add it to the end (the order of elements in inbounds is irrelevant).
  • For outbounds, add it to the beginning (the default first-choice outbound). However, if the filename contains "tail" (case-insensitive), add it to the end.

With multiple configurations, it is easy to add inbound for different protocols to the original configuration without modifying the original configuration.

The following example is not a valid configuration but is provided to demonstrate the above rules.

• 000.json

{
  "inbounds": [
    {
      "protocol": "socks",
      "tag": "socks",
      "port": 1234
    }
  ]
}

• 001.json

{
  "inbounds": [
    {
      "protocol": "http",
      "tag": "http"
    }
  ]
}

• 002.json

{
  "inbounds": [
    {
      "protocol": "socks",
      "tag": "socks",
      "port": 4321
    }
  ]
}

The three configurations will be combined into:

{
  "inbounds": [
    {
      "protocol": "socks",
      "tag": "socks",
      "port": 4321 // < 002顺序在000后，因此覆盖tag为socks的inbound端口为4321
    },
    {
      "protocol": "http",
      "tag": "http"
    }
  ]
}

Recommended Multi-file List

Execute：

for BASE in 00_log 01_api 02_dns 03_routing 04_policy 05_inbounds 06_outbounds 07_transport 08_stats 09_reverse; do echo '{}' > "/etc/Xray/$BASE.json"; done

or

for BASE in 00_log 01_api 02_dns 03_routing 04_policy 05_inbounds 06_outbounds 07_transport 08_stats 09_reverse; do echo '{}' > "/usr/local/etc/Xray/$BASE.json"; done

.
├── 00_log.json
├── 01_api.json
├── 02_dns.json
├── 03_routing.json
├── 04_policy.json
├── 05_inbounds.json
├── 06_outbounds.json
├── 07_transport.json
├── 08_stats.json
└── 09_reverse.json

0 directories, 10 files