Hysteria2

Protocol scope and minimum configuration

type: hysteria2 corresponds to the redesigned Hysteria 2 protocol. It runs over QUIC and UDP and disguises traffic as HTTP/3, but it cannot connect to a Hysteria 1.x server.

A node requires a name, type, server, and one valid port source. You may provide a single portor provide ports to enable port hopping. If neither is present, the client rejects the node with invalid port.

nameRequired

The node name, used by policy groups and rules.

type: hysteria2Required

Selects the Hysteria2 implementation, not a Hysteria 1.x compatibility mode.

serverRequired

The server domain name or IP address.

port / portsChoose one of two

Enter one port, or provide a port list and ranges to enable hopping.

passwordAuthentication

Enter the server authentication password. The current constructor permits an empty string, but omit it only when the server explicitly allows empty authentication.

Authentication and TLS validation

Hysteria2 uses TLS 1.3. The authentication password and TLS certificate validation are separate paths; a correct password does not replace a trusted certificate and the correct server name.

passwordAuthentication

The password the server uses to authenticate the client. For a userpass server, enter the complete format supplied by the server.

sniTLS

Sets the server name that matches the certificate; when omitted, uses server.

alpnTLS

The official example uses h3. Override the default negotiation result only when the server explicitly requires it.

skip-cert-verifyRisk

Skips certificate validation. Use only for testing or self-signed deployments when you clearly understand the risk.

name-cert-verifyTLS

Specifies a separate certificate-name validation target.

fingerprintTLS

Pins the SHA-256 fingerprint of the server certificate.

certificate / private-keymTLS

Provide both when the server requires a client certificate.

Port hopping

After entering ports , the client connects using the port set and ignores the single port. The port set follows the current core's port-range syntax: use hyphens for ranges and commas or slashes to separate multiple values.

portsOptional

For example, 443,20000-21000. The server and firewall must open exactly the same set of UDP ports.

hop-intervalDefault: 30 seconds

Use a fixed number of seconds, or enter 15-30 to choose a random interval for each switch.

Minimum interval5 seconds

The current implementation raises a starting value below 5 seconds to 5 seconds.

Range restrictionImportant

hop-interval accepts only one range; it cannot contain multiple comma-separated ranges. It has no effect when ports is not configured.

Salamander and Gecko obfuscation

Obfuscation changes the recognizable characteristics of QUIC packets. It does not turn Hysteria2 into TCP and cannot bypass a network-wide block on UDP. The client and server must use the same type and password.

obfsOptional

Currently supports salamander and gecko; leave it empty to disable obfuscation.

obfs-passwordConditionally required

Whenever obfs is set, an obfuscation password must also be provided, or the client reports missing obfs password.

obfs-min-packet-sizeGecko only

Sets the minimum on-wire packet size for handshake fragmentation. The official upstream default is 512 bytes.

obfs-max-packet-sizeGecko only

Sets the maximum on-wire packet size for handshake fragmentation. The official upstream default is 1200 bytes.

Gecko rangeConstraint

The maximum must be at least the minimum and no more than 2048 bytes. Salamander does not read these two packet-size fields.

Bandwidth, congestion control, and QUIC windows

Hysteria2's up and down fields differ from Hysteria 1.x: they determine by direction whether Brutal is used. Providing up enables Brutal for client uploads, while providing down passes the target download rate to the server-side direction.

The client's bbr-profile controls only the local QUIC send direction when upload Brutal is disabled; it does not select congestion control for the server's download direction. Receive windows are advanced quic-go parameters and should not be changed without understanding the bandwidth-delay product and memory cost.

up / downOptional

Enter the Brutal rate. Without a unit, it is interpreted as Mbps; do not exceed the link's stable achievable rate.

bbr-profileDefault: standard

Options are standard, conservative, and aggressive. This affects only the client's upload send direction when up Brutal is not used.

initial-stream-receive-windowAdvanced

Initial receive window for a single QUIC stream.

max-stream-receive-windowAdvanced

Maximum receive window for a single QUIC stream.

initial-connection-receive-windowAdvanced

Initial receive window for the entire QUIC connection.

max-connection-receive-windowAdvanced

Maximum receive window for the entire QUIC connection.

Hysteria2 Realm

realm-opts Used for UDP hole punching and rendezvous when connecting to Hysteria2 Realm. It is disabled by default and should be enabled only when the server or Realm provider explicitly supplies the parameters.

realm-opts.enableDefault: false

Must be explicitly set to true to enable Realm.

realm-opts.server-urlRealm

The HTTPS address of the rendezvous service.

realm-opts.token / realm-opts.realm-idRealm

Enter the rendezvous-service token and target Realm identifier, respectively.

realm-opts.stun-serversRealm

A list of STUN servers used to discover the public UDP address.

realm-opts.sni / skip-cert-verify / fingerprintScope

These subfields apply only to realm-opts.server-urland do not replace the proxy server's TLS fields.

Base example and common misconfigurations

First verify authentication and TLS using a single port with no obfuscation. Then add port hopping or obfuscation to match the actual server configuration.

• Copying Hysteria 1.x's auth-str or protocolfields, which do not belong to Hysteria2.
• Setting obfs without obfs-passwordcauses an immediate error while the node is being created.
• Enabling ports when the server or firewall has not opened the same port range causes periodic disconnects.
• Writing up and down Setting it far above the link's real bandwidth causes congestion and packet loss.

proxies:
  - name: hysteria2-node
    type: hysteria2
    server: server.example.com
    port: 443
    password: replace-with-server-password
    sni: server.example.com
    alpn:
      - h3
    skip-cert-verify: false