diff --git a/Configuration.md b/Configuration.md index ac65e97..b7afecf 100644 --- a/Configuration.md +++ b/Configuration.md @@ -8,11 +8,12 @@ To manage SSL certificates using ACME: 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. + - **Get SSL (Domain):** Obtain SSL certificates for a domain. - **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. + - **Show Existing Domains:** Display all domain certificates available on the server. + - **Set Cert paths for the panel:** Specify the certificate for your domain to be used by the panel. + - **Get SSL for IP Address:** Issue a short-lived (6-day, auto-renewing) certificate for a bare IP address. ### Certbot @@ -26,61 +27,96 @@ 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: +The management script includes a built-in SSL certificate application for Cloudflare (uses DNS validation, so it also works for wildcard certificates and servers behind Cloudflare's proxy). To use it you need: -- Cloudflare registered email -- Cloudflare Global API Key -- The domain name must be resolved to the current server through Cloudflare +- A **Cloudflare API Token** (recommended) scoped to `Zone:DNS:Edit` for your zone, **or** your Cloudflare registered email + **Global API Key** +- The domain must be managed by Cloudflare (its nameservers point to Cloudflare) -**How to get the Cloudflare Global API Key:** +Run the `x-ui` command in the terminal, then choose `Cloudflare SSL Certificate`. The script will ask whether you are using an **API Token** (`t`, default) or **Global API Key** (`g`), then prompt for the domain. -1. Run the `x-ui` command in the terminal, then choose `Cloudflare SSL Certificate`. -2. Visit the link: [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens). -3. Click on "View Global API Key" (see the screenshot below): +**How to create a scoped API Token (recommended):** + +1. Visit [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens). +2. Click **Create Token → Edit zone DNS** template, scope it to your zone, and create it. +3. Copy the token and paste it into the script when prompted. + +**How to get the Global API Key (alternative):** + +1. Visit the link: [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens). +2. Click on "View Global API Key" (see the screenshot below): ![](https://github.com/MHSanaei/3x-ui/raw/main/media/APIKey1.PNG) -4. You may need to re-authenticate your account. After that, the API Key will be shown (see the screenshot below): +3. You may need to re-authenticate your account. After that, the API Key will be shown (see the screenshot below): ![](https://github.com/MHSanaei/3x-ui/raw/main/media/APIKey2.png) -When using, just enter your `domain name`, `email`, and `API KEY`. The diagram is as follows: +When using the Global API Key, enter your `domain name`, `email`, and `API KEY`. The flow is as follows: ![](https://github.com/MHSanaei/3x-ui/raw/main/media/DetailEnter.png) ## Available environment variables -### `XUI_LOG_LEVEL` -* **Description**: Default log level -* **Type**: `string` -* **Acceptable values**: `debug` | `info` | `warn` | `error` -* **Default value**: `info` +These are read at startup. On a systemd install you can set them in the service environment file (`/etc/default/x-ui`, `/etc/conf.d/x-ui`, or `/etc/sysconfig/x-ui`, depending on distro); for Docker, pass them with `-e` / the `environment:` block. -### `XUI_DEBUG` -* **Description**: Whether debug mode should be enabled -* **Type**: `boolean` -* **Default value**: `false` +### `XUI_DB_TYPE` +* **Description**: Database backend +* **Type**: `string` +* **Acceptable values**: `sqlite` | `postgres` +* **Default value**: `sqlite` + +### `XUI_DB_DSN` +* **Description**: PostgreSQL connection string (used when `XUI_DB_TYPE=postgres`) +* **Type**: `string` +* **Default value**: — (empty) +* **Example**: `postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable` + +### `XUI_DB_FOLDER` +* **Description**: Path to the folder holding the SQLite database file +* **Type**: `string` +* **Default value**: `/etc/x-ui` + +### `XUI_DB_MAX_OPEN_CONNS` +* **Description**: Maximum number of open database connections +* **Type**: `integer` +* **Default value**: `25` (PostgreSQL) / `8` (SQLite) + +### `XUI_DB_MAX_IDLE_CONNS` +* **Description**: Maximum number of idle database connections +* **Type**: `integer` +* **Default value**: `25` (PostgreSQL) / `4` (SQLite) ### `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 +### `XUI_LOG_LEVEL` +* **Description**: Default log level * **Type**: `string` -* **Default value**: `/etc/x-ui` +* **Acceptable values**: `debug` | `info` | `notice` | `warning` | `error` +* **Default value**: `info` ### `XUI_LOG_FOLDER` * **Description**: Path to the logs * **Type**: `string` -* **Default value**: `/var/log` +* **Default value**: `/var/log/x-ui` + +### `XUI_DEBUG` +* **Description**: Whether debug mode should be enabled (forces the log level to `debug`) +* **Type**: `boolean` +* **Default value**: `false` ### `XUI_ENABLE_FAIL2BAN` -* **Description**: Should [fail2ban](https://github.com/fail2ban/fail2ban) be working +* **Description**: Should [fail2ban](https://github.com/fail2ban/fail2ban) enforce per-client IP limits * **Type**: `boolean` * **Default value**: `true` +### `XUI_SKIP_HSTS` +* **Description**: Skip sending the `Strict-Transport-Security` (HSTS) header — useful when terminating TLS at a reverse proxy +* **Type**: `boolean` +* **Default value**: `false` + ## Reverse Proxy ### Nginx @@ -109,7 +145,7 @@ location / { > [!NOTE] > The URL in the panel settings needs to end with /. -For the subscriptions +For the subscriptions (the default subscription port is `2096`) ```nginx location /sub { @@ -141,7 +177,7 @@ location /sub { > A huge thanks to [@Gill-Bates](https://github.com/Gill-Bates) for providing the config > [!IMPORTANT] -> This configuration will work when the “WebSocket” transport is set inbound +> 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 @@ -199,7 +235,7 @@ 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 +If you do not need HTTP Auth, remove the following lines ```caddyfile basic_auth { @@ -212,49 +248,38 @@ basic_auth { ## Setting Fail2Ban +The bundled Fail2ban integration enforces per-client **IP limits**: when a client exceeds its allowed number of simultaneous IPs, the offending address is temporarily banned. + > [!NOTE] -> IP Limit won't work correctly when using IP Tunnel. +> The IP limit won't work correctly when using an IP Tunnel. -### **For versions up to `v1.6.1`:** +To set it up, run the `x-ui` command in the terminal and choose `IP Limit Management`. You will see the following options: -The IP limit is built-in to the panel +- **Install Fail2ban and configure IP Limit:** Install Fail2ban and set up the 3x-ui jail. +- **Change Ban Duration:** Adjust how long bans last. +- **Unban Everyone:** Lift all current bans. +- **Ban Logs:** View the ban history. +- **Ban an IP Address:** Manually ban an IP. +- **Unban an IP Address:** Manually unban an IP. +- **Real-Time Logs:** Follow the live Fail2ban log. +- **Service Status:** Check the status of `fail2ban`. +- **Service Restart:** Restart the `fail2ban` service. +- **Uninstall Fail2ban and IP Limit:** Remove Fail2ban and its configuration. -### **For versions `v1.7.0` and newer:** +Then enable the access log so Fail2ban can read client connections: in the panel go to `Xray Configs`, set the `log → Access log` path to `./access.log`, save, and restart Xray. -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: - - ```sh - "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. +> [!TIP] +> On Docker, Fail2ban is bundled and enabled by default (`XUI_ENABLE_FAIL2BAN=true`). It needs the `NET_ADMIN` (and `NET_RAW` for IPv6) capabilities to apply bans with iptables — see the Docker installation section. --- # API Documentation -- [API Documentation Postman](https://documenter.getpostman.com/view/5146551/2sBXwnsBko) +3X-UI ships an interactive **Swagger UI** built into the panel. Open the panel and click **API Docs** in the sidebar to browse every endpoint, see request/response schemas, and try calls live against your server. +- The OpenAPI 3 specification is served at `/panel/api/openapi.json`. +- API requests authenticate with your panel session cookie, or with an **API token** created under `Settings`. +- [API Documentation (Postman)](https://documenter.getpostman.com/view/5146551/2sBXwnsBko) — community-maintained collection. ## Geosites @@ -294,7 +319,7 @@ The Geosites in Xray-core play a key role in traffic routing, enabling flexible ## Custom GeoSite / GeoIP DAT sources -Administrators can add custom GeoSite and GeoIP `.dat` files from URLs in the panel (same workflow as updating built-in geofiles). Files are stored under the same directory as the Xray binary (`XUI_BIN_FOLDER`, default `bin/`) with deterministic names: `geosite_<alias>.dat` and `geoip_<alias>.dat`. +Administrators can add custom GeoSite and GeoIP `.dat` files from URLs in the panel (same workflow as updating built-in geofiles). Files are stored under the same directory as the Xray binary (`XUI_BIN_FOLDER`, default `bin/`) with deterministic names: `geosite_.dat` and `geoip_.dat`. **Routing:** Xray resolves extra lists using the `ext:` form, for example `ext:geosite_myalias.dat:tag` or `ext:geoip_myalias.dat:tag`, where `tag` is a list name inside that DAT file (same pattern as built-in regional files such as `ext:geoip_IR.dat:ir`).