Xray Install

https://github.com/xtls/xray-install
Admin
Xray Install provides a set of robust shell scripts to easily install and manage Xray, a unified...
Tokens:24,697
Snippets:173
Trust Score:8.8
License:GPL-3.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### One-off start with custom confdir and env

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/api-reference/openrc-xray-service.md

Shows how to override the confdir and env variables for a single service start, using a custom configuration directory and asset location.

```sh
# Use a custom config directory and asset location for a one-off start
rc-service xray confdir="/srv/xray/conf/" env="XRAY_LOCATION_ASSET=/srv/xray/data/" start
```

--------------------------------

### Catch errors via exit status and message prefix protocol

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/errors.md

Two shell examples show how consumer code can detect installer failures: checking the exit status of `install-release.sh @ check`, and grepping stdout for the documented message prefixes (`error:`, `warning:`, `info:`, `removed:`, `installed:`, `ok:`). The scripts print all diagnostics to stdout, so stdout is machine-greppable.

```bash
# 1 — exit status: the script's documented contract
if bash install-release.sh @ check; then
  echo "check ok"
else
  echo "check failed with exit $?"
fi
```

```bash
# 2 — message prefix protocol (stdout is machine-greppable):
#    error: | warning: | warn: | info: | installed: | removed: | ok.
bash install-release.sh @ remove --purge 2>&1 | grep -E '^(error|warning|info|removed|installed):'
```

--------------------------------

### Run Xray Installation Script

Source: https://github.com/xtls/xray-install/blob/main/alpinelinux/README.md

Executes the downloaded installation script using the ash shell to install Xray.

```sh
ash install-release.sh
```

--------------------------------

### Download and run the Alpine installer

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/api-reference/alpinelinux-install-release.sh.md

Downloads the installer script from GitHub and runs it with `ash`. Requires `curl` and `ash`; the script must be run as root and on Alpine or Gentoo with OpenRC.

```bash
curl -O -L https://github.com/XTLS/Xray-install/raw/main/alpinelinux/install-release.sh
ash install-release.sh
```

--------------------------------

### Installed layout (fixed, non-configurable)

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/api-reference/alpinelinux-install-release.sh.md

Lists the fixed installation paths for the Xray binary, geo data files, configuration files, log files, and the OpenRC init script.

```text
/usr/local/bin/xray
/usr/local/share/xray/geoip.dat
/usr/local/share/xray/geosite.dat
/usr/local/etc/xray/00_log.json … 09_reverse.json
/var/log/xray/{access,error}.log
/etc/init.d/xray        # OpenRC unit, owner/dependent on install_startup_service_file
```

--------------------------------

### Install & Upgrade Xray-core to a pre-release version

Source: https://github.com/xtls/xray-install/blob/main/README.md

Installs or upgrades Xray-core to a pre-release (beta) version using the --beta flag.

```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install --beta
```

--------------------------------

### start_pre() hook

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/api-reference/openrc-xray-service.md

Runs checkconfig before starting the service and refuses to start if validation fails. This makes config validation a hard precondition.

```sh
start_pre() {
	checkconfig || return 1
}
```

--------------------------------

### install-geodata action with proxy

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/api-reference/install-release.sh.md

Downloads, verifies, and installs only geoip.dat and geosite.dat into $DAT_PATH, then exits 0. The only supported option is -p/--proxy.

```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install-geodata -p http://127.0.0.1:8118
```

--------------------------------

### check action: print versions

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/api-reference/install-release.sh.md

Prints installed version, latest release, and latest pre-release from GitHub, then exits 0. Supports -p/--proxy.

```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ check
```

--------------------------------

### Install & Upgrade Xray-core and geodata with User=nobody

Source: https://github.com/xtls/xray-install/blob/main/README.md

Installs or upgrades Xray-core and geodata using the install-release.sh script. Runs with User=nobody but does not overwrite the User setting in existing service files.

```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
```

--------------------------------

### Install & Upgrade Xray-core and geodata with logrotate

Source: https://github.com/xtls/xray-install/blob/main/README.md

Installs or upgrades Xray-core and geodata with logrotate support. The $time parameter can be in the format 12:34:56. This installs additional systemd service and timer files for logrotate.

```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install --logrotate $time
```

```text
installed: /etc/systemd/system/logrotate@.service
installed: /etc/systemd/system/logrotate@.timer

installed: /etc/logrotate.d/xray
```

--------------------------------

### Enable Xray Service (Auto-start on Boot)

Source: https://github.com/xtls/xray-install/blob/main/alpinelinux/README.md

Adds the Xray service to the default runlevel so it starts automatically on boot.

```sh
rc-update add xray
```

--------------------------------

### Install cURL on Alpine Linux

Source: https://github.com/xtls/xray-install/blob/main/alpinelinux/README.md

Installs cURL using the Alpine package manager. Required before downloading the installation script.

```sh
apk add curl
```

--------------------------------

### Install & Upgrade Xray-core and geodata with User=root

Source: https://github.com/xtls/xray-install/blob/main/README.md

Installs or upgrades Xray-core and geodata with User=root. This will overwrite the User setting in existing service files.

```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install -u root
```

--------------------------------

### Download Xray Installation Script

Source: https://github.com/xtls/xray-install/blob/main/alpinelinux/README.md

Downloads the official Xray installation script for Alpine Linux from the Xray-install repository.

```sh
curl -O -L https://github.com/XTLS/Xray-install/raw/main/alpinelinux/install-release.sh
```

--------------------------------

### install action: upgrade to newest pre-release without geodata

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/api-reference/install-release.sh.md

Upgrades to the newest pre-release while skipping geodata updates. Uses --beta and --without-geodata options.

```bash
# Upgrade to the newest pre-release without touching geodata
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install --beta --without-geodata
```

--------------------------------

### Filesystem Hierarchy Standard (FHS) for Xray Installation

Source: https://github.com/xtls/xray-install/blob/main/README.md

Lists the files installed by the Xray-install script, including systemd service files, the Xray binary, configuration files, geodata files, and log file locations. Note that Xray does not log to /var/log/xray/*.log by default; configure the "log" setting to specify log files.

```text
installed: /etc/systemd/system/xray.service
installed: /etc/systemd/system/xray@.service

installed: /usr/local/bin/xray
installed: /usr/local/etc/xray/*.json

installed: /usr/local/share/xray/geoip.dat
installed: /usr/local/share/xray/geosite.dat

installed: /var/log/xray/access.log
installed: /var/log/xray/error.log
```

--------------------------------

### /etc/logrotate.d/xray (only with --logrotate)

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/configuration.md

Logrotate configuration for Xray log files. Rotates daily, keeps 7 rotations, compresses, and creates new files with mode 0600 owned by the install user.

```plaintext
/var/log/xray/*.log {
    daily
    missingok
    rotate 7
    compress
    delaycompress
    notifempty
    create 0600 $INSTALL_USER_UID $INSTALL_USER_GID
}
```

--------------------------------

### Canonical invocation: bash -c with curl and @

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/api-reference/install-release.sh.md

The standard way to run the install script from the network. The @ is ignored by bash -c and passes the following arguments as $@ to the script.

```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ ACTION [OPTION]...
```

--------------------------------

### Install & Upgrade Xray-core without geodata

Source: https://github.com/xtls/xray-install/blob/main/README.md

Installs or upgrades Xray-core without downloading or installing geodata files.

```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install --without-geodata
```

--------------------------------

### Start Xray Service

Source: https://github.com/xtls/xray-install/blob/main/alpinelinux/README.md

Starts the Xray service immediately using the Alpine service manager.

```sh
rc-service xray start
```

--------------------------------

### Show help for Xray-install script

Source: https://github.com/xtls/xray-install/blob/main/README.md

Displays the help information for the Xray-install script.

```bash
bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ help
```

--------------------------------

### /etc/systemd/system/xray.service (base unit)

Source: https://github.com/xtls/xray-install/blob/main/_autodocs/configuration.md

Systemd unit for the Xray service. Uses the resolved $INSTALL_USER, and when INSTALL_USER_UID=0 the capability and NoNewPrivileges lines are commented out. ExecStart points to the single-config JSON path.

```ini
[Unit]
Description=Xray Service
Documentation=https://github.com/xtls
After=network.target nss-lookup.target

[Service]
User=$INSTALL_USER
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
NoNewPrivileges=true
ExecStart=/usr/local/bin/xray run -config /usr/local/etc/xray/config.json
Restart=on-failure
RestartPreventExitStatus=23
LimitNPROC=10000
LimitNOFILE=1000000
RuntimeDirectory=xray
RuntimeDirectoryMode=0755

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Disable Xray Service (Remove from Auto-start)

Source: https://github.com/xtls/xray-install/blob/main/alpinelinux/README.md

Removes the Xray service from the default runlevel so it no longer starts automatically on boot.

```sh
rc-update del xray
```
Tokens:
Raw