Files

Whispering Wind d1385ac8c4 feat: add script to manage extra subscription links

Introduces a new script `extra_config.py` to manage additional proxy configurations (vmess, vless, ss, trojan) for subscription links.

2025-08-17 15:33:28 +03:30

scripts

feat: add script to manage extra subscription links

2025-08-17 15:33:28 +03:30

cli_api.py

fix: correct type hints for optional parameters in config_ip_limiter

2025-08-11 23:40:32 +03:30

cli.py

Changes the add_user function's unlimited_user parameter to default to False.

2025-08-13 23:35:02 +03:30

README.md

Update README.md

2025-08-14 23:40:04 +03:30

traffic.py

feat: Merge traffic collection and user kicking

2025-05-10 14:06:55 +03:30

README.md

Hysteria2 Management CLI Guide

This document provides a comprehensive guide to using the cli.py script, a command-line interface for managing Hysteria2 and related services. It covers installation, user management, advanced configurations, and troubleshooting. The commands are organized into sections for clarity. Each command is described with its options, arguments, and expected behavior.

Installation & Setup
Command Categories
Common Usage Examples
Error Handling
Tips & Best Practices
Troubleshooting

Command Categories

🚀 Hysteria2 Server Management

Install Hysteria2

# Install with required port and optional SNI
python3 cli.py install-hysteria2 --port 8080 --sni example.com
python3 cli.py install-hysteria2 -p 8080 -s example.com

# Install with default SNI (bts.com)
python3 cli.py install-hysteria2 --port 8080

Server Operations

# Uninstall Hysteria2
python3 cli.py uninstall-hysteria2

# Update Hysteria2
python3 cli.py update-hysteria2

# Restart Hysteria2 service
python3 cli.py restart-hysteria2

# Change server port
python3 cli.py change-hysteria2-port --port 9090

# Change SNI (Server Name Indication)
python3 cli.py change-hysteria2-sni --sni newdomain.com

Backup & Restore

# Create backup of Hysteria configuration
python3 cli.py backup-hysteria

# Restore from backup file
python3 cli.py restore-hysteria2 /path/to/backup.zip

👥 User Management

List and View Users

# List all users
python3 cli.py list-users

# Get specific user details
python3 cli.py get-user --username john_doe
python3 cli.py get-user -u john_doe

Add New Users

# Add user with basic settings
python3 cli.py add-user -u john_doe -t 50 -e 30

# Add user with custom password and creation date
python3 cli.py add-user \
  --username john_doe \
  --traffic-limit 100 \
  --expiration-days 60 \
  --password mypassword123 \
  --creation-date 2024-01-15

# Add unlimited user (no IP limit checks)
python3 cli.py add-user -u premium_user -t 500 -e 365 --unlimited

Edit Existing Users

# Change username
python3 cli.py edit-user -u old_name --new-username new_name

# Update traffic limit and expiration
python3 cli.py edit-user -u john_doe --new-traffic-limit 200 --new-expiration-days 90

# Renew password and creation date
python3 cli.py edit-user -u john_doe --renew-password --renew-creation-date

# Block/unblock user
python3 cli.py edit-user -u john_doe --blocked
python3 cli.py edit-user -u john_doe --unblocked

# Set unlimited IP access
python3 cli.py edit-user -u john_doe --unlimited-ip
python3 cli.py edit-user -u john_doe --limited-ip

User Operations

# Reset user (clears usage statistics)
python3 cli.py reset-user --username john_doe

# Remove user completely
python3 cli.py remove-user --username john_doe

# Kick user (disconnect active sessions)
python3 cli.py kick-user --username john_doe

User URI & QR Codes

# Show user connection URI
python3 cli.py show-user-uri --username john_doe

# Generate QR code for URI
python3 cli.py show-user-uri -u john_doe --qrcode

# Show IPv6 URI
python3 cli.py show-user-uri -u john_doe --ipv 6

# Show both IPv4 and IPv6 URIs with QR codes
python3 cli.py show-user-uri -u john_doe --all --qrcode

# Generate Singbox sublink
python3 cli.py show-user-uri -u john_doe --singbox

# Generate normal sublink
python3 cli.py show-user-uri -u john_doe --normalsub

# Get JSON format for multiple users
python3 cli.py show-user-uri-json user1 user2 user3

🖥️ Server Information & Monitoring

Traffic and Status

# Show traffic status for all users
python3 cli.py traffic-status

# Update traffic data without GUI (kicks expired users)
python3 cli.py traffic-status --no-gui

Server Information

# Display server information
python3 cli.py server-info

# Show current version
python3 cli.py show-version

# Check for updates
python3 cli.py check-version

Service Status

# Check all services status
python3 cli.py get-services-status

# Check web panel specific services
python3 cli.py get-webpanel-services-status

⚙️ Server Configuration

Obfuscation Management

# Check obfuscation status
python3 cli.py manage_obfs --check

# Enable obfuscation
python3 cli.py manage_obfs --generate

# Disable obfuscation
python3 cli.py manage_obfs --remove

IP Address Management

# Auto-detect and add IP addresses
python3 cli.py ip-address

# Manually edit IP addresses
python3 cli.py ip-address --edit --ipv4 192.168.1.100
python3 cli.py ip-address --edit --ipv6 2001:db8::1
python3 cli.py ip-address --edit -4 192.168.1.100 -6 2001:db8::1

External Node Management

# Add external node
python3 cli.py node add --name Node-DE --ip 45.67.89.123

# List all nodes
python3 cli.py node list

# Delete node
python3 cli.py node delete --name Node-DE

Masquerade Configuration

# Enable masquerade with domain
python3 cli.py masquerade --enable google.com

# Disable masquerade
python3 cli.py masquerade --remove

Geo Files Update

# Update geo files for Iran (default)
python3 cli.py update-geo

# Update for specific country
python3 cli.py update-geo --country china
python3 cli.py update-geo --country russia
python3 cli.py update-geo --country iran

🔧 Advanced Features

TCP Brutal Installation

# Install TCP Brutal optimization
python3 cli.py install-tcp-brutal

WARP Integration

# Install WARP
python3 cli.py install-warp

# Uninstall WARP
python3 cli.py uninstall-warp

# Check WARP status
python3 cli.py warp-status

# Configure WARP settings
python3 cli.py configure-warp --set-all on
python3 cli.py configure-warp --set-popular-sites off
python3 cli.py configure-warp --set-domestic-sites on
python3 cli.py configure-warp --set-block-adult-sites on

# Multiple WARP configurations
python3 cli.py configure-warp \
  --set-all off \
  --set-popular-sites on \
  --set-domestic-sites off \
  --set-block-adult-sites on

Telegram Bot

# Start Telegram bot
python3 cli.py telegram --action start --token YOUR_BOT_TOKEN --adminid YOUR_ADMIN_ID

# Stop Telegram bot
python3 cli.py telegram --action stop

Singbox Service

# Start Singbox service
python3 cli.py singbox --action start --domain example.com --port 8443

# Stop Singbox service
python3 cli.py singbox --action stop

Normal Subscription Service

# Start NormalSub service
python3 cli.py normal-sub --action start --domain example.com --port 8080

# Stop NormalSub service
python3 cli.py normal-sub --action stop

# Edit subpath
python3 cli.py normal-sub --action edit_subpath --subpath newpath123

Web Panel Management

# Start web panel
python3 cli.py webpanel \
  --action start \
  --domain panel.example.com \
  --port 8090 \
  --admin-username admin \
  --admin-password securepass123 \
  --expiration-minutes 60 \
  --debug

# Start with decoy site
python3 cli.py webpanel \
  --action start \
  --domain panel.example.com \
  --port 8090 \
  --admin-username admin \
  --admin-password securepass123 \
  --decoy-path /var/www/html

# Stop web panel
python3 cli.py webpanel --action stop

# Get web panel URL
python3 cli.py get-webpanel-url

# Get API token
python3 cli.py get-webpanel-api-token

# Reset credentials
python3 cli.py reset-webpanel-creds --new-username newadmin
python3 cli.py reset-webpanel-creds --new-password newpass123
python3 cli.py reset-webpanel-creds --new-username newadmin --new-password newpass123

# Setup decoy site
python3 cli.py setup-webpanel-decoy --domain panel.example.com --decoy-path /var/www/decoy

# Stop decoy site
python3 cli.py stop-webpanel-decoy

IP Limiter Service

# Start IP limiter
python3 cli.py start-ip-limit

# Stop IP limiter
python3 cli.py stop-ip-limit

# Configure IP limiter
python3 cli.py config-ip-limit --block-duration 3600 --max-ips 3
python3 cli.py config-ip-limit --block-duration 7200
python3 cli.py config-ip-limit --max-ips 5

Common Usage Examples

Setting Up a New Server

# 1. Install Hysteria2
python3 cli.py install-hysteria2 --port 8080 --sni google.com

# 2. Add IP addresses
python3 cli.py ip-address

# 3. Enable obfuscation
python3 cli.py manage_obfs --generate

# 4. Create first user
python3 cli.py add-user -u testuser -t 50 -e 30

# 5. Get user connection URI
python3 cli.py show-user-uri -u testuser --qrcode

User Management Workflow

# Add premium user with unlimited access
python3 cli.py add-user -u premium_user -t 1000 -e 365 --unlimited

# Monitor user usage
python3 cli.py traffic-status

# Reset user if needed
python3 cli.py reset-user -u premium_user

# Generate connection details
python3 cli.py show-user-uri -u premium_user --all --qrcode

Advanced Server Configuration

# Install optimizations
python3 cli.py install-tcp-brutal
python3 cli.py install-warp

# Configure WARP
python3 cli.py configure-warp --set-popular-sites on --set-block-adult-sites on

# Setup web panel with decoy
python3 cli.py webpanel \
  --action start \
  --domain admin.example.com \
  --port 8443 \
  --admin-username admin \
  --admin-password secure123 \
  --decoy-path /var/www/fake-site

# Start IP limiting
python3 cli.py start-ip-limit
python3 cli.py config-ip-limit --max-ips 2 --block-duration 3600

Error Handling

The CLI includes comprehensive error handling. Common error scenarios:

Missing required parameters: The CLI will show usage information
Invalid user operations: Clear error messages for non-existent users
Service conflicts: Warnings when services are already running/stopped
File permissions: Errors for inaccessible backup files or paths
Network issues: Connection errors during updates or installations

Tips & Best Practices

Regular Monitoring: Use traffic-status regularly to monitor user usage
Backup Strategy: Create backups before major changes using backup-hysteria
Security: Use strong passwords for web panel and rotate them regularly
Performance: Enable TCP Brutal for better performance on high-latency connections
Obfuscation: Enable obfuscation in restrictive network environments
User Management: Use descriptive usernames and set appropriate traffic limits
Monitoring: Check service status regularly with get-services-status

Troubleshooting

Service not starting: Check get-services-status and system logs
Connection issues: Verify firewall settings and port availability
User can't connect: Check user status with get-user and verify URI generation
High resource usage: Monitor with traffic-status and consider IP limiting
SSL issues: Verify domain configuration for web panel and other services

README.md

Hysteria2 Management CLI Guide

Table of Contents

Command Categories

🚀 Hysteria2 Server Management

Install Hysteria2

Server Operations

Backup & Restore

👥 User Management

List and View Users

Add New Users

Edit Existing Users

User Operations

User URI & QR Codes

🖥️ Server Information & Monitoring

Traffic and Status

Server Information

Service Status

⚙️ Server Configuration

Obfuscation Management

IP Address Management

External Node Management

Masquerade Configuration

Geo Files Update

🔧 Advanced Features

TCP Brutal Installation

WARP Integration

Telegram Bot

Singbox Service

Normal Subscription Service

Web Panel Management

IP Limiter Service

Common Usage Examples

Setting Up a New Server

User Management Workflow

Advanced Server Configuration

Error Handling

Tips & Best Practices

Troubleshooting