PasarGuard

Unified GUI Censorship Resistant Solution

English / فارسی / 简体中文 / Русский

Table of Contents

• Overview
  • Why using PasarGuard?
    • Features
• Installation guide
• Configuration
• Documentation
• API
• Backup
• Telegram Bot
• PasarGuard CLI
• PasarGuard Node
• Webhook notifications
• Donation
• License
• Contributors

Overview

PasarGuard is a proxy management tool that provides a simple and easy-to-use user interface for managing hundreds of proxy accounts powered by Xray-core and built using Python and Reactjs.

Why using PasarGuard?

PasarGuard is user-friendly, feature-rich and reliable. It lets you to create different proxies for your users without any complicated configuration. Using its built-in web UI, you are able to monitor, modify and limit users.

Features

• Built-in Web UI
• Fully REST API backend
• Multiple Nodes support (for infrastructure distribution & scalability)
• Supports protocols Vmess, VLESS, Trojan and Shadowsocks
• Multi-protocol for a single user
• Multi-user on a single inbound
• Multi-inbound on a single port (fallbacks support)
• Traffic and expiry date limitations
• Periodic traffic limit (e.g. daily, weekly, etc.)
• Subscription link compatible with V2ray (such as V2RayNG, SingBox, Nekoray, etc.), Clash and ClashMeta
• Automated Share link and QRcode generator
• System monitoring and traffic statistics
• Customizable xray configuration
• TLS and REALITY support
• Integrated Telegram Bot
• Integrated Command Line Interface (CLI)
• Multi-language
• Multi-admin support (WIP)

Installation guide

⚠️ The following commands will install the pre release versions (alpha/beta)

Run the following command to install PasarGuard with SQLite database:

sudo bash -c "$(curl -sL https://github.com/PasarGuard/scripts/raw/main/pasarguard.sh)" @ install --pre-release

Run the following command to install PasarGuard with MySQL database:

sudo bash -c "$(curl -sL https://github.com/PasarGuard/scripts/raw/main/pasarguard.sh)" @ install --database mysql --pre-release

Run the following command to install PasarGuard with MariaDB database:

sudo bash -c "$(curl -sL https://github.com/PasarGuard/scripts/raw/main/pasarguard.sh)" @ install --database mariadb --pre-release

Run the following command to install PasarGuard with PostgreSQL database:

sudo bash -c "$(curl -sL https://github.com/PasarGuard/scripts/raw/main/pasarguard.sh)" @ install --database postgresql --pre-release

Once the installation is complete:

• You will see the logs that you can stop watching them by closing the terminal or pressing Ctrl+C
• The PasarGuard files will be located at /opt/pasarguard
• The configuration file can be found at /opt/pasarguard/.env (refer to configurations section to see variables)
• The data files will be placed at /var/lib/pasarguard
• For security reasons, the PasarGuard dashboard is not accessible via IP address. Therefore, you must obtain SSL certificate and access your PasarGuard dashboard by opening a web browser and navigating to https://YOUR_DOMAIN:8000/dashboard/ (replace YOUR_DOMAIN with your actual domain)
• You can also use SSH port forwarding to access the PasarGuard dashboard locally without a domain. Replace user@serverip with your actual SSH username and server IP and Run the command below:

ssh -L 8000:localhost:8000 user@serverip

Finally, you can enter the following link in your browser to access your PasarGuard dashboard:

http://localhost:8000/dashboard/

You will lose access to the dashboard as soon as you close the SSH terminal. Therefore, this method is recommended only for testing purposes.

Next, you need to create a sudo admin for logging into the PasarGuard dashboard by the following command

pasarguard cli admin create --sudo

That's it! You can login to your dashboard using these credentials

To see the help message of the PasarGuard script, run the following command

pasarguard --help

If you are eager to run the project using the source code, check the section below

Manual install (advanced)

Install xray on your machine

You can install it using Xray-install

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

Clone this project and install the dependencies (you need Python >= 3.12.7)

git clone https://github.com/PasarGuard/panel.git
cd PasarGuard
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

Alternatively, to have an isolated environment you can use Python Virtualenv

Then run the following command to run the database migration scripts

uv run alembic upgrade head

If you want to use PasarGuard-cli, you should link it to a file in your $PATH, make it executable, and install the auto-completion:

sudo ln -s $(pwd)/PasarGuard-cli.py /usr/bin/pasarguard-cli
sudo chmod +x /usr/bin/pasarguard-cli
pasarguard-cli completion install

Now it's time to configuration

Make a copy of .env.example file, take a look and edit it using a text editor like nano.

You probably like to modify the admin credentials.

cp .env.example .env
nano .env

Check configurations section for more information

Eventually, launch the application using command below

uv run main.py

To launch with linux systemctl (copy PasarGuard.service file to /var/lib/pasarguard/PasarGuard.service)

systemctl enable /var/lib/pasarguard/PasarGuard.service
systemctl start PasarGuard

To use with nginx

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name  example.com;

    ssl_certificate      /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/example.com/privkey.pem;

    location ~* /(dashboard|statics|sub|api|docs|redoc|openapi.json) {
        proxy_pass http://0.0.0.0:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # xray-core ws-path: /
    # client ws-path: /PasarGuard/me/2087
    #
    # All traffic is proxed through port 443, and send to the xray port(2087, 2088 etc.).
    # The '/PasarGuard' in location regex path can changed any characters by yourself.
    #
    # /${path}/${username}/${xray-port}
    location ~* /PasarGuard/.+/(.+)$ {
        proxy_redirect off;
        proxy_pass http://127.0.0.1:$1/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

or

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name  PasarGuard.example.com;

    ssl_certificate      /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/example.com/privkey.pem;

    location / {
        proxy_pass http://0.0.0.0:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

By default the app will be run on http://localhost:8000/dashboard. You can configure it using changing the UVICORN_HOST and UVICORN_PORT environment variables.

Configuration

You can set settings below using environment variables or placing them in .env file.

Variable	Description
SUDO_USERNAME	Superuser's username
SUDO_PASSWORD	Superuser's password
SQLALCHEMY_DATABASE_URL	Database URL (SQLAlchemy's docs)
SQLALCHEMY_POOL_SIZE	(default: 10)
SQLALCHEMY_MAX_OVERFLOW	(default: 30)
UVICORN_HOST	Bind application to this host (default: 0.0.0.0)
UVICORN_PORT	Bind application to this port (default: 8000)
UVICORN_UDS	Bind application to a UNIX domain socket
UVICORN_SSL_CERTFILE	SSL certificate file to have application on https
UVICORN_SSL_KEYFILE	SSL key file to have application on https
UVICORN_SSL_CA_TYPE	Type of authority SSL certificate. Use private for testing self-signed CA (default: public)
XRAY_JSON	Path of Xray's json config file (default: xray_config.json)
CUSTOM_TEMPLATES_DIRECTORY	Customized templates directory (default: app/templates)
CLASH_SUBSCRIPTION_TEMPLATE	The template that will be used for generating clash configs (default: clash/default.yml)
SUBSCRIPTION_PAGE_TEMPLATE	The template used for generating subscription info page (default: subscription/index.html)
XRAY_SUBSCRIPTION_TEMPLATE	The template that will be used for generating xray configs (default: xray/default.yml)
SINGBOX_SUBSCRIPTION_TEMPLATE	The template that will be used for generating xray configs (default: xray/default.yml)
HOME_PAGE_TEMPLATE	Decoy page template (default: home/index.html)
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	Expire time for the Access Tokens in minutes, 0 considered as infinite (default: 1440)
DOCS	Whether API documents should be available on /docs and /redoc or not (default: False)
DEBUG	Debug mode for development (default: False)
USERS_AUTODELETE_DAYS	Delete expired (and optionally limited users) after this many days (Negative values disable this feature, default: -1)
USER_AUTODELETE_INCLUDE_LIMITED_ACCOUNTS	Whether to include limited accounts in the auto-delete feature (default: False)
XRAY_SUBSCRIPTION_PATH	You can change your api path for subscrtiption (default: sub)
ENABLE_RECORDING_NODES_STATS	Due to high amount of data, this job is only available for postgresql and timescaledb

Documentation

The PasarGuard Documentation provides all the essential guides to get you started, available in three languages: Farsi, English, and Russian. This documentation requires significant effort to cover all aspects of the project comprehensively. We welcome and appreciate your contributions to help us improve it. You can contribute on this GitHub repository.

API

PasarGuard provides a REST API that enables developers to interact with PasarGuard services programmatically. To view the API documentation in Swagger UI or ReDoc, set the configuration variable DOCS=True and navigate to the /docs and /redoc.

Backup

It's always a good idea to backup your PasarGuard files regularly to prevent data loss in case of system failures or accidental deletion. Here are the steps to backup PasarGuard:

1. By default, all PasarGuard important files are saved in /var/lib/pasarguard (Docker versions). Copy the entire /var/lib/pasarguard directory to a backup location of your choice, such as an external hard drive or cloud storage.
2. Additionally, make sure to backup your env file, which contains your configuration variables, and also, your Xray config file. If you installed PasarGuard using PasarGuard-scripts (recommended installation approach), the env and other configurations should be inside /opt/pasarguard/ directory.

PasarGuard's backup service efficiently zips all necessary files and sends them to your specified Telegram bot. It supports SQLite, MySQL, and MariaDB databases. One of its key features is automation, allowing you to schedule backups every hour. There are no limitations concerning Telegram's upload limits for bots; if a file exceeds the limit, it will be split and sent in multiple parts. Additionally, you can initiate an immediate backup at any time.

Install the Latest Version of PasarGuard Command:

sudo bash -c "$(curl -sL https://github.com/PasarGuard/scripts/raw/main/pasarguard.sh)" @ install-script

Setup the Backup Service:

pasarguard backup-service

Get an Immediate Backup:

pasarguard backup

By following these steps, you can ensure that you have a backup of all your PasarGuard files and data, as well as your configuration variables and Xray configuration, in case you need to restore them in the future. Remember to update your backups regularly to keep them up-to-date.

Telegram Bot

PasarGuard comes with an integrated Telegram bot that can handle server management, user creation and removal, and send notifications. This bot can be easily enabled by following a few simple steps, and it provides a convenient way to interact with PasarGuard without having to log in to the server every time.

To enable Telegram Bot:

1. set TELEGRAM_API_TOKEN to your bot's API Token
2. set TELEGRAM_ADMIN_ID to your Telegram account's numeric ID, you can get your ID from @userinfobot

PasarGuard CLI

PasarGuard comes with an integrated CLI named PasarGuard-cli which allows administrators to have direct interaction with it.

If you've installed PasarGuard using easy install script, you can access the cli commands by running

pasarguard cli [OPTIONS] COMMAND [ARGS]...

For more information, You can read PasarGuard CLI's documentation.

PasarGuard TUI

PasarGuard also provides a Terminal User Interface (TUI) for interactive management directly within your terminal.

If you've installed PasarGuard using the easy install script, you can access the TUI by running:

pasarguard tui

For more information, you can read PasarGuard TUI's documentation.

Node

The PasarGuard project introduces the node, which revolutionizes infrastructure distribution. With node, you can distribute your infrastructure across multiple locations, unlocking benefits such as redundancy, high availability, scalability, flexibility. node empowers users to connect to different servers, offering them the flexibility to choose and connect to multiple servers instead of being limited to only one server. For more detailed information and installation instructions, please refer to the PasarGuard-node official documentation

Webhook notifications

You can set a webhook address and PasarGuard will send the notifications to that address.

the requests will be sent as a post request to the adress provided by WEBHOOK_ADDRESS with WEBHOOK_SECRET as x-webhook-secret in the headers.

Example request sent from PasarGuard:

Headers:
Host: 0.0.0.0:9000
User-Agent: python-requests/2.28.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
x-webhook-secret: something-very-very-secret
Content-Length: 107
Content-Type: application/json



Body:
{"username": "PasarGuard_test_user", "action": "user_updated", "enqueued_at": 1680506457.636369, "tries": 0}

Different action typs are: user_created, user_updated, user_deleted, user_limited, user_expired, user_disabled, user_enabled

Donation

If you found PasarGuard useful and would like to support its development, you can make a donation, Click Here

Thank you for your support!

License

Made in [Unknown!] and Published under AGPL-3.0.

Contributors

We ❤️‍🔥 contributors! If you'd like to contribute, please check out our Contributing Guidelines and feel free to submit a pull request or open an issue. We also welcome you to join our Telegram group for either support or contributing guidance.

Check open issues to help the progress of this project.

Thanks to the all contributors who have helped improve PasarGuard:

Made with contrib.rocks