Ansible Role: Xray

Installs and configures Xray-core with a basic VLESS+REALITY setup using systemd on Linux hosts. Includes optional network tuning (TCP BBR) for potentially improved performance.

Requirements

Prerequisites on Managed Node (Target Server)

• openssl: Used to generate a random short ID for REALITY if one is not provided. Most Linux distributions include this by default.
• Linux Kernel >= 4.9: Required for the TCP BBR network tuning feature to be effective.

Prerequisites on Ansible Control Node

• Ansible: Version 2.10 or higher recommended.
• quera.github Collection: This role uses the quera.github.install_from_github module to fetch assets directly from GitHub releases. Install it using:

  ansible-galaxy collection install quera.github

Role Variables

Most variables have defaults defined in defaults/main.yml. You may need to override some depending on your specific requirements.

Essential Variables to Define

Variable	Description
xray_core_reality_dest	The real domain name the REALITY protocol will pretend to connect to (e.g., "www.microsoft.com").
xray_core_port	The port Xray will listen on for incoming connections.

Optional Variables (Generated if not set)

These variables will be generated by the role using xray or openssl commands if not explicitly defined in your playbook or inventory.

Variable	Description	Generation Method (if empty)
xray_core_client_uuid	The UUID for the VLESS client.	xray uuid
xray_core_reality_private_key	The private key for the REALITY key pair. Note: The corresponding public key needs to be configured on the client side. The role does not currently output the generated public key automatically. You may need to run xray x25519 manually or inspect logs.	xray x25519
xray_core_reality_short_id	A short identifier for REALITY.	openssl rand -hex 8

Other Configuration Variables

Variable	Description	Default
xray_core_enabled	Whether the xray systemd service should be enabled and started. Set to false to disable and stop the service.	true
xray_core_user	The system user to run Xray.	xray
xray_core_group	The system group for the Xray user.	xray
xray_core_assets_dir	Directory for GeoIP/GeoSite data.	/usr/local/share/xray
xray_core_config_dir	Directory for configuration files.	/usr/local/etc/xray
xray_core_logs_dir	Directory for log files.	/var/log/xray
xray_core_config_file	Path to the main config file.	{{ xray_core_config_dir }}/config.json
xray_core_config	The entire Xray configuration structure as an Ansible dictionary/map (See defaults/main.yml). Override parts or the whole structure for advanced customization.	(See defaults/main.yml)

Dependencies

• quera.github Ansible collection (see Prerequisites).

Example Playbook

Here's how to include this role in Ansible project's playbook:

1. Installation:

• Option 1: Install via requirements.yml (Recommended) Create a requirements.yml file in Ansible project and add an entry for the collection. For example:

# requirements.yml
collections:
  - name: ouroborosng.xray
    source: git+https://github.com/ouroborosng/ansible-xray-collection.git
    type: git
    version: main

Then, run the following command to install both roles and collections defined in the file:

ansible-galaxy collection install -r requirements.yml

This method centralizes dependency management and ensures consistency across environments.

• Option 2: Direct Installation via Git URL: Install the collection directly by running:

ansible-galaxy collection install git+https://github.com/ouroborosng/ansible-xray-collection.git

This command instructs Ansible Galaxy to fetch and install the collection from the specified Git repository URL, making it immediately available for use in the playbooks.

Optional: Removing the Collection

This pipeline uses ansible-config dump to list the configured COLLECTIONS_PATHS, filters each absolute directory, searches for the ouroborosng collection under ansible_collections, and removes its contents:

ansible-config dump \
  | grep COLLECTIONS_PATHS \
  | awk -F"[' ,]" '{for(i=1;i<=NF;i++) if($i ~ /^\//) print $i}' \
  | xargs -I {} find {}/ansible_collections/ouroborosng -mindepth 1 -maxdepth 1 -type d -print \
  | xargs -I {} rm -rf {}

To confirm the collection has been removed, run:

ansible-galaxy collection list | grep ouroborosng.xray || echo "Collection 'ouroborosng.xray' not found"

2. Playbook Usage:

# playbook.yml
- name: Setup Xray Server
  hosts: your_xray_servers
  become: true # Most tasks require root privileges
  collections:
    - ouroborosng.xray
  roles:
    - name: xray_core
      vars:
        xray_core_reality_dest: "www.your-chosen-domain.com" # REQUIRED: Set your target domain for REALITY protocol
        xray_core_port: 443 # Optional: override default port

💡 Note:
Ensure you have installed the collection (e.g. via a requirements.yml file or direct Git URL installation) before running this playbook.

Re-running Configuration

This role is idempotent by design and will not overwrite an existing Xray configuration file ({{ xray_core_config_dir }}/config.json). This safeguard prevents accidental loss of generated UUIDs, private keys, or any other custom settings when the playbook is executed again.

When role variables (e.g., in defaults/main.yml) or the configuration template (templates/xray.config.json.j2) have been updated and those changes must be applied to an existing deployment, remove the current configuration file before re-running the playbook:

sudo rm /usr/local/etc/xray/config.json

After removing the file, running the playbook again will regenerate the configuration based on the current variables and template.