Protocol Types
Stash supports multiple types of proxy protocols and can proxy TCP / UDP protocols.
Each proxy must contain the following parameters:
name
: Proxy name, unique for each proxy.type
: Proxy type.server
: Server address, can be a domain name or IP address.port
: Port.
Proxies may support the following parameters:
tls
: Boolean, whether to forward based on TLS.skip-cert-verify
: Boolean, whether to ignore certificate verification during TLS handshake.server-cert-fingerprint
: String, verify server certificate SHA256 fingerprint during TLS handshake, encoded in Hex.sni
: String, Server Name Indication (opens in a new tab) sent during TLS handshake. Defaults to the value ofserver
ifsni
is empty.alpn
: Array of strings, Application-Layer Protocol Negotiation (ALPN) (opens in a new tab) sent during TLS handshake.interface-name
: Binding network card interface, only supported on macOS.
Additionally, for individual proxy latency testing, the following parameters can be modified:
benchmark-url
: The URL used for latency testing, default ishttp://www.apple.com/
.benchmark-timeout
: Latency test timeout in seconds, default is 5 seconds.benchmark-disabled
: Set totrue
to completely disable latency testing.
You can find more information about testing proxy latency here.
For QUIC-based protocols, port numbers can be changed periodically to counteract ISP speed throttling on a single port, a method known as port hopping.
ports
: String, supports multiple ports or port ranges separated by commas, for example,443,8443,5000-6000
.hop-interval
: Integer, port hop interval in seconds, default is 30 seconds.
When handling UDP, to maximize compatibility with various protocol behaviors, proxies will only forward in the form of IP addresses, unlike TCP which delegates domain name resolution to the proxy. Therefore, before initiating a UDP forwarding request, Stash will attempt to initiate a DNS query via the proxy to obtain correct CDN-optimized DNS resolution, then forward the UDP packet to this address.
Stash uses 1.0.0.1 for DNS queries by default, but it can be changed with the following parameter:
udp-nameserver
: Array, DNS server address, only supports UDP protocol.
For example:
name: proxy
type: ss
udp-nameserver: ['8.8.4.4', '8.8.8.8:53']
# ...
Different types of proxies may require specific parameters, which can be referred to below.
Shadowsocks / Shadowsocks2022
name: ss1
type: ss
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: 'password'
udp: true
plugin: null
plugin-opts:
mode:
host:
The following ciphers are supported:
aes-128-gcm
aes-192-gcm
aes-256-gcm
aes-128-cfb
aes-192-cfb
aes-256-cfb
aes-128-ctr
aes-192-ctr
aes-256-ctr
rc4-md5
chacha20
chacha20-ietf
xchacha20
chacha20-ietf-poly1305
xchacha20-ietf-poly1305
2022-blake3-aes-128-gcm
2022-blake3-aes-256-gcm
Shadowsocks Plugins
The following plugins are supported:
obfs
: Use simple-obfs (opens in a new tab) to obfuscate TCP traffic.
plugin: obfs
plugin-opts:
mode: tls # Obfuscation mode, can be http or tls
host: bing.com # Obfuscation domain, must match server configuration
v2ray-plugin
: Use v2ray-plugin (opens in a new tab) to carry traffic over WebSocket.
plugin: v2ray-plugin
plugin-opts:
mode: websocket # QUIC protocol is not supported for now
tls: true # wss
skip-cert-verify: true # Skip certificate verification
host: bing.com
path: '/'
headers: # Custom request headers
key: value
shadow-tls
: Use shadow-tls (opens in a new tab) for genuine TLS handshakes while being able to use certificates from major companies or institutions without self-issuance.
Currently, only Shadow TLS v2 (opens in a new tab) and v3 (opens in a new tab) versions are supported.
plugin: shadow-tls
plugin-opts:
password: singalongsong
host: weather-data.apple.com
skip-cert-verify: false # Skip certificate verification
version: 3 # Only supports 2 and 3
ShadowsocksR
name: ssr
type: ssr
server: server
port: 443
cipher: chacha20-ietf
password: 'password'
obfs: ''
protocol: ''
obfs-param: ''
protocol-param: ''
The supported ciphers are the same as for Shadowsocks.
Supported obfuscation methods (obfs):
plain
http_simple
http_post
random_head
tls1.2_ticket_auth
tls1.2_ticket_fastauth
Supported protocols (protocol):
origin
auth_sha1_v4
auth_aes128_md5
auth_aes128_sha1
auth_chain_a
auth_chain_b
SOCKS5
name: socks
type: socks5
server: server
port: 443
# username: username
# password: password
# tls: true
# skip-cert-verify: true
# udp: true
HTTP
name: http
type: http
server: server
port: 443
headers:
key: value
tls: true # https
skip-cert-verify: true
# username: username
# password: password
VMess
name: vmess
type: vmess
server: server
port: 443
uuid: d0529668-8835-11ec-a8a3-0242ac120002
cipher: auto
alterId: 64
network:
Supported ciphers:
auto
aes-128-gcm
chacha20-poly1305
none
Supported transport networks (network):
ws
h2
http
grpc
network: ws
ws-opts:
path: /path
headers:
Host: v2ray.com
max-early-data: 2048
early-data-header-name: Sec-WebSocket-Protocol
network: h2
tls: true
h2-opts:
host:
- http.example.com
- http-alt.example.com
path: /
Snell
name: snell
type: snell
server: server
port: 443
psk: yourpsk
udp: true # Requires v3 or above server
version: 3
# obfs-opts:
# mode: http # or tls
# host: bing.com
Snell UDP requires a server version of v3 or above.
Supported obfuscation modes (obfs-opts.mode):
- http
- tls
Trojan
name: trojan
type: trojan
server: server
port: 443
password: yourpassword
# udp: true
# sni: example.com # Server Name Indication, if empty will use value from server
# alpn:
# - h2
# - http/1.1
# skip-cert-verify: true
Supported transport networks (network):
ws
grpc
Hysteria
Hysteria is a feature-rich, network tool optimized for harsh network environments (bilateral acceleration), such as satellite networks, crowded public Wi-Fi, connecting to foreign servers from China, etc., based on a modified QUIC protocol.
For Hysteria server deployment, please refer to here (opens in a new tab).
name: 'hysteria'
type: hysteria
server: server
port: 443
up-speed: 100 # Upload bandwidth (in Mbps)
down-speed: 100 # Download bandwidth (in Mbps)
auth-str: your-password
# auth: aHR0cHM6Ly9oeXN0ZXJpYS5uZXQvd29yay9kb2NzL2FkdmFuY2VkLXVzYWdlLw== # bytes encoded in base64
protocol: '' # udp / wechat-video
obfs: '' # obfs password
sni: example.com # Server Name Indication, if empty will use value from server
alpn:
- hysteria
skip-cert-verify: true
Upload and download bandwidth are in Mbps, please fill them accurately; exceeding the actual bandwidth can have adverse effects.
External link: Online base64 encoding tool (opens in a new tab).
Hysteria2
Please note that Hysteria 2 is completely incompatible with Hysteria 1.x. For differences, refer to official documentation (opens in a new tab).
For Hysteria2 server deployment, please refer to here (opens in a new tab).
name: 'hysteria2'
type: hysteria2
server: server
port: 443
auth: your-password
fast-open: true
sni: example.com # Server Name Indication, if empty will use value from server
skip-cert-verify: true
up-speed: 100 # Upload bandwidth (optional, in Mbps)
down-speed: 100 # Download bandwidth (optional, in Mbps)
VLESS
The XTLS protocol removes redundant encryption in a TLS environment to provide better forwarding performance.
name: vless
type: vless
server: server
port: 443
uuid: d0529668-8835-11ec-a8a3-0242ac120002
# flow: xtls-rprx-direct
# skip-cert-verify: true
# network: h2
# tls: true
# ws-opts:
# path: /path
# headers:
# Host: v2ray.com
# grpc-opts:
# grpc-service-name: "example"
# h2-opts:
# host:
# - http.example.com
# - http-alt.example.com
# path: /
# reality-opts:
# public-key:
# short-id:
Supported XTLS modes (flow):
xtls-rprx-origin
xtls-rprx-direct
xtls-rprx-splice
xtls-rprx-vision
TUIC
TUIC is a lightweight QUIC-based proxy protocol written in Rust, currently supporting v4 and v5 versions. You can find more information here (opens in a new tab).
name: tuic-v5
type: tuic
server: server
port: 443
version: 5
uuid: d0529668-8835-11ec-a8a3-0242ac120002 # for v5
password: your_password # for v5
skip-cert-verify: true
sni: ''
alpn:
- h3
name: tuic-v4
type: tuic
server: server
port: 443
version: 4
token: 'your_token' # for v4
skip-cert-verify: true
sni: ''
alpn:
- h3
Please note that the Stash client does not support an empty ALPN, and the default ALPN is h3. Please add the --alpn h3
parameter on the TUIC server.
Choose the appropriate congestion control algorithm --congestion-controller
on the server side to fully utilize bandwidth.
Juicity
Juicity (opens in a new tab) is a QUIC-based proxy protocol inspired by TUIC.
name: juicity
type: juicity
server: server
port: 443
uuid: d0529668-8835-11ec-a8a3-0242ac120002
password: your_password
skip-cert-verify: true
sni: ''
alpn:
- h3
WireGuard
WireGuard (opens in a new tab) is a high-performance Layer 3 VPN. Stash supports using it as a Layer 4 proxy and can forward WireGuard packets through other protocols.
name: wireguard
type: wireguard
server: server # domain is supported
port: 51820
ip: 10.8.4.8
# ipv6: fe80::e6bf:faff:fea0:9fae # optional
private-key: 0G6TTWwvgv8Gy5013/jv2GttkCLYYaNTArHV0NdNkGI= # client private key
public-key: 0ag+C+rINHBnvLJLUyJeYkMWvIAkBjQPPObicuBUn1U= # peer public key
# preshared-key: # optional
dns: [1.0.0.1, 223.6.6.6] # optional
# mtu: 1420 # optional
# reserved: [0, 0, 0] # optional
# keepalive: 45 # optional
# underlying-proxy: # optional
# type: trojan
# server: your-underlying-proxy
# port: 443
# password: your-password
WireGuard is not a proxy protocol designed with high throughput in mind. Stash needs to perform Layer 3 to Layer 4 conversion in the user space, which results in greater performance loss compared to common proxy protocols. On mobile devices, WireGuard throughput is generally lower compared to Layer 4 proxy protocols.
If using underlying-proxy
, it must support UDP relay. It is recommended to
use protocols with UDP over TCP (such as Trojan, VLESS, VMess, Snell).
SSH
Forward TCP traffic via the Secure Shell Protocol (SSH) (opens in a new tab), supporting both password and key authentication.
Due to SSH not inherently supporting UDP forwarding, Stash cannot forward UDP traffic via SSH protocol.
name: ssh
type: ssh
server: server # domain is supported
port: 22
user: root
password: password
private-key: |
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA0G6TTWwvgv8Gy5013/jv2GttkCLYYaNTArHV0NdNkGI=
...
-----END RSA PRIVATE KEY-----
private-key-passphrase: your-passphrase # optional
DIRECT with Specified Interface
By creating a proxy of type direct
and specifying interface-name
, you can force certain traffic to go through a specified network card, commonly used to resolve issues where VPN and Stash cannot be used simultaneously.
For instance, if OpenVPN on this machine uses utun3
and you want traffic for 10.4.8.0/24
to go through utun3
rather than the default macOS network card.
name: my-corp-vpn
type: direct
interface-name: utun3
rules:
- IP-CIDR,10.4.8.0/24,my-corp-vpn
The above utun3
should be changed according to the actual situation.
You can use netstat -rn | grep utun3
to query the static routing table of utun3
.