Configuration

Getting SSL

ACME

To manage SSL certificates using ACME:

1. Ensure your domain is correctly resolved to the server.

2. Run the x-ui command in the terminal, then choose SSL Certificate Management.

3. You will be presented with the following options:

   • Get SSL: Obtain SSL certificates.
   • Revoke: Revoke existing SSL certificates.
   • Force Renew: Force renewal of SSL certificates.
   • Show Existing Domains: Display all domain certificates available on the server.
   • Set Certificate Paths for the Panel: Specify the certificate for your domain to be used by the panel.

Certbot

To install and use Certbot:

apt-get install certbot -y
certbot certonly --standalone --agree-tos --register-unsafely-without-email -d yourdomain.com
certbot renew --dry-run

Cloudflare

The management script includes a built-in SSL certificate application for Cloudflare. To use this script to apply for a certificate, you need the following:

• Cloudflare registered email
• Cloudflare Global API Key
• The domain name must be resolved to the current server through Cloudflare

How to get the Cloudflare Global API Key:

1. Run the x-ui command in the terminal, then choose Cloudflare SSL Certificate.
2. Visit the link: Cloudflare API Tokens.
3. Click on "View Global API Key" (see the screenshot below):

4. You may need to re-authenticate your account. After that, the API Key will be shown (see the screenshot below):

When using, just enter your domain name, email, and API KEY. The diagram is as follows:

Available environment variables

XUI_LOG_LEVEL

• Description: Default log level
• Type: string
• Acceptable values: debug | info | warn | error
• Default value: info

XUI_DEBUG

• Description: Whether debug mode should be enabled
• Type: boolean
• Default value: false

XUI_BIN_FOLDER

• Description: Path to the folder with xray-core, geosite & geoip databases
• Type: string
• Default value: bin

XUI_DB_FOLDER

• Description: Path to the 3x-ui database
• Type: string
• Default value: /etc/x-ui

XUI_LOG_FOLDER

• Description: Path to the logs
• Type: string
• Default value: /var/log

XUI_ENABLE_FAIL2BAN

• Description: Should fail2ban be working
• Type: boolean
• Default value: true

Reverse Proxy

Nginx

To configure the reverse proxy, add the following paths to your nginx config

location / {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Range $http_range;
    proxy_set_header If-Range $http_if_range; 
    proxy_redirect off;
    proxy_pass http://127.0.0.1:2053;
}

Note

The URL in the panel settings needs to end with /.

For the subscriptions

location /sub {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Range $http_range;
    proxy_set_header If-Range $http_if_range; 
    proxy_redirect off;
    proxy_pass http://127.0.0.1:2053;
}

Note

Ensure that the "URI Path" in the /sub panel settings is the same.

Caddy

Important

A huge thanks to @Gill-Bates for providing the config

Important

This configuration will work when the “WebSocket” transport is set inbound

Before configuring caddyfile, make sure that the following parameters are set in the panel setup

After customizing the panel, modify the caddyfile as follows

vpn.example.com {

    encode gzip

    # TLS 1.3 mandatory!
    tls {
        protocols tls1.3
    }

    # Protect your GUI with Basic Auth
    route /admin* {
        basic_auth {
            admin ******
        }
        reverse_proxy xx.xx.xx.xx:2053
    }

    # Obfuscate the Endpoint
    route /api/v1* {
        @websockets {
            header Connection *Upgrade*
            header Upgrade websocket
        }
        reverse_proxy @websockets xx.xx.xx.xx:54321
        respond "Forbidden" 403
    }

    # Security Header
    header {
        header_up Authorization { >Authorization }
        header_up Content-Type { >Content-Type }
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options nosniff
        X-Frame-Options SAMEORIGIN
        Referrer-Policy strict-origin-when-cross-origin
        -Server
        -X-Powered-By
    }

    # Fallback
    respond "Not found!" 404
}

The following data must be replaced in the config:

• vpn.example.com -> your domain.
• admin ***** -> replace the asterisks with your password.

If you do not need HTTP Auth, remove the following line

basic_auth {
    admin ******
}

• reverse_proxy xx.xx.xx.xx -> replace the xx.xx.xx.xx with your IP
• reverse_proxy @websockets xx.xx.xx.xx:54321 -> replace 54321 with your inbound port

Setting Fail2Ban

Note

IP Limit won't work correctly when using IP Tunnel.

For versions up to v1.6.1:

The IP limit is built-in to the panel

For versions v1.7.0 and newer:

To enable the IP Limit functionality, you need to install fail2ban and its required files by following these steps:

1. Run the x-ui command in the terminal, then choose IP Limit Management.

2. You will see the following options:

   • Change Ban Duration: Adjust the duration of bans.
   • Unban Everyone: Lift all current bans.
   • Check Logs: Review the logs.
   • Fail2ban Status: Check the status of fail2ban.
   • Restart Fail2ban: Restart the fail2ban service.
   • Uninstall Fail2ban: Uninstall Fail2ban with configuration.

3. Add a path for the access log on the panel by setting Xray Configs/log/Access log to ./access.log then save and restart xray.

• For versions before v2.1.3:

  • You need to set the access log path manually in your Xray configuration:

    "log": {
      "access": "./access.log",
      "dnsLog": false,
      "loglevel": "warning"
    },

• For versions v2.1.3 and newer:

  • There is an option for configuring access.log directly from the panel.

API

• API Documentation
• /login with POST user data: {username: '', password: ''} for login
• /panel/api/inbounds base for following actions:

Method	Path	Action
GET	"/list"	Get all inbounds
GET	"/get/:id"	Get inbound with inbound.id
GET	"/getClientTraffics/:email"	Get Client Traffics with email
GET	"/getClientTrafficsById/:id"	Get client's traffic By ID
GET	"/createbackup"	Telegram bot sends backup to admins
POST	"/add"	Add inbound
POST	"/del/:id"	Delete Inbound
POST	"/update/:id"	Update Inbound
POST	"/clientIps/:email"	Client Ip address
POST	"/clearClientIps/:email"	Clear Client Ip address
POST	"/addClient"	Add Client to inbound
POST	"/:id/delClient/:clientId"	Delete Client by clientId*
POST	"/updateClient/:clientId"	Update Client by clientId*
POST	"/:id/resetClientTraffic/:email"	Reset Client's Traffic
POST	"/resetAllTraffics"	Reset traffics of all inbounds
POST	"/resetAllClientTraffics/:id"	Reset traffics of all clients in an inbound
POST	"/delDepletedClients/:id"	Delete inbound depleted clients (-1: all)
POST	"/onlines"	Get Online users ( list of emails )

*- The field clientId should be filled by:

• client.id for VMESS and VLESS
• client.password for TROJAN
• client.email for Shadowsocks

Geosites

What is it?

The Geosites in Xray-core play a key role in traffic routing, enabling flexible control over traffic distribution based on the geographical location of IP addresses and domains. Here are their main files:

• geoip.dat contains a database of IP addresses classified by country (e.g., geoip:cn for China or geoip:private for private networks). This allows:

  • Redirecting traffic for specific countries (e.g., Chinese IPs via direct, others via proxy).

  • Blocking or allowing access to IPs from certain regions.

• geosite.dat includes domain lists grouped by categories (e.g., geosite:cn for Chinese domains, geosite:google for Google services). This is used for:

  • Granular traffic control (e.g., ad domains → block, streaming → proxy).

Sources

3X-UI uses multiple geofiles sources for flexible traffic routing:

Repository	Files	Available geosites
Loyalsoldier/v2ray-rules-dat	geoip.dat geosite.dat	View
🇮🇷 chocolate4u/Iran-v2ray-rules	geoip_IR.dat geosite_IR.dat	View
🇷🇺 runetfreedom/russia-v2ray-rules-dat	geoip_RU.dat geosite_RU.dat	View

Updating geofiles

1. Open panel and click to Xray version

2. Open Geofiles dropdown and update the needed geofile