HyNetwork Hysteria

Hysteria is a feature-packed proxy and relay utility optimized for lossy, unstable connections such as satellite networks, congested public WiFi, and connecting from China to servers abroad. It is powered by a customized QUIC (pronounced “quick”) protocol. QUIC is a general-purpose transport layer network protocol initially designed by Jim Roskind at Google. Although its name was initially the acronym for “Quick UDP Internet Connections,” it is now simply the name of the protocol.

We give instructions for the example of a Windows client, although clients for other platforms are also available. We use Debian 11 for server. You will need a domain name pointing to your server. Our example is vps.example.com.

1. Server

1.1. Generate Port Number and Password

You will need an unusual port number and a strong password for your Hysteria server. First generate a random port number from the command line of a Linux computer like this:

echo $((1024 + $RANDOM))

The shell function RANDOM gives you a pseudo-random integer between 0 and 32767, so after evaluating the arithmetical expression, you will end up with a port number between 1024 and 33791. In our examples on the rest of this page, we will use the result:

4401

Also generate a random password from the command line of a Linux computer:

openssl rand -base64 24

The openssl rand -base64 function gives you a random number, expressed in base-64 notation. Because of the argument 24, it will be based on 24 bytes or 192 bits. The result will have 32 base-64 characters. In our examples on the rest of this page, we will use the result:

Qi0n04pcO38SFROxnIspyE0WRwwMjVEf

1.2. Open Firewall

A server firewall is recommended but optional. There are multiple ways to implement a firewall on a Debian/Ubuntu server: nftables, iptables, ufw, and firewalld. We will use nftables in our examples, but you can use another method if you prefer.

SSH into your server as root.

Issue each of the following commands in turn to install and start nftables:

apt update && apt upgrade -y
apt install nftables -y
systemctl enable nftables
systemctl start nftables

Configure the firewall to accept related traffic and internal traffic on the loopback interface:

nft add rule inet filter input ct state related,established counter accept
nft add rule inet filter input iif lo counter accept

Configure the firewall to accept ping requests so that you can test latency:

nft add rule inet filter input ip protocol icmp icmp type echo-request counter accept
nft add rule inet filter input ip6 nexthdr icmpv6 icmpv6 type echo-request counter accept

Open port 22 for SSH. If you can restrict the port 22 rule so that only certain source IP addresses are whitelisted for SSH access, then so much the better. For example, if you always connect to your server from source IP address XX.XX.XX.XX:

nft add rule inet filter input tcp dport 22 ip saddr XX.XX.XX.XX/32 counter accept

If you cannot restrict the port 22 rule, then you will have to open the port to the whole world instead:

nft add rule inet filter input tcp dport 22 counter accept

Open the server for Hysteria UDP input on your chosen port:

nft add rule inet filter input udp dport 4401 counter accept

Open the server ports 80 and 443:

nft add rule inet filter input tcp dport {http, https} counter accept

Drop all unexpected input:

nft add rule inet filter input counter drop

Save the rules:

nft list ruleset > /etc/nftables.conf

1.3. Obtain SSL Certificate

Follow the certbot instructions to obtain an SSL certificate for your server:

apt install snapd -y
snap install core; snap refresh core
snap install --classic certbot
ln -s /snap/bin/certbot /usr/bin/certbot
certbot certonly --standalone

Answer the questions from the certbot script:

On success, certbot stores your certificate and key as follows:

Test automatic renewal:

certbot renew --dry-run

1.4. Install Hysteria on Server

Use the provided script to install the components needed for a Hysteria server:

wget https://raw.githubusercontent.com/HyNetwork/hysteria/master/install_server.sh
chmod +x install_server.sh
./install_server.sh

Hysteria latest version is installed.

1.5. Configure Server

Edit the sample configuration file:

vi /etc/hysteria/config.json

Delete the existing contents and insert the template below, changing it as necessary for your port, domain name, and password:

{
  "listen": ":4401",
  "cert": "/etc/letsencrypt/live/vps.example.com/fullchain.pem",
  "key": "/etc/letsencrypt/live/vps.example.com/privkey.pem",
  "obfs": "xnnIxB3FqDr8mxIDXSNRIa6TotpWgb5m"
}

Write the file to disk and quit the editor.

1.6. Configure to Run as Root

The easiest way to access the private key of the certificate is just to run Hysteria as root. Edit the systemd service file:

vi /lib/systemd/system/hysteria-server.service

Change the line:

User=root

Write the file and quit the editor.

Reload the daemon:

systemctl daemon-reload

1.7. Start Hysteria Server

Execute the commands:

systemctl enable hysteria-server
systemctl start hysteria-server

Check that Hysteria server is active (running):

systemctl status hysteria-server

1.8. Exit SSH on Server

Your work on the server is done, so you can exit your SSH session now:

exit

2. Client

2.1. Download client

You can download pre-built binaries from https://github.com/HyNetwork/hysteria/releases.

We are using Windows as our example client here. Therefore download the latest release of hysteria-tun-windows-6.0-amd64.exe.

2.2. Configure client

Use Windows Notepad to create a text file. Insert contents based on this model:

{
  "server": "vps.example.com:4401",
  "obfs": "xnnIxB3FqDr8mxIDXSNRIa6TotpWgb5m",
  "up_mbps": 1000,
  "down_mbps": 1000,
  "socks5": {
    "listen": "127.0.0.1:1080"
  },
  "http": {
    "listen": "127.0.0.1:1081"
  }
}

This configuration enables a SOCKS5 proxy (with both TCP and UDP support) and an HTTP proxy at the same time. There are many other modes in Hysteria. Be sure to check them out in the wiki under Advanced Usage. To enable or disable a mode, simply add or remove its entry in the configuration file.

Save the file with name config.json (with no .txt at the end of its name) under the same directory as your client program. By default this would be your Downloads directory.

2.3. Run Client

To launch the client, open a Command Prompt window and issue the commands:

cd Downloads
hysteria-tun-windows-6.0-amd64.exe client

You should see messages like this:

[INFO] [config:{Server:vps.example.com:4401 Protocol: Up: UpMbps:1000 Down: DownMbps:1000 Retry:0 RetryInterval:0 SOCKS5:{Listen:127.0.0.1:1080 Timeout:0 DisableUDP:false User: Password:} HTTP:{Listen:127.0.0.1:1081 Timeout:0 User: Password: Cert: Key:} TUN:{Name: Timeout:0 Address: Gateway: Mask: DNS:[] Persist:false} TCPRelays:[] TCPRelay:{Listen: Remote: Timeout:0} UDPRelays:[] UDPRelay:{Listen: Remote: Timeout:0} TCPTProxy:{Listen: Timeout:0} UDPTProxy:{Listen: Timeout:0} TCPRedirect:{Listen: Timeout:0} ACL: MMDB: Obfs:xnnIxB3FqDr8mxIDXSNRIa6TotpWgb5m Auth:[] AuthString: ALPN: ServerName: Insecure:false CustomCA: ReceiveWindowConn:0 ReceiveWindow:0 DisableMTUDiscovery:false Resolver: ResolvePreference:}] ←[0mClient configuration loaded
[INFO] [addr:vps.example.com:4401] ←[0mConnected
[INFO] [addr:127.0.0.1:1081] ←[0mHTTP server up and running
[INFO] [addr:127.0.0.1:1080] ←[0mSOCKS5 server up and running

Leave the Command Prompt window open with Hysteria client running in it.

2.4. Set System Proxy

Open Settings > Network & internet > Proxy > Manual proxy setup.

Click Save.

2.5. Test Browser

Open a browser and try to visit https://ipchicken.com.

3. Get Help and Report Issues

For documentation on Hysteria, consult the wiki.

Report Hysteria issues on the GitHub issues page.

Updated 2022-07-06