Hysteria 2

https://v2.hysteria.network/docs
Admin
Hysteria 2 is a high-performance proxy software that provides both server and client components for...
Tokens:48,455
Snippets:411
Trust Score:7.9
Update:5 days ago
Show doc for...
Tokens:
Raw
### Enable and Start Service

Source: https://v2.hysteria.network/docs/getting-started/Server-Installation-Script

Enables the Hysteria server service to start at boot and starts it immediately.

```bash
systemctl enable --now hysteria-server.service
```

--------------------------------

### Speed test examples

Source: https://v2.hysteria.network/docs/advanced/Speed-Test

Examples of running the speed test in default time-based mode, with a custom duration, and in size-based mode.

```bash
# Default: time-based, 10s each direction
./hysteria speedtest

```

```bash
# Time-based with custom duration
./hysteria speedtest --duration 30s

```

```bash
# Size-based: transfer 200 MB each direction
./hysteria speedtest --data-size 209715200

```

--------------------------------

### Install from Local File

Source: https://v2.hysteria.network/docs/getting-started/Server-Installation-Script

Installs Hysteria from a local executable file when the VPS cannot connect to GitHub Release. Replace /path/to/hysteria-linux-amd64 with the actual path.

```bash
bash <(curl -fsSL https://get.hy2.sh/) --local /path/to/hysteria-linux-amd64
```

--------------------------------

### Start server with default config filename

Source: https://v2.hysteria.network/docs/getting-started/Server

Starts the Hysteria server using the default config.yaml file in the current directory. Look for the log message 'server up and running' to confirm success.

```bash
./hysteria-linux-amd64-avx server

```

--------------------------------

### Start server with custom config filename

Source: https://v2.hysteria.network/docs/getting-started/Server

Starts the Hysteria server using a custom configuration file specified with the -c flag. Replace 'whatever.yaml' with your actual config file name.

```bash
./hysteria-linux-amd64-avx server -c whatever.yaml

```

--------------------------------

### Run client with custom config filename

Source: https://v2.hysteria.network/docs/getting-started/Client

Starts the client with a custom configuration file using the -c flag.

```bash
./hysteria-linux-amd64-avx -c whatever.yaml

```

--------------------------------

### Format and tidy code before committing

Source: https://v2.hysteria.network/docs/developers/Build

Run these commands before committing to format and tidy the codebase. Requires gofumpt to be installed.

```bash
python hyperbole.py format
python hyperbole.py tidy

```

--------------------------------

### Run client with default config filename

Source: https://v2.hysteria.network/docs/getting-started/Client

Starts the client using the default config.yaml file in the current directory. The 'client' subcommand is optional as it is the default mode.

```bash
./hysteria-linux-amd64-avx

```

--------------------------------

### Generate mocks with mockery

Source: https://v2.hysteria.network/docs/developers/Build

Run this command before committing if you changed any interface that has a mock. Requires mockery to be installed.

```bash
python hyperbole.py mockgen

```

--------------------------------

### ACL rules example

Source: https://v2.hysteria.network/docs/advanced/ACL

Example ACL rules demonstrating various address types, protocol/port matching, and hijacking. Uses the outbounds defined above.

```plaintext
# Use the v6_only outbound for Google
v6_only(suffix:google.com)

# Use the v4_only outbound for Twitter
v4_only(suffix:twitter.com)

# Use the some_proxy outbound for ipinfo.io
some_proxy(ipinfo.io)

# Non-English IDN domains are also supported
v6_only(战狼*.中国)

# Block QUIC protocol
reject(all, udp/443)

# Block SMTP protocol
reject(all, tcp/25)

# Block China and North Korea
reject(geoip:cn)
reject(geoip:kp)

# Block Facebook and Google Ads
reject(geosite:facebook)
reject(geosite:google@ads)

# Block some random ranges
reject(73.0.0.0/8)
reject(2601::/20)

# Hijack 8.8.8.8 to 1.1.1.1 and use default (first) outbound
default(8.8.8.8, *, 1.1.1.1)

# Hijack 8.8.4.4 to 1.1.1.1 and use default (first) outbound, but UDP 53 only
default(8.8.4.4, udp/53, 1.1.1.1)

# Direct all other connections
direct(all)

```

--------------------------------

### Minimal mimic configuration

Source: https://v2.hysteria.network/docs/advanced/Mimic

Enables mimic with just `enabled: true`. This is the recommended setup for most cases and must be set on both server and client.

```yaml
mimic:
  enabled: true

```

--------------------------------

### Install or Upgrade to a Specified Version

Source: https://v2.hysteria.network/docs/getting-started/Server-Installation-Script

Installs or upgrades Hysteria to a specific version using the --version flag. Replace v2.13.0 with the desired version.

```bash
bash <(curl -fsSL https://get.hy2.sh/) --version v2.13.0
```

--------------------------------

### Enable Fast Open

Source: https://v2.hysteria.network/docs/advanced/Full-Client-Config

Set fastOpen to true to reduce connection setup by one RTT, but this sacrifices correct SOCKS5/HTTP proxy semantics. The client accepts connections without confirming destination reachability, and may close connections without sending data if the server fails.

```yaml
fastOpen: true

```

--------------------------------

### Define outbounds with direct, SOCKS5, and HTTP types

Source: https://v2.hysteria.network/docs/advanced/Full-Server-Config

Shows the YAML configuration for defining multiple outbounds. The first outbound is the default when ACL is not used. HTTP outbounds do not support UDP and will reject UDP traffic. The SOCKS5 example includes address, username, and password; the HTTP example includes URL and insecure flag.

```yaml
outbounds:
  - name: my_outbound_1 
    type: direct 
  - name: my_outbound_2
    type: socks5
    socks5:
      addr: shady.proxy.ru:1080 
      username: hackerman 
      password: Elliot Alderson 
  - name: my_outbound_3
    type: http
    http:
      url: http://username:password@sketchy-proxy.cc:8081 
      insecure: false 

```

--------------------------------

### Specify Architecture (AVX)

Source: https://v2.hysteria.network/docs/getting-started/Server-Installation-Script

Installs the AVX version of Hysteria by setting the ARCHITECTURE environment variable to amd64-avx.

```bash
ARCHITECTURE=amd64-avx bash <(curl -fsSL https://get.hy2.sh/)
```

--------------------------------

### Run Hysteria client as dedicated user manually

Source: https://v2.hysteria.network/docs/advanced/TPROXY

Starts the Hysteria client as the 'hysteria' user when running it manually.

```bash
sudo -u hysteria /path/to/hysteria -c config.yaml

```

--------------------------------

### Docker Compose example

Source: https://v2.hysteria.network/docs/getting-started/Installation

Docker Compose configuration for running Hysteria server with host networking, ACME volume for certificates, and a mounted configuration file. The NET_ADMIN capability is only required when port hopping is enabled.

```yaml
version: "3.9"
services:
  hysteria:
    image: tobyxdd/hysteria
    container_name: hysteria
    restart: always
    network_mode: "host"
    cap_add:
      - NET_ADMIN
    volumes:
      - acme:/acme
      - ./hysteria.yaml:/etc/hysteria.yaml
    command: ["server", "-c", "/etc/hysteria.yaml"]
volumes:
  acme:
```

--------------------------------

### TOML configuration example (config.toml)

Source: https://v2.hysteria.network/docs/misc/Hate-YAML

A TOML configuration file for Hysteria. It sets the server address, authentication string, bandwidth limits, fastOpen and lazy options, and SOCKS5 and HTTP proxy listeners. Use this format when you prefer TOML over YAML.

```toml
server = "your.server.net"
auth = "i_still_love_tom"
fastOpen = true
lazy = true

[bandwidth]
up = "30 mbps"
down = "100 mbps"

[socks5]
listen = "127.0.0.1:1080"

[http]
listen = "127.0.0.1:8080"

```

--------------------------------

### Run Hysteria client with JSON or TOML config

Source: https://v2.hysteria.network/docs/misc/Hate-YAML

Commands to run the Hysteria client using either a JSON or TOML configuration file. The file extension must match the format used. The example uses the binary `hysteria-linux-amd64-avx`.

```bash
./hysteria-linux-amd64-avx -c config.json
# or
./hysteria-linux-amd64-avx -c config.toml

```

--------------------------------

### JSON configuration example (config.json)

Source: https://v2.hysteria.network/docs/misc/Hate-YAML

A JSON configuration file for Hysteria. It sets the server address, authentication string, bandwidth limits, fastOpen and lazy options, and SOCKS5 and HTTP proxy listeners. Use this format when you prefer JSON over YAML.

```json
{
  "server": "your.server.net",
  "auth": "i_still_love_jason",
  "bandwidth": {
    "up": "30 mbps",
    "down": "100 mbps"
  },
  "fastOpen": true,
  "lazy": true,
  "socks5": {
    "listen": "127.0.0.1:1080"
  },
  "http": {
    "listen": "127.0.0.1:8080"
  }
}

```

--------------------------------

### Deployment script for Linux servers

Source: https://v2.hysteria.network/docs/getting-started/Installation

Downloads and runs the official Hysteria installation script, which automatically downloads the latest version and configures a systemd service on common Linux distributions.

```bash
bash <(curl -fsSL https://get.hy2.sh/)
```

--------------------------------

### Set process priority with chrt

Source: https://v2.hysteria.network/docs/advanced/Performance

Use chrt to set real-time priority for the hysteria process. On FreeBSD, install util-linux and the highest priority is 31 instead of 99. Start with moderate priority and test before raising.

```bash
# Execute after each service start
chrt -r 20 $(pidof hysteria)

# Or, use the following command to start the service
chrt -r 20 hysteria server -c /path/to/config.yaml
```

--------------------------------

### Server startup log with ECH config list

Source: https://v2.hysteria.network/docs/advanced/ECH

On startup, the server logs the config list that clients need. Copy this base64 string and give it to clients.

```log
INFO ECH enabled, set the following config list on clients (tls.ech) {"configList": "AEz+DQBIAAAg..."}

```

--------------------------------

### Example outbounds list for ACL

Source: https://v2.hysteria.network/docs/advanced/ACL

Assumed outbounds list used in the examples. Defines three outbounds: v4_only, v6_only, and some_proxy.

```yaml
outbounds:
  - name: v4_only
    type: direct
    direct:
      mode: 4
  - name: v6_only
    type: direct
    direct:
      mode: 6
  - name: some_proxy
    type: socks5
    socks5:
      addr: ohno.moe:1080

```

--------------------------------

### Basic client configuration (config.yaml)

Source: https://v2.hysteria.network/docs/getting-started/Client

Creates a config.yaml file with server address, authentication secret, bandwidth limits, and SOCKS5/HTTP proxy listeners. Replace values with your server's settings. Enclose values in quotes if they conflict with YAML syntax, such as IPv6 addresses.

```yaml
server: your.domain.net:443 

auth: Se7RAuFZ8Lzg 

bandwidth: 
  up: 20 mbps
  down: 100 mbps

socks5:
  listen: 127.0.0.1:1080 

http:
  listen: 127.0.0.1:8080 

```

--------------------------------

### ACL blocking example without custom outbounds

Source: https://v2.hysteria.network/docs/advanced/ACL

Example ACL rules to block certain addresses using built-in outbounds, commonly used to block ads and private networks.

```plaintext
reject(geoip:cn)
reject(geosite:facebook)
reject(10.0.0.0/8)
reject(172.16.0.0/12)
reject(192.168.0.0/16)
reject(fc00::/7)

```

--------------------------------

### Policy Routing Rules for TProxy (IPv4 and IPv6)

Source: https://v2.hysteria.network/docs/advanced/TPROXY

Run these commands every time the system boots unless made persistent. They set up policy routing rules using fwmark 0x1 and table ID 100. Adjust the fwmark and table ID as needed.

```bash
# IPv4
ip rule add fwmark 0x1 lookup 100
ip route add local default dev lo table 100

# IPv6
ip -6 rule add fwmark 0x1 lookup 100
ip -6 route add local default dev lo table 100

```

--------------------------------

### GET /dump/streams

Source: https://v2.hysteria.network/docs/advanced/Traffic-Stats-API

Returns a JSON object containing information about each QUIC stream of a Hysteria TCP proxy connection. Optionally, an 'Accept: text/plain' header can be used to get a human-readable table output.

```APIDOC
## GET /dump/streams

### Description
Returns a JSON object containing information about each QUIC stream of a Hysteria TCP proxy connection. Optionally, an 'Accept: text/plain' header can be used to get a human-readable table output.

### Method
GET

### Endpoint
/dump/streams

### Headers
- **Accept** (string) - Optional - Set to 'text/plain' to receive a human-readable table output.

### Response
#### Success Response (200)
- **streams** (array) - List of stream objects.
  - **state** (string) - Stream state (e.g., "estab").
  - **auth** (string) - Authentication identifier.
  - **connection** (integer) - Connection identifier.
  - **stream** (integer) - Stream identifier.
  - **req_addr** (string) - Request address.
  - **hooked_req_addr** (string) - Hooked request address.
  - **tx** (integer) - Transmitted bytes.
  - **rx** (integer) - Received bytes.
  - **initial_at** (string) - Initial timestamp.
  - **last_active_at** (string) - Last active timestamp.

#### Response Example (JSON)
```
{
  "streams": [
    {
      "state": "estab", 
      "auth": "user", 
      "connection": 3191736581, 
      "stream": 4, 
      "req_addr": "192.0.2.1:80", 
      "hooked_req_addr": "example.com:80", 
      "tx": 3937, 
      "rx": 4441, 
      "initial_at": "2024-11-08T16:07:45.956956773+09:00", 
      "last_active_at": "2024-11-08T16:07:47.121503203+09:00" 
    }
  ]
}
```

#### Response Example (Text/plain)
```
State    Auth           Connection   Stream     TX-Bytes     RX-Bytes     Lifetime  Last-Active Req-Addr         Hooked-Req-Addr
ESTAB    user             BE3E0905        4         3937         4441       3.005s        1.84s 192.0.2.1:80     example.com:80
```
```

--------------------------------

### GET /traffic with clear parameter

Source: https://v2.hysteria.network/docs/advanced/Traffic-Stats-API

Query parameter to zero out traffic statistics after they are returned.

```http
/traffic?clear=1
```

--------------------------------

### Set process priority with systemd

Source: https://v2.hysteria.network/docs/advanced/Performance

Create a systemd drop-in file to set Nice=-5 for the hysteria-server service. Then reload systemd and restart the service.

```ini
[Service]
Nice=-5
```

```bash
systemctl daemon-reload
systemctl restart hysteria-server.service
```

--------------------------------

### QUIC parameters configuration

Source: https://v2.hysteria.network/docs/advanced/Full-Server-Config

Configures QUIC protocol parameters. Default stream and connection receive windows are 8MB and 20MB respectively; changing them is not recommended. If changed, keep the stream-to-connection window ratio at 2:5.

```yaml
quic:
  initStreamReceiveWindow: 8388608 
  maxStreamReceiveWindow: 8388608 
  initConnReceiveWindow: 20971520 
  maxConnReceiveWindow: 20971520 
  maxIdleTimeout: 30s 
  maxIncomingStreams: 1024 
  disablePathMTUDiscovery: false 
  disableStatelessReset: false 

```

--------------------------------

### Customize direct outbound with bind options and mode

Source: https://v2.hysteria.network/docs/advanced/Full-Server-Config

Shows YAML configuration for a direct outbound with additional options: mode, bindIPv4, bindIPv6, bindDevice, and fastOpen. The bind options are mutually exclusive: either specify bindIPv4 and/or bindIPv6 without bindDevice, or use bindDevice without the bind addresses. The mode values control IPv4/IPv6 preference.

```yaml
outbounds:
  - name: hoho
    type: direct
    direct:
      mode: auto 
      bindIPv4: 2.4.6.8 
      bindIPv6: 0:0:0:0:0:ffff:0204:0608 
      bindDevice: eth233 
      fastOpen: false 

```

--------------------------------

### Build Hysteria with Hyperbole

Source: https://v2.hysteria.network/docs/developers/Build

Run from the repository root to build Hysteria. Use -r for a release build and -p for a portable build.

```bash
python hyperbole.py build 
# or
python hyperbole.py build -r 
# or
python hyperbole.py build -p 

```

--------------------------------

### QUIC parameters configuration

Source: https://v2.hysteria.network/docs/advanced/Full-Client-Config

YAML configuration for QUIC parameters. Default stream and connection receive windows are 8MB and 20MB; changing them is not recommended. The sockopts options apply only to outbound QUIC connections. Chrome parroting overrides some settings and requires ECDSA or RSA certificates.

```yaml
quic:
  initStreamReceiveWindow: 8388608 
  maxStreamReceiveWindow: 8388608 
  initConnReceiveWindow: 20971520 
  maxConnReceiveWindow: 20971520 
  maxIdleTimeout: 30s 
  keepAlivePeriod: 10s 
  disablePathMTUDiscovery: false 
  disableChromeParrot: false 
  sockopts:
    bindInterface: eth0 
    fwmark: 1234 
    fdControlUnixSocket: ./test.sock 

```

--------------------------------

### GET /dump/streams text/plain response

Source: https://v2.hysteria.network/docs/advanced/Traffic-Stats-API

Human-readable output similar to ss -atn when Accept: text/plain header is used.

```text
State    Auth           Connection   Stream     TX-Bytes     RX-Bytes     Lifetime  Last-Active Req-Addr         Hooked-Req-Addr
ESTAB    user             BE3E0905        4         3937         4441       3.005s        1.84s 192.0.2.1:80     example.com:80
```

--------------------------------

### GET /dump/streams response

Source: https://v2.hysteria.network/docs/advanced/Traffic-Stats-API

JSON object containing information about each QUIC stream of a Hysteria TCP proxy connection.

```json
{
  "streams": [
    {
      "state": "estab", 
      "auth": "user", 
      "connection": 3191736581, 
      "stream": 4, 
      "req_addr": "192.0.2.1:80", 
      "hooked_req_addr": "example.com:80", 
      "tx": 3937, 
      "rx": 4441, 
      "initial_at": "2024-11-08T16:07:45.956956773+09:00", 
      "last_active_at": "2024-11-08T16:07:47.121503203+09:00" 
    }
  ]
}
```

--------------------------------

### GET /online response

Source: https://v2.hysteria.network/docs/advanced/Traffic-Stats-API

JSON map of online clients to their connection counts (number of Hysteria client instances).

```json
{
  "wang": 2,
  "joe": 1
}
```

--------------------------------

### ip6tables Rules for TProxy (IPv6)

Source: https://v2.hysteria.network/docs/advanced/TPROXY

Run these commands every time the system boots unless made persistent. They create a HYSTERIA chain to skip already-handled traffic, only proxy public IPv6 addresses, redirect traffic to TProxy port 2500, and proxy local traffic. The fwmark is 0x1.

```bash
ip6tables -t mangle -N HYSTERIA

# Skip traffic already handled by TProxy 
ip6tables -t mangle -A HYSTERIA -p tcp -m socket --transparent -j MARK --set-mark 0x1
ip6tables -t mangle -A HYSTERIA -p udp -m socket --transparent -j MARK --set-mark 0x1
ip6tables -t mangle -A HYSTERIA -m socket -j RETURN

# Only proxy public IPv6 addresses 
ip6tables -t mangle -A HYSTERIA ! -d 2000::/3 -j RETURN

# Redirect traffic to the TProxy port
ip6tables -t mangle -A HYSTERIA -p tcp -j TPROXY --on-port 2500 --on-ip ::1 --tproxy-mark 0x1
ip6tables -t mangle -A HYSTERIA -p udp -j TPROXY --on-port 2500 --on-ip ::1 --tproxy-mark 0x1 

# Enable the above rules
ip6tables -t mangle -A PREROUTING -j HYSTERIA

# === Proxy Local Traffic - Start === 

ip6tables -t mangle -N HYSTERIA_MARK

# Match user to prevent loops
ip6tables -t mangle -A HYSTERIA_MARK -m owner --uid-owner hysteria -j RETURN

# Only proxy public IPv6 addresses
ip6tables -t mangle -A HYSTERIA_MARK ! -d 2000::/3 -j RETURN

# Mark traffic to re-route it to PREROUTING
ip6tables -t mangle -A HYSTERIA_MARK -p tcp -j MARK --set-mark 0x1
ip6tables -t mangle -A HYSTERIA_MARK -p udp -j MARK --set-mark 0x1

# Enable the above rules
ip6tables -t mangle -A OUTPUT -j HYSTERIA_MARK

# === Proxy Local Traffic - End ===

```

--------------------------------

### Run speed test with default config

Source: https://v2.hysteria.network/docs/advanced/Speed-Test

Runs the speed test using the default configuration file (config.yaml). The server must have speed test support enabled.

```bash
./hysteria-linux-amd64-avx speedtest

```

--------------------------------

### curl request with Authorization header

Source: https://v2.hysteria.network/docs/advanced/Traffic-Stats-API

Example of making a request to the Traffic Stats API with an Authorization header when an API secret is set.

```bash
curl -H 'Authorization: secret' http://ip:port/path
```

--------------------------------

### Server realm listen configuration

Source: https://v2.hysteria.network/docs/advanced/Realms

Set 'listen' to a realm URI to run the server in realm mode. The server dials the rendezvous over outbound TCP, registers the realm, and waits for connections. No inbound port is needed. Enable 'obfs' if DPI-based censorship is a concern.

```yaml
listen: realm://public@realm.hy2.io/your-realm-name

```

--------------------------------

### Set HY_APP_PLATFORMS for cross-platform builds

Source: https://v2.hysteria.network/docs/developers/Build

Set the HY_APP_PLATFORMS environment variable to build for other platforms. The example targets linux/amd64, windows/amd64, and darwin/amd64.

```bash
export HY_APP_PLATFORMS="linux/amd64,windows/amd64,darwin/amd64"

```

--------------------------------

### GET /traffic response

Source: https://v2.hysteria.network/docs/advanced/Traffic-Stats-API

JSON response from the /traffic endpoint, mapping client IDs to their traffic statistics (tx and rx bytes).

```json
{
  "wang": {
    "tx": 514,
    "rx": 4017
  },
  "joe": {
    "tx": 7790,
    "rx": 446623
  }
}
```

--------------------------------

### Server address as host:port

Source: https://v2.hysteria.network/docs/advanced/Full-Client-Config

Sets the server address. If the port is omitted, it defaults to 443.

```yaml
server: example.com

```

--------------------------------

### Run speed test with custom config file

Source: https://v2.hysteria.network/docs/advanced/Speed-Test

Runs the speed test using a custom configuration file specified with the -c flag.

```bash
./hysteria-linux-amd64-avx speedtest -c whatever.yaml

```
Tokens:
Raw