pjandro/3x-ui
1
0
Fork 0
mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-08-05 06:42:14 +03:00
Code Issues Packages Projects Releases Wiki Activity

v3

Sanaei
2026-06-03 00:45:23 +02:00
parent 44d5e58907
commit 17bb993740
1 changed files with 88 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
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 `<your-panel-url>/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_&lt;alias&gt;.dat` and `geoip_&lt;alias&gt;.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_<alias>.dat` and `geoip_<alias>.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`).