mirror of
https://github.com/XTLS/Xray-docs-next.git
synced 2026-10-14 10:09:16 +03:00
Env: Add new env configuration (#874)
https://github.com/XTLS/Xray-core/pull/6400 Co-authored-by: yiguodev <147401898+yiguodev@users.noreply.github.com>
This commit is contained in:
Meow
@@ -0,0 +1,139 @@
|
||||
# Environment Variables
|
||||
|
||||
Environment variables are used to adjust some underlying Xray settings.
|
||||
|
||||
They can be set either through the `env` item in the configuration file or in the traditional way as process environment variables before Xray starts.
|
||||
|
||||
::: tip Variable names
|
||||
Built-in Xray variables accept both lowercase, dot-separated names and uppercase, underscore-separated names, such as `xray.location.asset` and `XRAY_LOCATION_ASSET`. If both forms exist, the dot-separated form takes precedence.<br>This page uses the dot-separated form throughout; the uppercase, underscore-separated form is recommended when setting variables through a shell or service manager for better compatibility.
|
||||
:::
|
||||
|
||||
## EnvObject
|
||||
|
||||
`EnvObject` corresponds to the `env` item in the configuration file. It is a mapping of environment variable names to values.
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"xray.location.asset": "/usr/local/share/xray",
|
||||
"xray.buf.readv": "true",
|
||||
"xray.ray.buffer.size": "2"
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `environment variable name`: string
|
||||
|
||||
Both the environment variable name and its value must be strings. After Xray reads and merges all configuration files, it writes the entries in `env` to the current process environment before building its modules.
|
||||
|
||||
::: tip
|
||||
When [multiple configuration files](./features/multiple.md) are used, their `env` items are merged by key. A duplicate key from a later file overrides the earlier value.
|
||||
|
||||
The `env` item sets the exact name written in the configuration and replaces an existing process variable with that exact name.
|
||||
:::
|
||||
|
||||
::: warning
|
||||
The `env` item takes effect only after the configuration files have been located, read, and merged. For the following three options to affect the current startup, they must therefore be supplied as process environment variables before Xray starts. Placing them in the configuration file's `env` item cannot affect how that configuration is located or parsed:
|
||||
|
||||
- `xray.json.strict`
|
||||
- `xray.location.config`
|
||||
- `xray.location.confdir`
|
||||
|
||||
:::
|
||||
|
||||
## Setting Process Environment Variables
|
||||
|
||||
The following examples set both the resource file path and the strict JSON parser:
|
||||
|
||||
::: code-group
|
||||
|
||||
```bash [Shell]
|
||||
# Set the variables in the current shell and its child processes
|
||||
export XRAY_LOCATION_ASSET=/usr/local/share/xray
|
||||
export XRAY_JSON_STRICT=true
|
||||
|
||||
# Alternatively, set them for a single Xray invocation, separated by spaces
|
||||
XRAY_LOCATION_ASSET=/usr/local/share/xray XRAY_JSON_STRICT=true xray run
|
||||
```
|
||||
|
||||
```powershell [PowerShell]
|
||||
# Set the variables in the current PowerShell session and its child processes
|
||||
$env:XRAY_LOCATION_ASSET = "C:\Xray"
|
||||
$env:XRAY_JSON_STRICT = "true"
|
||||
```
|
||||
|
||||
```batch [CMD]
|
||||
:: Set the variables in the current CMD session and its child processes
|
||||
set "XRAY_LOCATION_ASSET=C:\Xray"
|
||||
set "XRAY_JSON_STRICT=true"
|
||||
```
|
||||
|
||||
```ini [systemd]
|
||||
# Set the variables in the Xray service's [Service] section
|
||||
[Service]
|
||||
Environment="XRAY_LOCATION_ASSET=/usr/local/share/xray"
|
||||
Environment="XRAY_JSON_STRICT=true"
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Built-in Xray Variables
|
||||
|
||||
### Resource File Path
|
||||
|
||||
- Name: `xray.location.asset`.
|
||||
- Default value: Specific [FHS](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard) directories or the directory containing the Xray executable.
|
||||
|
||||
This variable specifies the directory containing the `geoip.dat` and `geosite.dat` files.
|
||||
If it is not specified, the program looks for resource files in the following order:
|
||||
|
||||
```text
|
||||
./
|
||||
/usr/local/share/xray
|
||||
/usr/share/xray
|
||||
```
|
||||
|
||||
### Configuration File Location
|
||||
|
||||
- Name: `xray.location.config`.
|
||||
- Default value: The directory containing the Xray executable.
|
||||
|
||||
This variable specifies the directory containing the `config.json` file.
|
||||
|
||||
Setting it in the configuration file's `env` item has no effect because Xray locates the configuration file before reading that item.
|
||||
|
||||
### Multiple Configuration Directory
|
||||
|
||||
- Name: `xray.location.confdir`.
|
||||
- Default value: `""`.
|
||||
|
||||
The `.json` files in this directory are read in filename order as multiple configuration files.
|
||||
|
||||
Setting it in the configuration file's `env` item has no effect because Xray locates the configuration directory before reading that item.
|
||||
|
||||
This item has lower priority than the `confdir` startup argument.
|
||||
|
||||
### Strict JSON Parser
|
||||
|
||||
- Name: `xray.json.strict`.
|
||||
- Default value: `false`.
|
||||
|
||||
By default, Xray uses a custom JSON parser at startup. This parser strips comments and other non-standard characters from the configuration. If your configuration files strictly conform to the JSON standard (RFC 8259), you can enable this option to use the standard JSON parser, which can parse very large configurations faster.
|
||||
|
||||
Setting it in the configuration file's `env` item has no effect because Xray must select the JSON parser before it can read that item.
|
||||
|
||||
### Other Available Variables
|
||||
|
||||
- `xray.location.cert`
|
||||
- `xray.buf.readv`
|
||||
- `xray.buf.splice`
|
||||
- `xray.vmess.padding`
|
||||
- `xray.cone.disabled`
|
||||
- `xray.ray.buffer.size`
|
||||
- `xray.browser.dialer`
|
||||
- `xray.xudp.show`
|
||||
- `xray.xudp.basekey`
|
||||
- `xray.tun.fd`
|
||||
|
||||
These options are intended for specialized use cases. Refer to the source code for their exact behavior.
|
||||
@@ -1,57 +1,3 @@
|
||||
# Environment Variables
|
||||
|
||||
Xray provides the following environment variables to modify some underlying configurations of Xray.
|
||||
|
||||
## Resource File Path
|
||||
|
||||
- Name: `xray.location.asset` or `XRAY_LOCATION_ASSET`.
|
||||
- Default value: Specific [FHS](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard) directories or the same path as the Xray executable.
|
||||
|
||||
This environment variable specifies a folder location that should contain the `geoip.dat` and `geosite.dat` files.
|
||||
If no variable value is specified, the program will look for resource files in the following order:
|
||||
|
||||
```text
|
||||
./
|
||||
/usr/local/share/xray
|
||||
/usr/share/xray
|
||||
```
|
||||
|
||||
## Configuration File Location
|
||||
|
||||
- Name: `xray.location.config` or `XRAY_LOCATION_CONFIG`.
|
||||
- Default value: The same path as the Xray executable.
|
||||
|
||||
This environment variable specifies a folder location that should contain the `config.json` file.
|
||||
|
||||
## Multiple Configuration Directory
|
||||
|
||||
- Name: `xray.location.confdir` or `XRAY_LOCATION_CONFDIR`.
|
||||
- Default value: `""`.
|
||||
|
||||
The `.json` files in this directory will be read in alphabetical order of their filenames as multiple configuration options.
|
||||
|
||||
This item has lower priority than the startup argument `confdir`.
|
||||
|
||||
## Strict JSON Parser
|
||||
|
||||
- Name: `xray.json.strict` or `XRAY_JSON_STRICT`.
|
||||
- Default value: `false`.
|
||||
|
||||
By default, on startup Xray uses a custom JSON parser that strips comments and other non-standard characters from the configuration. If you are sure that your configuration file strictly conforms to the JSON standard (RFC 8259), you can enable this option to use the standard JSON parser, which is faster when working with large configurations.
|
||||
|
||||
## Other Available Configurations
|
||||
|
||||
- xray.location.plugin
|
||||
- xray.location.tool
|
||||
- xray.location.cert
|
||||
|
||||
- xray.buf.readv
|
||||
- xray.buf.splice
|
||||
- xray.vmess.padding
|
||||
|
||||
- xray.ray.buffer.size
|
||||
- xray.browser.dialer
|
||||
- xray.xudp.show
|
||||
- xray.xudp.basekey
|
||||
|
||||
These options are open to users with special needs; you can read the source code to discover their usage. ~~PR Welcome~~
|
||||
This page has moved to [Environment Variables](../env.md).
|
||||
|
||||
@@ -5,6 +5,5 @@ Xray has the following features:
|
||||
- [XTLS Deep Dive](xtls.md)
|
||||
- [Fallback](fallback.md)
|
||||
- [Browser Dialer](browser_dialer.md)
|
||||
- [Environment Variables](env.md)
|
||||
- [Multiple File Configuration](multiple.md)
|
||||
- [Reverse Proxy / NAT Traversal](/en/document/level-2/vless_reverse.md)
|
||||
|
||||
@@ -61,4 +61,4 @@ The resource download URL. It must be an HTTPS URL.
|
||||
|
||||
The resource filename to write, such as `geoip.dat` or `geosite.dat`.
|
||||
|
||||
The file is resolved using the [Resource File Path](./features/env.md#resource-file-path). It must be an existing regular file inside the resource directory; absolute paths and paths escaping the resource directory are not supported.
|
||||
The file is resolved using the [Resource File Path](./env.md#resource-file-path). It must be an existing regular file inside the resource directory; absolute paths and paths escaping the resource directory are not supported.
|
||||
|
||||
@@ -13,6 +13,7 @@ The format is as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {},
|
||||
"log": {},
|
||||
"api": {},
|
||||
"dns": {},
|
||||
@@ -170,11 +171,15 @@ List the parts of my question that are not confirmed by the official documentati
|
||||
|
||||
## Basic Configuration Modules
|
||||
|
||||
> log:[LogObject](./log.md)
|
||||
> env: [EnvObject](./env.md)
|
||||
|
||||
Environment variables for modifying some underlying configurations of Xray.
|
||||
|
||||
> log: [LogObject](./log.md)
|
||||
|
||||
Log configuration, controls how Xray outputs logs.
|
||||
|
||||
> api:[ApiObject](./api.md)
|
||||
> api: [ApiObject](./api.md)
|
||||
|
||||
Provides some API interfaces for remote calls.
|
||||
|
||||
|
||||
@@ -93,7 +93,7 @@ When multiple attributes are specified simultaneously, these attributes must be
|
||||
- **Full match**: Starts with `"full:"`, the rest is a domain name. The rule takes effect when this domain exactly matches the target domain. For example, "full:xray.com" matches "xray.com" but not "www.xray.com".
|
||||
- **Dotless domain**: Starts with `"dotless:"`, the rest is a string that cannot contain `.`. The rule takes effect when the domain contains no `.` and this string matches any part of the target domain. For example, "dotless:pc-" matches "pc-alice", "mypc-alice". Suitable for intranet NetBIOS domains, etc. Case sensitive.
|
||||
- **Predefined domain list**: Starts with `"geosite:"`, the rest is a name, such as `geosite:google` or `geosite:cn`. Refer to [Predefined Domain List](#predefined-domain-list) for names and domain lists.
|
||||
- **Load domains from file**: In the form of `"ext:file:tag"`. Must start with `ext:` (lowercase), followed by filename and tag. The file is stored in the [Resource Directory](./features/env.md#resource-file-path). The file format is the same as `geosite.dat`, and the tag must exist in the file.
|
||||
- **Load domains from file**: In the form of `"ext:file:tag"`. Must start with `ext:` (lowercase), followed by filename and tag. The file is stored in the [Resource Directory](./env.md#resource-file-path). The file format is the same as `geosite.dat`, and the tag must exist in the file.
|
||||
|
||||
::: tip
|
||||
`"ext:geoip.dat:cn"` is equivalent to `"geoip:cn"`
|
||||
@@ -107,7 +107,7 @@ An array, where each item represents an IP range. The rule takes effect when an
|
||||
- **[CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)**: Like `"10.0.0.0/8"`. You can also use `"0.0.0.0/0"` or `"::/0"` to specify all IPv4 or IPv6.
|
||||
- **Predefined IP list**: This list is pre-installed in every Xray installation package, named `geoip.dat`. Usage is like `"geoip:cn"`. Must start with `geoip:` (lowercase), followed by a two-character country code. Supports almost all countries with internet access.
|
||||
- **Special value**: `"geoip:private"`, includes all private addresses, such as `127.0.0.1`.
|
||||
- **Load IPs from file**: In the form of `"ext:file:tag"`. Must start with `ext:` (lowercase), followed by filename and tag. The file is stored in the [Resource Directory](./features/env.md#resource-file-path). The file format is the same as `geoip.dat`, and the tag must exist in the file.
|
||||
- **Load IPs from file**: In the form of `"ext:file:tag"`. Must start with `ext:` (lowercase), followed by filename and tag. The file is stored in the [Resource Directory](./env.md#resource-file-path). The file format is the same as `geoip.dat`, and the tag must exist in the file.
|
||||
- **Inverse selection `!`**: `"!10.0.0.0/8"` means anything not in `10.0.0.0/8`, and `"!geoip:cn"` means results not in `geoip:cn`. Multiple inverse options have an `AND` relationship, while positive options, or positive options together with all inverse options, have an `OR` relationship. For example, `ip: ["!geoip:cn", "!geoip:us", "geoip:telegram"]` matches IPs that are not from the US AND not from China, OR are Telegram IPs.
|
||||
|
||||
> `port`: number | string
|
||||
|
||||
@@ -110,7 +110,7 @@ xray run -config http+unix:///run/xray-config.sock/config.json
|
||||
When `-config` is not specified, Xray will attempt to load `config.json` from the following paths in order:
|
||||
|
||||
- Working Directory
|
||||
- The path specified by `Xray.location.asset` in [Environment Variables](../config/features/env.md#resource-file-path)
|
||||
- The path specified by `Xray.location.asset` in [Environment Variables](../config/env.md#resource-file-path)
|
||||
:::
|
||||
|
||||
```bash
|
||||
@@ -255,7 +255,7 @@ xray wg [-i "(base64.StdEncoding)"]
|
||||
When `-config` is not specified, Xray will attempt to load `config.json` from the following paths in order:
|
||||
|
||||
- Working Directory
|
||||
- The path specified by `Xray.location.asset` in [Environment Variables](../config/features/env.md#resource-file-path)
|
||||
- The path specified by `Xray.location.asset` in [Environment Variables](../config/env.md#resource-file-path)
|
||||
:::
|
||||
|
||||
### xray mldsa65
|
||||
|
||||
@@ -87,6 +87,7 @@ Two different styles of Docker images are currently provided:
|
||||
- 09_metrics.json
|
||||
- 10_observatory.json
|
||||
- 11_geodata.json
|
||||
- 12_env.json
|
||||
- 99_version.json
|
||||
- `/usr/local/share/xray/`: Resource file directory containing Loyalsoldier geolocation data files (owner: `65532:65532`, directory permissions: `755`, file permissions: `644`)
|
||||
- geoip.dat
|
||||
|
||||
Reference in New Issue
Block a user