465 lines
12 KiB
Markdown
465 lines
12 KiB
Markdown
# 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.
|
||
|
||
---
|
||
## Table of Contents
|
||
|
||
- [Installation & Setup](#installation--setup)
|
||
- [Command Categories](#command-categories)
|
||
- [🚀 Hysteria2 Server Management](#-hysteria2-server-management)
|
||
- [Install Hysteria2](#install-hysteria2)
|
||
- [Server Operations](#server-operations)
|
||
- [Backup & Restore](#backup--restore)
|
||
- [👥 User Management](#-user-management)
|
||
- [List and View Users](#list-and-view-users)
|
||
- [Add New Users](#add-new-users)
|
||
- [Edit Existing Users](#edit-existing-users)
|
||
- [User Operations](#user-operations)
|
||
- [User URI & QR Codes](#user-uri--qr-codes)
|
||
- [🖥️ Server Information & Monitoring](#️-server-information--monitoring)
|
||
- [Traffic and Status](#traffic-and-status)
|
||
- [Server Information](#server-information)
|
||
- [Service Status](#service-status)
|
||
- [⚙️ Server Configuration](#️-server-configuration)
|
||
- [Obfuscation Management](#obfuscation-management)
|
||
- [IP Address Management](#ip-address-management)
|
||
- [External Node Management](#external-node-management)
|
||
- [Masquerade Configuration](#masquerade-configuration)
|
||
- [Geo Files Update](#geo-files-update)
|
||
- [🔧 Advanced Features](#-advanced-features)
|
||
- [TCP Brutal Installation](#tcp-brutal-installation)
|
||
- [WARP Integration](#warp-integration)
|
||
- [Telegram Bot](#telegram-bot)
|
||
- [Singbox Service](#singbox-service)
|
||
- [Normal Subscription Service](#normal-subscription-service)
|
||
- [Web Panel Management](#web-panel-management)
|
||
- [IP Limiter Service](#ip-limiter-service)
|
||
- [Common Usage Examples](#common-usage-examples)
|
||
- [Setting Up a New Server](#setting-up-a-new-server)
|
||
- [User Management Workflow](#user-management-workflow)
|
||
- [Advanced Server Configuration](#advanced-server-configuration)
|
||
- [Error Handling](#error-handling)
|
||
- [Tips & Best Practices](#tips--best-practices)
|
||
- [Troubleshooting](#troubleshooting)
|
||
|
||
## Command Categories
|
||
|
||
### 🚀 Hysteria2 Server Management
|
||
|
||
#### Install Hysteria2
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# Enable masquerade with domain
|
||
python3 cli.py masquerade --enable google.com
|
||
|
||
# Disable masquerade
|
||
python3 cli.py masquerade --remove
|
||
```
|
||
|
||
#### Geo Files Update
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# Install TCP Brutal optimization
|
||
python3 cli.py install-tcp-brutal
|
||
```
|
||
|
||
#### WARP Integration
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
```bash
|
||
# 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
|
||
|
||
1. **Regular Monitoring**: Use `traffic-status` regularly to monitor user usage
|
||
2. **Backup Strategy**: Create backups before major changes using `backup-hysteria`
|
||
3. **Security**: Use strong passwords for web panel and rotate them regularly
|
||
4. **Performance**: Enable TCP Brutal for better performance on high-latency connections
|
||
5. **Obfuscation**: Enable obfuscation in restrictive network environments
|
||
6. **User Management**: Use descriptive usernames and set appropriate traffic limits
|
||
7. **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
|