VPN Field Guides [A]

Hysteria 2 field guide: a QUIC proxy, a verified server, and a careful TUN choice

Hysteria 2 is a newer proxy built on QUIC and TLS. It can offer a local SOCKS5 or HTTP proxy; its own desktop client also documents a TUN mode. Those are different deployment modes. Start with one application through a local SOCKS5 listener so that you can verify the server and credentials before asking a client to alter system routes.

For the ordinary public-server path, the official server guide starts with a reachable server and a domain pointing at it. Download the current binary or use the project's official installation instructions; do not hard-code a release number from an old blog post. Use a real TLS certificate for that domain. Hysteria can obtain one through ACME, or read a certificate and key you provision separately. The basic server YAML has listen: :443, an acme block with your domain and contact address (or a tls block with cert and key paths), and auth.type: password with a strong unique password. Open the chosen UDP port on both provider and host firewalls. ACME's validation requirements depend on the challenge and configuration; check them before opening or closing TCP ports. Keep the server key and password private.

The official example also includes an optional masquerade response for unauthenticated HTTP/3 requests. It can make a probe receive ordinary-looking content, but it is not proof that every observer sees an indistinguishable website or that a network cannot identify your server. If you use a reverse-proxy target, choose and test it deliberately; do not treat a third-party site's domain as something you own. With no masquerade section, the official guide says Hysteria returns a 404 for ordinary HTTP requests. Begin with a stable authenticated connection, then decide whether the additional moving part is useful to your threat model.

On a desktop, create a client YAML with server: your.domain.example:443, auth: your unique password, and socks5.listen: 127.0.0.1:1080. Keep TLS verification enabled. Run hysteria client -c /path/to/client.yaml and point one application at the local SOCKS5 listener. Compare that application's public address with a direct connection, then repeat with the server stopped. Use a remote-hostname SOCKS request when you test DNS. A successful connection proves the selected application path, not full-device routing.

For desktop-wide routing, Hysteria's TUN documentation covers Windows, Linux and macOS. It creates routes and requires platform-specific privileges and an exclusion for the server endpoint to avoid routing its own connection back into the tunnel. It handles TCP and UDP, not arbitrary IP protocols such as ICMP. Follow the current official TUN field names for your exact release rather than copying an old YAML snippet: the documentation has changed over time. On Android or GrapheneOS, the official CLI TUN mode is not the phone solution; use a maintained compatible Android client that explicitly supports Hysteria 2 and Android VpnService, then test its profile, DNS and per-app rules. The equivalent iOS client is likewise a separate implementation, so check its supported version and route behavior before importing credentials.

Neither local SOCKS nor TUN is automatically fail closed in every app and OS configuration. Stop the server and try both an app intended to use the proxy and an unrelated app. Then test Wi-Fi to cellular, IPv6 reachability and DNS resolution. If traffic leaves directly where you expected a block, configure the platform's actual blocking policy and retest. A QUIC tunnel can fail entirely on a network that blocks UDP; changing its port does not make TCP transport appear. The server operator remains a trust point for destinations and metadata after the encrypted hop, and HTTPS to a destination remains valuable.

If the client cannot connect, check UDP reachability, the exact domain/SNI, certificate validity and password before touching congestion-control settings. If only large transfers struggle, measure the path and then consult Hysteria's current bandwidth/MTU guidance; do not set an invented speed value and call it a fix. Record a working baseline and revisit it after each upgrade.

Sources, checked 3 October 2026:
Hysteria 2 server guide — https://v2.hysteria.network/docs/getting-started/Server/
Hysteria 2 client guide — https://v2.hysteria.network/docs/getting-started/Client/
Hysteria 2 full client configuration, including TUN — https://v2.hysteria.network/docs/advanced/Full-Client-Config/
Hysteria 2 installation — https://v2.hysteria.network/docs/getting-started/Installation/
Project repository — https://github.com/HyNetworks/hysteria

↑ 10

Debate

Comentarios

2

Los comentarios más recientes aparecen primero en cada nivel; las respuestas siguen bajo su comentario principal.

Escribir Únete para participar en la discusión.

Verified server first, then TUN, seems like the right order. I once ran the client against the wrong port and blamed QUIC for a full day before reading the logs.
↑ 2 Responder
Respuestas · 1
@yukis, Wrong port has caught me too, though my usual one is a UDP firewall silently dropping packets while the host firewall looked open. Now I check with a tcpdump on the server before blaming the client.
↑ 0 Responder