Working directory of the OpenGFW service and home of hysteria-client.user.
(optionally newline-terminated) single-line string
"/var/lib/hysteria-client"Whether to enable Hysteria (client, a powerful, lightning fast and censorship resistant proxy. .
boolean
falsetrueFormat of the logs.
one of "json", "console"
"json""console"Level of the logs.
one of "debug", "info", "warn", "error"
"info""warn"The hysteria package to use.
package
pkgs.hysteriaHysteria client settings
null or (submodule)
nullIf the server uses the userpass authentication, the format must be username:password.
null or string
null"some_password"Hysteria has two built-in congestion control algorithms (BBR & Brutal). Which one to use depends on whether bandwidth information is provided. If you want to use BBR instead of Brutal, you can delete the entire bandwidth section. For more details, see Bandwidth negotiation process and Congestion control details.
⚠️ Warning Higher bandwidth values are not always better; be very careful not to exceed the maximum bandwidth that your current network can support.
Doing so will backfire, causing network congestion and unstable connections.
The client's actual upload speed will be the lesser of the value specified here and the server's maximum download speed (if set by the server).
Similarly, the client's actual download speed will be the lesser of the value specified here and the server's maximum upload speed (if set by the server).
One exception is that if the server has enabled the ignoreClientBandwidth option, the values specified here will be ignored.
Supported units are:
- bps or b (bits per second)
- kbps or kb or k (kilobits per second)
- mbps or mb or m (megabits per second)
- gbps or gb or g (gigabits per second)
- tbps or tb or t (terabits per second)
null or (submodule)
nullThe client's download bandwidth.
string
"200 mbps""500 mbps"The client's upload bandwidth.
string
"100 mbps""50 mbps"Fast Open can shave one roundtrip time (RTT) off each connection, but at the cost of the correct semantics of SOCKS5/HTTP proxy protocols. When this is enabled, the client always immediately accepts a connection without confirming with the server that the destination is reachable. If the server then fails or rejects the connection, the client will simply close the connection without sending any data back to the proxy client.
boolean
falsetrueAn HTTP proxy server that can be used with any HTTP proxy-compatible application. Supports both plaintext HTTP and HTTPS (CONNECT).
null or (submodule)
nullThe address to listen on.
null or string
null"127.0.0.1:8080"Optional. The password to require for authentication.
null or string
null"kong"Optional. The realm to require for authentication.
null or string
null"martian"Optional. The username to require for authentication.
null or string
null"king"When enabled, the client is "lazy" in the sense that it will only attempt to connect to the server if there is an incoming connection from one of the enabled client modes.
This differs from the default behavior, where the client attempts to connect to the server as soon as it starts up.
The lazy option can be useful if you're unsure when you'll use the client and want to avoid idle connections.
It's also useful if your Internet connection might not be ready when you start the Hysteria client.
boolean
falsetrueBy default, the Hysteria protocol mimics HTTP/3. If your network specifically blocks QUIC or HTTP/3 traffic (but not UDP in general), obfuscation can be used to work around this. We currently have an obfuscation implementation called "Salamander" that converts packets into seamingly random bytes with no pattern. This feature requires a password that must be identical on both the client and server sides.
null or (submodule)
nullReplace with a strong password of your choice.
null or string
null"cry_me_a_r1ver"Obfuscation type
value "salamander" (singular enum)
"salamander"Forces QUIC packets to be sent through this interface.
null or string
null"eth0"Path to a Unix Socket that is listened to by other processes. The Hysteria client will send the file descriptor (FD) used for the QUIC connection as ancillary information to this Unix Socket, allowing the listening process to perform other custom configurations. This option can be used in Android client development; please refer to the FD Control Protocol for more details.
null or string
null"./test.sock"The SO_MARK tag to be added to QUIC packets.
null or signed integer
null1234The server field specifies the address of the Hysteria server that the client should connect to.
The address can be formatted as either host:port or just host. If the port is omitted, it defaults to 443.
You also have the option to use a Hysteria 2 URI (hysteria2://).
In this case, because the URI already includes the password and certain other settings, you don't (and can't) specify them separately in the configuration file.
null or string
null"example.com"A SOCKS5 proxy server that can be used with any SOCKS5-compatible application. Supports both TCP and UDP.
null or (submodule)
nullOptional. Disable UDP support.
boolean
falsetrueThe address to listen on.
null or string
null"127.0.0.1:1080"Optional. The password to require for authentication.
null or string
null"pass"Optional. The username to require for authentication.
null or string
null"user"TCP Forwarding allows you to forward one or more TCP ports from the server (or any remote host) to the client. This is useful, for example, if you want to access a service that is only available on the server's network.
null or (list of (submodule))
nullThe address to listen on.
null or string
null"127.0.0.1:6600"The address to forward to.
null or string
null"other.machine.internal:6601"REDIRECT is essentially a special case of DNAT where the destination address is localhost. This method predates TPROXY as an older way to implement a TCP transparent proxy. We recommend using TPROXY instead if your kernel supports it. Example
null or (submodule)
nullThe address to listen on.
null or string
null":2500"TPROXY (transparent proxy) is a Linux-specific feature that allows you to transparently proxy TCP connections. For information, please refer to Setting up TPROXY.
null or (submodule)
nullThe address to listen on.
null or string
null":2500"TLS client settings
null or (submodule)
nullUse a custom CA certificate for TLS verification.
null or path
null"custom_ca.crt"Disable TLS verification.
boolean
falsetrueVerify the server's certificate fingerprint.
You can obtain the fingerprint of your certificate using openssl:
openssl x509 -noout -fingerprint -sha256 -in your_cert.crt
null or string
null"BA:88:45:17:A1..."Server name to use for TLS verification.
If omitted, the server name will be extracted from the server field.
null or string
null"another.example.com"The transport section is for customizing the underlying protocol used by the QUIC connection.
Currently the only type available is udp, but we reserve it for possible future expansions.
null or (submodule)
nullTransport type selection
value "udp" (singular enum)
"udp"The port hopping interval. This is only relevant if you're using a port hopping address. See Port Hopping for more information.
string
"30s""60s"TUN mode is a cross-platform transparent proxy solution that creates a virtual network interface in the system and uses the system's routes to capture and redirect traffic. It currently works on Windows, Linux, and macOS. Unlike traditional L3 VPNs (such as WireGuard and OpenVPN), Hysteria's TUN mode can only handle TCP and UDP and does not support other protocols including ICMP (e.g. ping). It also takes control of the TCP stack to speed up TCP connections. Compared to Hysteria 1's implementation, Hysteria 2's TUN is based on sing-tun's "system" stack, requiring a /30 IPv4 address and a /126 IPv6 address to be configured on the interface. Hysteria will automatically set up the network interface, addresses, and routes.
NOTE: ipv4Exclude/ipv6Exclude is important to avoid getting a routing loop. See the comments for these fields for more information.
null or (submodule)
nullOptional. Addresses to use on the interface. Set to any private address that does not conflict with your LAN. The defaults are as shown.
null or (submodule)
nullThe IPv4 address to use.
null or string
null"100.100.100.101/30"The IPv6 address to use.
null or string
null"2001::ffff:ffff:ffff:fff1/126"Optional. The maximum packet size accepted by the TUN interface.
signed integer
1500The name of the TUN interface.
null or string
null"hytun"Optional. Routing rules. Omitting or skipping all fields means that no routes will be added automatically.
In most cases, just having ipv4Exclude or ipv6Exclude is enough.
null or (submodule)
nullOptional. IPv4 prefix to proxy. If any other field is configured, the default is 0.0.0.0/0.
null or (list of string)
null[
"0.0.0.0/0"
]Optional. IPv4 prefix to exclude.
Add your Hysteria server address here to avoid a routing loop.
If you want to disable IPv4 proxying completely, you can also put 0.0.0.0/0 here.
null or (list of string)
null[
"192.0.2.1/32"
]Optional. IPv6 prefix to proxy. Due to YAML limitations, quotes are required. If any other field is configured, the default is ::/0.
null or (list of string)
null[
"2000::/3"
]Optional. IPv6 prefix to exclude.
Due to YAML limitations, quotes are required.
Add your Hysteria server address here to avoid a routing loop.
If you want to disable IPv6 proxying completely, you can also put "::/0" here.
null or (list of string)
null[
"2001:db8::1/128"
]Optional. UDP session timeout.
string
"5m""10m"UDP Forwarding allows you to forward one or more UDP ports from the server (or any remote host) to the client. This is useful, for example, if you want to access a service that is only available on the server's network.
null or (list of (submodule))
nullThe address to listen on.
null or string
null"127.0.0.1:6600"The address to forward to.
null or string
null"other.machine.internal:5301"Optional. The timeout for each UDP session. If omitted, the default timeout is 60 seconds.
string
"60s""20s"TPROXY (transparent proxy) is a Linux-specific feature that allows you to transparently proxy UDP connections. For information, please refer to Setting up TPROXY.
null or (submodule)
nullThe address to listen on.
null or string
null":2500"Optional. The timeout for each UDP session. If omitted, the default timeout is 60 seconds.
string
"60s""20s"Path to file containing Hysteria settings.
null or path
nullUsername of the Hysteria user
string
"hysteria-client"Working directory of the OpenGFW service and home of hysteria-server.user.
(optionally newline-terminated) single-line string
"/var/lib/hysteria-server"Whether to enable Hysteria (server, a powerful, lightning fast and censorship resistant proxy. .
boolean
falsetrueFormat of the logs.
one of "json", "console"
"json""console"Level of the logs.
one of "debug", "info", "warn", "error"
"info""warn"Open the firewall for the Hysteria server.
boolean
falsetrueThe hysteria package to use.
package
pkgs.hysteriaHysteria server settings
null or (submodule)
nullACL, often used in combination with outbounds, is a very powerful feature of the Hysteria server that allows you to customize the way client's requests are handled.
For example, you can use ACL to block certain addresses, or to use different outbounds for different websites.
For details on syntax, usage and other information, please refer to the ACL documentation.
You can have either file or inline, but not both.
NOTE: Hysteria currently uses the protobuf-based "dat" format for geoip/geosite data originating from v2ray.
If you don't need any customization, you can omit the
geoiporgeositefields and let Hysteria automatically download the latest version Loyalsoldier/v2ray-rules-dat to your working directory.
The files will only be downloaded and used if your ACL has at least one rule that uses this feature.
null or (submodule)
nullThe path to the ACL file.
null or path
null"./some.txt"Optional. The interval at which to refresh the GeoIP/GeoSite databases. 168 hours (1 week) by default. Only applies if the GeoIP/GeoSite databases are automatically downloaded.
Hysteria currently only downloads the GeoIP/GeoSite databases once at startup.
You will need to use external tools to periodically restart the Hysteria server in order to update the databases regularly through geoUpdateInterval.
This may change in future versions.
string
"168h""100h"Optional. The path to the GeoIP database file. If this field is omitted, Hysteria will automatically download the latest database to your working directory.
null or path
null"./geoip.dat"Optional. The path to the GeoSite database file. If this field is omitted, Hysteria will automatically download the latest database to your working directory.
null or path
null"./geosite.dat"The list of inline ACL rules. ACL documentation]
null or (list of string)
null[
"reject(suffix:v2ex.com)"
"reject(all, udp/443)"
"reject(geoip:cn)"
"reject(geosite:netflix)"
]ACME configuration.
null or (submodule)
nullThe CA to use.
one of "letsencrypt", "zerossl"
"letsencrypt""zerossl"Directory to store ACME credentials.
string
"acme"ACME DNS can obtain certificates through the DNS service provider API. T his function does not rely on specific ports (does not occupy 80/443) and external access.
null or (submodule)
nullACME DNS provider configuration. ACME DNS Config documentation
null or (attribute set of string)
null{
cloudflare_api_token = "Dxabckw9dB_jYBdi89kgyaS8wRjqqSsd679urScKOBP";
}Name of the DNS provider.
null or one of "cloudflare", "duckdns", "gandi", "godaddy", "namedotcom", "vultr"
null"cloudflare"Your domains
list of string
[ ][
"domain1.com"
"domain2.org"
]Your email address
string
null"your@email.net"Listening port for HTTP challenges.
NOTE: Changing to a port other than 80 requires port forwarding or HTTP reverse proxy, or the challenge will fail!
null or signed integer
null8888Listening address for ACME verification (no port). Defaults to listening on all available interfaces.
string
"0.0.0.0""192.168.5.150"Listening port for TLS-ALPN challenges.
NOTE: Changing to a port other than 443 requires port forwarding or TLS reverse proxy, or the challenge will fail!
null or signed integer
null44333ACME challenge type.
null or one of "http", "tls", "dns"
null"http"Authentication payload:
{
"addr": "123.123.123.123:44556",
"auth": "something_something",
"tx": 123456
}null or (submodule)
nullThe path to the command that handles authentication. When using command authentication, the server will execute the specified command with the following arguments from the authentication payload when a client attempts to connect:
/etc/some_command addr auth tx
The command must print the client's unique identifier to stdout and return with exit code 0 if the client is allowed to connect,
or return with a non-zero exit code if the client is rejected.
If the command fails to execute, the client will be rejected.
null or string
null"/etc/some_command"When using HTTP authentication, the server will send a POST request to the backend server with the authentication payload when a client attempts to connect.
Your endpoint must respond with a JSON object with the following fields:
{
"ok": true,
"id": "john_doe"
}NOTE: The HTTP status code must be 200 for the authentication to be considered successful.
null or (submodule)
nullDisable TLS verification for the backend server (only applies to HTTPS URLs).
boolean
falsetrueThe URL of the backend server that handles authentication.
null or string
null"http://your.backend.com/auth"Replace with a strong password of your choice.
null or string
null"your_password"Authentication type.
one of "password", "userpass", "http", "command"
"password""userpass"A map of username-password pairs.
null or (attribute set of string)
null{
user1 = "pass1";
user2 = "pass2";
user3 = "pass3";
}The bandwidth values on the server side act as speed limits, limiting the maximum rate at which the server will send and receive data (per client).
NOTE: that the server's upload speed is the client's download speed, and vice versa.
You can omit these values or set them to zero on either or both sides, which would mean no limit. Supported units are:
- bps or b (bits per second)
- kbps or kb or k (kilobits per second)
- mbps or mb or m (megabits per second)
- gbps or gb or g (gigabits per second)
- tbps or tb or t (terabits per second)
null or (submodule)
nullThe server's download bandwidth.
string
"1 gbps""0"The server's upload bandwidth.
string
"1 gbps""0"disableUDP disables UDP forwarding, only allowing TCP connections.
boolean
falsetrueignoreClientBandwidth is a special option that, when enabled, makes the server to disregard any bandwidth hints set by clients,
opting to use a more traditional congestion control algorithm (currently BBR) instead.
This effectively overrides any bandwidth values set by clients in both directions.
This feature is primarily useful for server owners who prefer congestion fairness over other network traffic,
or who do not trust users to accurately set their own bandwidth values.
Bandwidth negotiation process
boolean
falsetrueThe server's listen address.
When the IP address is omitted, the server will listen on all interfaces, both IPv4 and IPv6.
To listen on IPv4 only, you can use 0.0.0.0:443.
To listen on IPv6 only, you can use [::]:443.
string
":443"One of the keys to Hysteria's censorship resistance is its ability to masquerade as standard HTTP/3 traffic. This means that not only do the packets appear as HTTP/3 to middleboxes, but the server also responds to HTTP requests like a regular web server. However, this means that your server must actually serve some content to make it appear authentic to potential censors. If censorship is not a concern, you can omit the masquerade section entirely. In this case, Hysteria will always return "404 Not Found" for all HTTP requests. Currently, Hysteria provides the following masquerade modes:
file: Act as a static file server, serving files from a directory.proxy: Act as a reverse proxy, serving content from another website.string: Act as a server that always returns a user-supplied string.
HTTP/HTTPS Masquerading documentation
null or (submodule)
nullThe directory to serve files from.
null or path
null"/www/masq"Whether to force HTTPS. If enabled, all HTTP requests will be redirected to HTTPS.
boolean
truefalseHTTP (TCP) listen address.
string
":80"HTTPS (TCP) listen address.
string
":443"Use a proxy for masquerading.
null or (submodule)
nullWhether to rewrite the Host header to match the proxied website. This is required if the target web server uses Host to determine which site to serve.
boolean
falsetrueThe URL of the website to proxy.
null or string
null"https://some.site.net"Use a string for masquerading.
null or (submodule)
nullThe string to return.
null or string
null"hello stupid world"Optional. The headers to return.
null or (attribute set of string)
nullOptional. The status code to return.
signed integer
200404Masquerade type
one of "file", "proxy", "string"
"proxy""string"By default, the Hysteria protocol mimics HTTP/3. If your network specifically blocks QUIC or HTTP/3 traffic (but not UDP in general), obfuscation can be used to work around this. We currently have an obfuscation implementation called "Salamander" that converts packets into seamingly random bytes with no pattern. This feature requires a password that must be identical on both the client and server sides.
null or (submodule)
nullReplace with a strong password of your choice.
null or string
null"cry_me_a_r1ver"Obfuscation type
value "salamander" (singular enum)
"salamander"Outbounds are used to define the "exit" through which a connection should be routed. For example, when combined with ACL, you can route all traffic except Netflix directly through the local interface, while routing Netflix traffic through a SOCKS5 proxy. Currently, Hysteria supports the following outbound types:
- direct: Direct connection through the local interface.
- socks5: SOCKS5 proxy.
- http: HTTP/HTTPS proxy.
NOTE: HTTP/HTTPS proxies do not support UDP at the protocol level. Sending UDP traffic to HTTP outbounds will result in rejection.
If you do not use ACL, all connections will always be routed through the first ("default") outbound in the list, and all other outbounds will be ignored.
null or (list of (submodule))
null[
{
name = "my_outbound_1";
type = "direct";
}
{
name = "my_outbound_2";
socks5 = {
addr = "shady.proxy.ru:1080";
password = "Elliot Alderson";
username = "hackerman";
};
type = "socks5";
}
{
http = {
insecure = false;
url = "http://username:password@sketchy-proxy.cc:8081";
};
name = "my_outbound_3";
type = "http";
}
{
direct = {
bindDevice = "eth233";
bindIPv4 = "2.4.6.8";
bindIPv6 = "0:0:0:0:0:ffff:0204:0608";
mode = "auto";
};
name = "hoho";
type = "direct";
}
]The direct outbound has a few additional options that can be used to customize its behavior:
NOTE: The options
bindIPv4,bindIPv6, andbindDeviceare mutually exclusive.
You can either specify
bindIPv4and/orbindIPv6withoutbindDevice, or usebindDevicewithoutbindIPv4andbindIPv6.
null or (submodule)
nullThe local network interface to bind to.
null or string
null"eth233"The local IPv4 address to bind to.
null or string
null"2.4.6.8"The local IPv6 address to bind to.
null or string
null"0:0:0:0:0:ffff:0204:0608"The available mode values are:
auto: Default. Dual-stack "happy eyeballs" mode. The client will attempt to connect to the destination using both IPv4 and IPv6 addresses (if available), and use the first one that succeeds.64: Always use IPv6 if available, otherwise use IPv4.46: Always use IPv4 if available, otherwise use IPv6.6: Always use IPv6. Fail if no IPv6 address is available.4: Always use IPv4. Fail if no IPv4 address is available.
one of "auto", "64", "46", "6", "4"
"auto"Optional. Whether to disable TLS verification. Applies to HTTPS proxies only.
boolean
falsetrueThe URL of the HTTP/HTTPS proxy. (Can be http:// or https://)
null or string
null"http://username:password@sketchy-proxy.cc:8081"The name of the outbound. This is used in ACL rules.
null or string
null"my_outbound_1"The address of the SOCKS5 proxy.
null or string
null"shady.proxy.ru:1080"Optional. The password for the SOCKS5 proxy, if authentication is required.
null or string
null"Elliot Alderson"Optional. The username for the SOCKS5 proxy, if authentication is required.
null or string
null"hackerman"Type of outbound
one of "direct", "socks5", "http"
"direct""socks5"The default stream and connection receive window sizes are 8MB and 20MB, respectively. We do not recommend changing these values unless you fully understand what you are doing. If you choose to change these values, we recommend keeping the ratio of stream receive window to connection receive window at 2:5.
null or (submodule)
nullDisable QUIC path MTU discovery.
boolean
falsetrueThe initial QUIC connection receive window size.
signed integer
20971520The initial QUIC stream receive window size.
signed integer
8388608The maximum QUIC connection receive window size.
signed integer
20971520The maximum idle timeout. How long the server will consider the client still connected without any activity.
string
"30s""60s"The maximum number of concurrent incoming streams.
signed integer
10242048The maximum QUIC stream receive window size.
signed integer
8388608You can specify what resolver (DNS server) to use to resolve domain names in client requests. If omitted, Hysteria will use the system's default resolver.
null or (submodule)
nullThe address of the HTTPS resolver.
string
"1.1.1.1:443"Disable TLS verification for the TLS resolver.
boolean
falsetrueThe SNI to use for the TLS resolver.
string
"cloudflare-dns.com"The timeout for DNS queries.
string
"10s""5s"The address of the TCP resolver.
string
"8.8.8.8:53"The timeout for DNS queries.
string
"4s""8s"The address of the TLS resolver.
string
"1.1.1.1:853"Disable TLS verification for the TLS resolver.
boolean
falsetrueThe SNI to use for the TLS resolver.
string
"cloudflare-dns.com"The timeout for DNS queries.
string
"10s"Resolver type
null or one of "tcp", "udp", "tls", "https"
null"tls"The address of the UDP resolver.
string
"8.8.4.4:53"The timeout for DNS queries.
string
"4s""8s"Certificates are read on every TLS handshake. This means you can update the files without restarting the server.
null or (submodule)
nullWhether to enable protocol sniffing.
boolean
falsetrueWhether to rewrite requests that are already in domain name form. If enabled, requests with the target address already in domain name form will still be sniffed.
boolean
falsetrueList of TCP ports. Only TCP requests on these ports will be sniffed.
null or string
null"80,443,8000-9000"Sniffing timeout. If the protocol/domain cannot be determined within this time, the original address will be used to initiate the connection.
null or string
null"2s"List of UDP ports. Only UDP requests on these ports will be sniffed.
null or string
null"all"speedTest enables the built-in speed test server.
When enabled, clients can test their download and upload speeds with the server.
For more information, see the Speed Test documentation.
boolean
falsetrueCertificates are read on every TLS handshake. This means you can update the files without restarting the server.
null or (submodule)
nullTLS certificate
null or path
null"./some.crt"TLS private key
null or path
null"./some.key"Verify the SNI provided by the client.
Accept the connection only when it matches what's in the certificate.
Terminate the TLS handshake otherwise.
Set to strict to enforce this behavior.
Set to disable to disable this entirely.
The default is dns-san, which enables this feature
only when the certificate contains the "Subject Alternative Name"
extension with a domain name in it.
null or one of "strict", "disable", "dns-san"
null"strict"The Traffic Stats API allows you to query the server's traffic statistics and kick clients using an HTTP API. For endpoints and usage, please refer to the Traffic Stats API documentation.
NOTE: If you don't set a secret, anyone with access to your API listening address will be able to see traffic stats and kick users.
We strongly recommend setting a secret, or at least using ACL to block users from accessing the API.
null or (submodule)
nullThe address to listen on.
null or string
null":9999"The secret key to use for authentication. Attach this to the Authorization header in your HTTP requests.
null or string
null"some_secret"udpIdleTimeout specifies the amount of time the server will keep a local UDP port open for each UDP session that has no activity.
This is conceptually similar to the NAT UDP session timeout.
string
"60s""120s"Path to file containing Hysteria settings.
null or path
nullUsername of the Hysteria user
string
"hysteria-server"