Home

Awesome

<p align="center"> <a href="https://github.com/gozargah/marzban" target="_blank" rel="noopener noreferrer"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/Gozargah/Marzban-docs/raw/master/screenshots/logo-dark.png"> <img width="160" height="160" src="https://github.com/Gozargah/Marzban-docs/raw/master/screenshots/logo-light.png"> </picture> </a> </p> <h1 align="center"/>Marzban</h1> <p align="center"> Unified GUI Censorship Resistant Solution Powered by <a href="https://github.com/XTLS/Xray-core">Xray</a> </p> <br/> <p align="center"> <a href="#"> <img src="https://img.shields.io/github/actions/workflow/status/gozargah/marzban/build.yml?style=flat-square" /> </a> <a href="https://hub.docker.com/r/gozargah/marzban" target="_blank"> <img src="https://img.shields.io/docker/pulls/gozargah/marzban?style=flat-square&logo=docker" /> </a> <a href="#"> <img src="https://img.shields.io/github/license/gozargah/marzban?style=flat-square" /> </a> <a href="https://t.me/gozargah_marzban" target="_blank"> <img src="https://img.shields.io/badge/telegram-group-blue?style=flat-square&logo=telegram" /> </a> <a href="#"> <img src="https://img.shields.io/badge/twitter-commiunity-blue?style=flat-square&logo=twitter" /> </a> <a href="#"> <img src="https://img.shields.io/github/stars/gozargah/marzban?style=social" /> </a> </p> <p align="center"> <a href="./README.md"> English </a> / <a href="./README-fa.md"> فارسی </a> / <a href="./README-zh-cn.md"> 简体中文 </a> / <a href="./README-ru.md"> Русский </a> </p> <p align="center"> <a href="https://github.com/gozargah/marzban" target="_blank" rel="noopener noreferrer" > <img src="https://github.com/Gozargah/Marzban-docs/raw/master/screenshots/preview.png" alt="Marzban screenshots" width="600" height="auto"> </a> </p>

Table of Contents

Overview

Marzban (the Persian word for "border guard" - pronounced /mærz'ban/) 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 Marzban?

Marzban 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

Installation guide

Run the following command

sudo bash -c "$(curl -sL https://github.com/Gozargah/Marzban-scripts/raw/master/marzban.sh)" @ install

Once the installation is complete:

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

marzban cli admin create --sudo

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

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

marzban --help

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

<details markdown="1"> <summary><h3>Manual install (advanced)</h3></summary>

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.8)

git clone https://github.com/Gozargah/Marzban.git
cd Marzban
wget -qO- https://bootstrap.pypa.io/get-pip.py | python3 -
python3 -m pip install -r requirements.txt

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

Then run the following command to run the database migration scripts

alembic upgrade head

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

sudo ln -s $(pwd)/marzban-cli.py /usr/bin/marzban-cli
sudo chmod +x /usr/bin/marzban-cli
marzban-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

python3 main.py

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

systemctl enable /var/lib/marzban/marzban.service
systemctl start marzban

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|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: /marzban/me/2087
    #
    # All traffic is proxed through port 443, and send to the xray port(2087, 2088 etc.).
    # The '/marzban' in location regex path can changed any characters by yourself.
    #
    # /${path}/${username}/${xray-port}
    location ~* /marzban/.+/(.+)$ {
        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  marzban.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.

</details>

Configuration

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

VariableDescription
SUDO_USERNAMESuperuser's username
SUDO_PASSWORDSuperuser's password
SQLALCHEMY_DATABASE_URLDatabase URL (SQLAlchemy's docs)
UVICORN_HOSTBind application to this host (default: 0.0.0.0)
UVICORN_PORTBind application to this port (default: 8000)
UVICORN_UDSBind application to a UNIX domain socket
UVICORN_SSL_CERTFILESSL certificate file to have application on https
UVICORN_SSL_KEYFILESSL key file to have application on https
XRAY_JSONPath of Xray's json config file (default: xray_config.json)
XRAY_EXECUTABLE_PATHPath of Xray binary (default: /usr/local/bin/xray)
XRAY_ASSETS_PATHPath of Xray assets (default: /usr/local/share/xray)
XRAY_SUBSCRIPTION_URL_PREFIXPrefix of subscription URLs
XRAY_FALLBACKS_INBOUND_TAGTag of the inbound that includes fallbacks, needed in the case you're using fallbacks
XRAY_EXCLUDE_INBOUND_TAGSTags of the inbounds that shouldn't be managed and included in links by application
CUSTOM_TEMPLATES_DIRECTORYCustomized templates directory (default: app/templates)
CLASH_SUBSCRIPTION_TEMPLATEThe template that will be used for generating clash configs (default: clash/default.yml)
SUBSCRIPTION_PAGE_TEMPLATEThe template used for generating subscription info page (default: subscription/index.html)
HOME_PAGE_TEMPLATEDecoy page template (default: home/index.html)
TELEGRAM_API_TOKENTelegram bot API token (get token from @botfather)
TELEGRAM_ADMIN_IDNumeric Telegram ID of admin (use @userinfobot to found your ID)
TELEGRAM_PROXY_URLRun Telegram Bot over proxy
JWT_ACCESS_TOKEN_EXPIRE_MINUTESExpire time for the Access Tokens in minutes, 0 considered as infinite (default: 1440)
DOCSWhether API documents should be available on /docs and /redoc or not (default: False)
DEBUGDebug mode for development (default: False)
WEBHOOK_ADDRESSWebhook address to send notifications to. Webhook notifications will be sent if this value was set.
WEBHOOK_SECRETWebhook secret will be sent with each request as x-webhook-secret in the header (default: None)
NUMBER_OF_RECURRENT_NOTIFICATIONSHow many times to retry if an error detected in sending a notification (default: 3)
RECURRENT_NOTIFICATIONS_TIMEOUTTimeout between each retry if an error detected in sending a notification in seconds (default: 180)
NOTIFY_REACHED_USAGE_PERCENTAt which percentage of usage to send the warning notification (default: 80)
NOTIFY_DAYS_LEFTWhen to send warning notifaction about expiration (default: 3)
USERS_AUTODELETE_DAYSDelete expired (and optionally limited users) after this many days (Negative values disable this feature, default: -1)
USER_AUTODELETE_INCLUDE_LIMITED_ACCOUNTSWeather to include limited accounts in the auto-delete feature (default: False)
USE_CUSTOM_JSON_DEFAULTEnable custom JSON config for ALL supported clients (default: False)
USE_CUSTOM_JSON_FOR_V2RAYNGEnable custom JSON config only for V2rayNG (default: False)
USE_CUSTOM_JSON_FOR_STREISANDEnable custom JSON config only for Streisand (default: False)
USE_CUSTOM_JSON_FOR_V2RAYNEnable custom JSON config only for V2rayN (default: False)

API

Marzban provides a REST API that enables developers to interact with Marzban 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 Marzban files regularly to prevent data loss in case of system failures or accidental deletion. Here are the steps to backup Marzban:

  1. By default, all Marzban important files are saved in /var/lib/marzban (Docker versions). Copy the entire /var/lib/marzban 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 Marzban using marzban-scripts (recommended installation approach), the env and other configurations should be inside /opt/marzban/ directory.

By following these steps, you can ensure that you have a backup of all your Marzban 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

Marzban 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 Marzban 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

Marzban CLI

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

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

marzban cli [OPTIONS] COMMAND [ARGS]...

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

Marzban Node

The Marzban project introduces the Marzban-node, which revolutionizes infrastructure distribution. With Marzban-node, you can distribute your infrastructure across multiple locations, unlocking benefits such as redundancy, high availability, scalability, flexibility. Marzban-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 Marzban-node official documentation

Webhook notifications

You can set a webhook address and Marzban 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 Marzban:

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": "marzban_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 Marzban useful and would like to support its development, you can make a donation in one of the following crypto networks:

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.

<p align="center"> Thanks to the all contributors who have helped improve Marzban: </p> <p align="center"> <a href="https://github.com/Gozargah/Marzban/graphs/contributors"> <img src="https://contrib.rocks/image?repo=Gozargah/Marzban" /> </a> </p> <p align="center"> Made with <a rel="noopener noreferrer" target="_blank" href="https://contrib.rocks">contrib.rocks</a> </p>