gozargah-node icon indicating copy to clipboard operation
gozargah-node copied to clipboard

verified publisher icon M03ED
→

Metadata

Gozargah-Node-Go

Attention ⚠️

This project is in the testing and development stage. The code may undergo major changes during this phase, so use it at your own risk.

Table of Contents

  • Overview
    • Why Use Gozargah Node?
    • Supported Cores
  • Documentation
    • Configuration
    • SSL Configuration
    • API
      • Data Structure
      • Methods
  • Official library
    • Go
    • Python
  • Donation
  • Contributors

Overview

Gozargah Node is developed by the Gozargah team to replace Marzban-node. It aims to be more stable, scalable, and efficient.

Why Use Gozargah Node?

We designed this project to be usable in any project, even without Marzban. You can run nodes with a simple script and the help of official libraries.
We plan to expand supported cores after the testing stage, allowing you to use any core you want.

Supported Cores

Core Support
xray-core ✅
sing-box ❌
v2ray-core ❌

Documentation

Configuration

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

Variable Description
SERVICE_PORT Bind application to this port (default: 62050).
NODE_HOST Bind application to this host (default: 127.0.0.1).
XRAY_EXECUTABLE_PATH Path of Xray binary (default: /usr/local/bin/xray).
XRAY_ASSETS_PATH Path of Xray assets (default: /usr/local/share/xray).
SSL_CERT_FILE SSL certificate file to secure the application between master and node (it will generate a self-signed SSL if it doesn't exist; better to use a real SSL with a domain).
SSL_KEY_FILE SSL key file to secure the application between master and node (it will generate a self-signed SSL if it doesn't exist; better to use a real SSL with a domain).
API_KEY Api Key to ensure only allowed clients can connect (type: UUID).
SERVICE_PROTOCOL Protocol to use: grpc or rest (recommended: grpc).
MAX_LOG_PER_REQUEST Maximum number of logs per request (only for long polling in REST connections).
DEBUG Debug mode for development; prints core logs in the node server (default: False).
GENERATED_CONFIG_PATH Path to the generated config by the node (default: /var/lib/gozargah-node/generated).

SSL Configuration

SSL Certificates

You can use SSL certificates issued by Let's Encrypt or other certificate authorities.
Make sure to set both SSL_CERT_FILE and SSL_KEY_FILE environment variables. Use fullchain for SSL_CERT_FILE and cert as server_ca in client side.

mTLS

If you don't have access to a real domain or tools like ACME, you can use mTLS to connect to a node.
Just replace the CN and subjectAltName values with your server information:

openssl req -x509 -newkey rsa:4096 -keyout /var/lib/gozargah-node/certs/ssl_key.pem \
  -out /var/lib/gozargah-node/certs/ssl_cert.pem -days 36500 -nodes \
  -subj "/CN={replace with your server IP or domain}" \
  -addext "subjectAltName = {replace with alternative names you need}"

API

Gozargah Node supports two types of connection protocols: gRPC and REST API.
We recommend using gRPC, with REST always available as a fallback option (in case there is a problem with gRPC).

Data Structure

The node uses the common/service.proto file messages for both protocols.

Message Description
Empty Used when no input is required. Can replace null with Empty.
BaseInfoResponse Contains:
- started (bool): Indicates if the service is started.
- core_version (string): Version of the core.
- node_version (string): Version of the node.
- session_id (string): Session ID.
- extra (string): Additional information.
Vmess Contains:
- id (string): UUID for Vmess configuration.
Vless Contains:
- id (string): UUID for Vless configuration.
- flow (string): Currently only supports xtls-rprx-vision.
Trojan Contains:
- password (string): Password for Trojan configuration.
Shadowsocks Contains:
- password (string): Password for Shadowsocks.
- method (string): Encryption method. Supported methods: aes-128-gcm, aes-256-gcm, chacha20-poly1305, xchacha20-poly1305.
Proxy Contains:
- vmess (Vmess): Vmess configuration.
- vless (Vless): Vless configuration.
- trojan (Trojan): Trojan configuration.
- shadowsocks (Shadowsocks): Shadowsocks configuration.
User Contains:
- email (string): User's email.
- proxies (Proxy): Proxy configurations.
- inbounds ([]string): List of inbounds.
BackendType Enum:
- XRAY = 0: Represents the Xray backend type.
Backend Contains:
- type (BackendType): Type of backend.
- config (string): Configuration for the backend.
- users ([]User): List of users.
- keepAlive (uint64): hold backend alive for x second after last connection
Log Contains:
- detail (string): Log details.
Stat Contains:
- name (string): Stat name.
- type (string): Stat type.
- link (string): Link associated with the stat.
- value (int64): Stat value.
StatResponse Contains:
- stats ([]Stat): List of stats.
StatRequest Contains:
- name (string): Name of the stat to request, user email or inbound \ outbound tag.
- reset (bool) Whether to reset traffic stats.
OnlineStatResponse Contains:
- name (string): User's email.
- value (int64): Online connection number.
OnlineStatResponse Contains:
- name (string): User's email.
- value (map<string, int64>): Online stat value.
BackendStatsResponse Contains:
- num_goroutine (uint32): Number of goroutines.
- num_gc (uint32): Number of garbage collections.
- alloc (uint64): Allocated memory.
- total_alloc (uint64): Total allocated memory.
- sys (uint64): System memory.
- mallocs (uint64): Number of mallocs.
- frees (uint64): Number of frees.
- live_objects (uint64): Number of live objects.
- pause_total_ns (uint64): Total pause time in nanoseconds.
- uptime (uint32): Uptime in seconds.
SystemStatsResponse Contains:
- mem_total (uint64): Total memory.
- mem_used (uint64): Used memory.
- cpu_cores (uint64): Number of CPU cores.
- cpu_usage (double): CPU usage percentage.
- incoming_bandwidth_speed (uint64): Incoming bandwidth speed.
- outgoing_bandwidth_speed (uint64): Outgoing bandwidth speed.
Users Contains:
- users ([]User): List of users.

Note: The node receives data with x-protobuf as the content type in the REST API.

Methods

  • Add address:port at the beginning of the REST API URL.
  • Use Authorization Bearer <session_id> in the header for authentication with the REST API.
  • Use authorization Bearer <session_id> in metadata for authentication with gRPC.
gRPC REST Input Output Description
Start() POST,/start Backend BaseInfoResponse This is the only method called before creating a connection.
Stop() PUT,/stop Empty Empty Stops the backend and deactivates the connection with the client.
GetBaseInfo() GET,/info Empty BaseInfoResponse Returns base info; can be used to check the connection between the node and client.
GetLogs() GET,/logs Empty gRPC: (stream Log)
REST API: (SSE)		 This method is a SSE connection in the REST protocol, but in gRPC, it provides a stream connection.
GetSystemStats() GET,/stats/system Empty SystemStatsResponse Retrieves system statistics.
GetBackendStats() GET,/stats/backend Empty BackendStatsResponse Retrieves backend statistics.
GetOutboundsStats() GET, /stats/outbounds StatRequest StatResponse Retrieves outbound statistics. The name field in the request will be ignored.
GetOutboundStats() GET,/stats/outbound StatRequest StatResponse Retrieves statistics for a specific outbound.
GetInboundsStats() GET,/stats/inbounds StatRequest StatResponse Retrieves inbound statistics. The name field in the request will be ignored.
GetInboundStats() GET,/stats/inbound StatRequest StatResponse Retrieves statistics for a specific inbound.
GetUsersStats() GET,/stats/users StatRequest StatResponse Retrieves user statistics and resets traffic stats. The name field in the request will be ignored.
GetUserStats() GET,/stats/user StatRequest StatResponse Retrieves statistics for a specific user.
GetUserOnlineStats() GET,/stats/user/online StatRequest OnlineStatResponse Retrieves online statistics for a specific user. The reset field in the request will be ignored
GetUserOnlineIpListStats() GET,/stats/user/online_ip StatRequest StatsOnlineIpListResponse Retrieves ip list statistics for a specific user. The reset field in the request will be ignored
SyncUser() PUT,/user/sync User Empty Adds/updates/removes a user in the core. To remove a user, ensure you send empty inbounds. Provides a stream in gRPC but must be called for each user in the REST API.
SyncUsers() PUT,/users/sync Users Empty Removes all old users and replaces them with the provided users.

Official library

We create some library's for you so make your job easier

Go

gozargah-node-bridge

To add bridge to your project use:

go get github.com/m03ed/gozargah_node_bridge

Python

gozargah-node-bridge-py

pip install gozargah-node-bridge

Donation

You can help gozargah team with your donations, Click Here

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 Gozargah Node:

Made with contrib.rocks

← Metadata

17
Stars
3
Forks
Watchers

Owner

verified publisher icon M03ED

Metadata

Back