Перейти к содержанию

Полная конфигурация клиента

На этой странице приведена документация по каждому полю конфигурационного файла клиента.

ПРИМЕЧАНИЕ: Один из распространённых паттернов в конфигурации клиента и сервера — «селектор типа»:

example:
  type: a
  a:
    something: something
  b:
    something: something
  c:
    something: something

type определяет, какой режим использовать и какие подполя парсить. В этом примере поле example может быть a, b или c. Если выбрано a, будет обработано подполе a, а подполя b и c будут проигнорированы.

Адрес сервера

Поле server указывает адрес сервера Hysteria, к которому должен подключаться клиент. Адрес может быть в формате host:port или просто host. Если порт опущен, по умолчанию используется 443.

Также можно использовать URI Hysteria 2 (hysteria2://). В этом случае, поскольку URI уже содержит пароль и некоторые другие настройки, вы не можете (и не нужно) указывать их отдельно в конфигурационном файле.

server: example.com

server: hysteria2://user:[email protected]/

Аутентификация

auth: some_password

ПРИМЕЧАНИЕ: Если сервер использует аутентификацию userpass, формат должен быть username:password.

TLS

tls:
  sni: another.example.com # (1)!
  insecure: false # (2)!
  pinSHA256: BA:88:45:17:A1... # (3)!
  ca: custom_ca.crt # (4)!
  clientCertificate: client.crt # (5)!
  clientKey: client.key # (6)!
  1. Имя сервера для проверки TLS. Если опущено, имя сервера будет извлечено из поля server.
  2. Отключить проверку TLS.
  3. Проверка отпечатка сертификата сервера. Вы можете получить отпечаток сертификата с помощью openssl: openssl x509 -noout -fingerprint -sha256 -in your_cert.crt
  4. Использовать пользовательский CA-сертификат для проверки TLS.
  5. Использовать клиентский сертификат для проверки mTLS.
  6. Использовать клиентский ключ для проверки mTLS.

Транспорт

Секция transport предназначена для настройки базового протокола, используемого QUIC-соединением. В настоящее время единственный доступный тип — udp, но мы оставляем место для возможных будущих расширений.

transport:
  type: udp # (2)!
  udp:
    hopInterval: 30s # (1)!
  1. Интервал смены портов. Актуально только при использовании адреса со сменой портов. Подробнее см. Смена портов.
  2. Пожалуйста, прочитайте инструкции о «селекторе типа» в начале этой страницы.

Обфускация

По умолчанию протокол Hysteria имитирует HTTP/3. Если ваша сеть специально блокирует QUIC или HTTP/3 трафик (но не UDP в целом), для обхода можно использовать обфускацию. В настоящее время у нас есть реализация обфускации под названием «Salamander», которая преобразует пакеты в случайные байты без паттернов. Для этой функции требуется пароль, который должен быть одинаковым на стороне клиента и сервера.

ПРИМЕЧАНИЕ: Использование неправильного пароля обфускации приведёт к таймауту соединения, как если бы сервер вообще не работал. При проблемах с подключением проверьте правильность пароля.

obfs:
  type: salamander # (2)!
  salamander:
    password: cry_me_a_r1ver # (1)!
  1. Замените на надёжный пароль по вашему выбору.
  2. Пожалуйста, прочитайте инструкции о «селекторе типа» в начале этой страницы.

Параметры QUIC

quic:
  initStreamReceiveWindow: 8388608 # (1)!
  maxStreamReceiveWindow: 8388608 # (2)!
  initConnReceiveWindow: 20971520 # (3)!
  maxConnReceiveWindow: 20971520 # (4)!
  maxIdleTimeout: 30s # (5)!
  keepAlivePeriod: 10s # (6)!
  disablePathMTUDiscovery: false # (7)!
  sockopts:
    bindInterface: eth0 # (8)!
    fwmark: 1234 # (9)!
    fdControlUnixSocket: ./test.sock # (10)!
  1. Начальный размер окна приёма потока QUIC.
  2. Максимальный размер окна приёма потока QUIC.
  3. Начальный размер окна приёма соединения QUIC.
  4. Максимальный размер окна приёма соединения QUIC.
  5. Максимальный таймаут бездействия. Сколько времени клиент будет считать соединение активным, если от сервера не поступают пакеты.
  6. Период поддержки соединения. Как часто клиент будет отправлять пакет серверу для поддержания соединения.
  7. Отключить обнаружение MTU пути QUIC.
  8. (Только Linux) Имя интерфейса. Принудительно отправляет QUIC-пакеты через этот интерфейс.
  9. (Только Linux) Тег SO_MARK, добавляемый к QUIC-пакетам.
  10. (Только Linux) Путь к Unix Socket, на котором слушает другой процесс. Клиент Hysteria отправит файловый дескриптор (FD), используемый для QUIC-соединения, как вспомогательную информацию на этот Unix Socket, позволяя слушающему процессу выполнять другие пользовательские настройки. Эта опция может использоваться при разработке Android-приложений; подробнее см. Протокол FD Control.

Размеры окна приёма потока и соединения по умолчанию составляют 8 МБ и 20 МБ соответственно. Мы не рекомендуем изменять эти значения, если вы полностью не понимаете, что делаете. Если вы решите их изменить, рекомендуем сохранять соотношение окна приёма потока к окну приёма соединения как 2:5.

Примечание: Опции в секции sockopts применяются только к исходящим QUIC-соединениям, а не к другим возможным исходящим соединениям (например, DNS-запросам для разрешения адреса сервера).

Полоса пропускания

bandwidth:
  up: 100 mbps
  down: 200 mbps

Hysteria имеет два встроенных алгоритма управления перегрузкой (BBR и Brutal). Выбор алгоритма зависит от того, указана ли информация о полосе пропускания. Если вы хотите использовать BBR вместо Brutal, удалите всю секцию bandwidth. Подробнее см. Процесс согласования полосы пропускания и Детали управления перегрузкой.

⚠️ Внимание Более высокие значения полосы пропускания не всегда лучше; будьте очень осторожны и не превышайте максимальную пропускную способность, которую поддерживает ваша текущая сеть. В противном случае это приведёт к обратному эффекту — перегрузке сети и нестабильному соединению.

Фактическая скорость загрузки клиента будет меньшим из указанного здесь значения и максимальной скорости скачивания сервера (если установлена на сервере). Аналогично, фактическая скорость скачивания клиента будет меньшим из указанного здесь значения и максимальной скорости загрузки сервера (если установлена на сервере).

Одно исключение — если на сервере включена опция ignoreClientBandwidth, указанные здесь значения будут проигнорированы.

Поддерживаемые единицы измерения:

  • bps или b (бит в секунду)
  • kbps или kb или k (килобит в секунду)
  • mbps или mb или m (мегабит в секунду)
  • gbps или gb или g (гигабит в секунду)
  • tbps или tb или t (терабит в секунду)

Fast Open

Fast Open позволяет сэкономить один RTT (время прохождения туда-обратно) на каждом соединении, но ценой корректной семантики протоколов SOCKS5/HTTP-прокси. При включении этой опции клиент всегда немедленно принимает соединение, не подтверждая у сервера доступность назначения. Если сервер затем откажет или отклонит соединение, клиент просто закроет соединение, не отправляя данных обратно прокси-клиенту.

fastOpen: true

Lazy

При включении клиент «ленится» в том смысле, что он будет пытаться подключиться к серверу только при наличии входящего соединения от одного из включённых клиентских режимов. Это отличается от поведения по умолчанию, когда клиент пытается подключиться к серверу сразу при запуске.

Опция lazy может быть полезна, если вы не уверены, когда будете использовать клиент, и хотите избежать простаивающих соединений. Она также полезна, если ваше интернет-соединение может быть не готово при запуске клиента Hysteria.

lazy: true

Режимы

Для использования клиента Hysteria необходимо указать хотя бы один из следующих режимов:

Подсказка: Начиная с версии 2.4.1, клиент Hysteria поддерживает одновременно протоколы SOCKS5 и HTTP на одном порту. Просто укажите оба — socks5 и http — в конфигурации и убедитесь, что их адреса listen совпадают.

SOCKS5

SOCKS5-прокси-сервер, совместимый с любым SOCKS5-приложением. Поддерживает TCP и UDP.

socks5:
  listen: 127.0.0.1:1080 # (1)!
  username: user # (2)!
  password: pass # (3)!
  disableUDP: false # (4)!
  1. Адрес прослушивания.
  2. Необязательно. Имя пользователя для аутентификации.
  3. Необязательно. Пароль для аутентификации.
  4. Необязательно. Отключить поддержку UDP.

HTTP

HTTP-прокси-сервер, совместимый с любым HTTP-прокси-приложением. Поддерживает как незашифрованный HTTP, так и HTTPS (CONNECT).

http:
  listen: 127.0.0.1:8080 # (1)!
  username: king # (2)!
  password: kong # (3)!
  realm: martian # (4)!
  1. Адрес прослушивания.
  2. Необязательно. Имя пользователя для аутентификации.
  3. Необязательно. Пароль для аутентификации.
  4. Необязательно. Область (realm) для аутентификации.

Проброс TCP

Проброс TCP позволяет перенаправлять один или несколько TCP-портов с сервера (или любого удалённого хоста) на клиент. Это полезно, например, если вы хотите получить доступ к сервису, доступному только в сети сервера.

tcpForwarding:
  - listen: 127.0.0.1:6600 # (1)!
    remote: 127.0.0.1:6600 # (2)!
  - listen: 127.0.0.1:6601 # (3)!
    remote: other.machine.internal:6601
  1. Адрес прослушивания.
  2. Адрес перенаправления.
  3. Вы можете указать одно или несколько правил перенаправления.

Проброс UDP

Проброс UDP позволяет перенаправлять один или несколько UDP-портов с сервера (или любого удалённого хоста) на клиент. Это полезно, например, если вы хотите получить доступ к сервису, доступному только в сети сервера.

udpForwarding:
  - listen: 127.0.0.1:5300 # (1)!
    remote: 127.0.0.1:5300 # (2)!
    timeout: 20s # (3)!
  - listen: 127.0.0.1:5301 # (4)!
    remote: other.machine.internal:5301
    timeout: 20s
  1. Адрес прослушивания.
  2. Адрес перенаправления.
  3. Необязательно. Таймаут для каждой UDP-сессии. Если опущено, по умолчанию 60 секунд.
  4. Вы можете указать одно или несколько правил перенаправления.

TCP TProxy (только Linux)

TPROXY (прозрачный прокси) — это функция, доступная только в Linux, позволяющая прозрачно проксировать TCP-соединения. Подробнее см. Настройка TPROXY.

tcpTProxy:
  listen: :2500 # (1)!
  1. Адрес прослушивания.

UDP TProxy (только Linux)

TPROXY (прозрачный прокси) — это функция, доступная только в Linux, позволяющая прозрачно проксировать UDP-соединения. Подробнее см. Настройка TPROXY.

udpTProxy:
  listen: :2500 # (1)!
  timeout: 20s # (2)!
  1. Адрес прослушивания.
  2. Необязательно. Таймаут для каждой UDP-сессии. Если опущено, по умолчанию 60 секунд.

TCP Redirect (только Linux)

REDIRECT — это, по сути, частный случай DNAT, где адресом назначения является localhost. Этот метод предшествует TPROXY как более старый способ реализации прозрачного TCP-прокси. Рекомендуем использовать TPROXY, если ваше ядро его поддерживает.

tcpRedirect:
  listen: :3500

Пример:

iptables -t nat -N HYSTERIA
iptables -t nat -A HYSTERIA -d 0.0.0.0/8 -j RETURN
iptables -t nat -A HYSTERIA -d 10.0.0.0/8 -j RETURN
iptables -t nat -A HYSTERIA -d 127.0.0.0/8 -j RETURN
iptables -t nat -A HYSTERIA -d 169.254.0.0/16 -j RETURN
iptables -t nat -A HYSTERIA -d 172.16.0.0/12 -j RETURN
iptables -t nat -A HYSTERIA -d 192.168.0.0/16 -j RETURN
iptables -t nat -A HYSTERIA -d 224.0.0.0/4 -j RETURN
iptables -t nat -A HYSTERIA -d 240.0.0.0/4 -j RETURN
iptables -t nat -A HYSTERIA -p tcp -j REDIRECT --to-ports 3500
iptables -t nat -A OUTPUT -p tcp -j HYSTERIA
iptables -t nat -A PREROUTING -p tcp -j HYSTERIA

ip6tables -t nat -N HYSTERIA
ip6tables -t nat -A HYSTERIA ! -d 2000::/3 -j RETURN
ip6tables -t nat -A HYSTERIA -p tcp -j REDIRECT --to-ports 3500
ip6tables -t nat -A OUTPUT -p tcp -j HYSTERIA
ip6tables -t nat -A PREROUTING -p tcp -j HYSTERIA

define HYSTERIA_REDIRECT_PORT=3500
define BYPASS_IPV4={
    0.0.0.0/8, 10.0.0.0/8, 127.0.0.0/8, 169.254.0.0/16,
    172.16.0.0/12, 192.168.0.0/16, 224.0.0.0/3
}
define BYPASS_IPV6={ ::/128 }

table inet hysteria_redirect {
  chain prerouting {
    type nat hook prerouting priority filter; policy accept;
    meta l4proto tcp counter jump hysteria
  }

  chain output {
    type nat hook output priority filter; policy accept;
    meta l4proto tcp counter jump hysteria
  }

  chain hysteria {
    ip daddr $BYPASS_IPV4 counter return
    ip6 daddr $BYPASS_IPV6 counter return
    ip6 daddr != 2000::/3 counter return
    meta l4proto tcp counter redirect to :$HYSTERIA_REDIRECT_PORT
  }
}

TUN

Режим TUN — это кроссплатформенное решение для прозрачного проксирования, которое создаёт виртуальный сетевой интерфейс в системе и использует системные маршруты для перехвата и перенаправления трафика. В настоящее время работает на Windows, Linux и macOS.

В отличие от традиционных L3 VPN (таких как WireGuard и OpenVPN), TUN-режим Hysteria может обрабатывать только TCP и UDP, не поддерживая другие протоколы, включая ICMP (например, ping). Он также берёт на себя управление TCP-стеком для ускорения TCP-соединений.

По сравнению с реализацией в Hysteria 1, TUN в Hysteria 2 основан на «system» стеке sing-tun, требующем настройки адреса /30 IPv4 и /126 IPv6 на интерфейсе. Hysteria автоматически настроит сетевой интерфейс, адреса и маршруты.

ПРИМЕЧАНИЕ: ipv4Exclude/ipv6Exclude важны для предотвращения петли маршрутизации. Подробнее см. комментарии к этим полям.

tun:
  name: "hytun" # (1)!
  mtu: 1500 # (2)!
  timeout: 5m # (3)!
  address: # (4)!
    ipv4: 100.100.100.101/30
    ipv6: 2001::ffff:ffff:ffff:fff1/126
  route: # (5)!
    ipv4: [0.0.0.0/0] # (6)!
    ipv6: ["2000::/3"] # (7)!
    ipv4Exclude: [192.0.2.1/32] # (8)!
    ipv6Exclude: ["2001:db8::1/128"] # (9)!
  1. Имя TUN-интерфейса.
  2. Необязательно. Максимальный размер пакета, принимаемый TUN-интерфейсом. По умолчанию 1500 байт.
  3. Необязательно. Таймаут UDP-сессии. По умолчанию 5 минут.
  4. Необязательно. Адреса для использования на интерфейсе. Установите любой приватный адрес, не конфликтующий с вашей LAN. По умолчанию — как показано.
  5. Необязательно. Правила маршрутизации. Пропуск или отсутствие всех полей означает, что маршруты не будут добавлены автоматически. В большинстве случаев достаточно ipv4Exclude или ipv6Exclude.
  6. Необязательно. IPv4-префикс для проксирования. Если настроено любое другое поле, по умолчанию 0.0.0.0/0.
  7. Необязательно. IPv6-префикс для проксирования. Из-за ограничений YAML требуются кавычки. Если настроено любое другое поле, по умолчанию ::/0.
  8. Необязательно. IPv4-префикс для исключения. Добавьте сюда адрес вашего сервера Hysteria, чтобы избежать петли маршрутизации. Если хотите полностью отключить IPv4-проксирование, можно указать 0.0.0.0/0.
  9. Необязательно. IPv6-префикс для исключения. Из-за ограничений YAML требуются кавычки. Добавьте сюда адрес вашего сервера Hysteria, чтобы избежать петли маршрутизации. Если хотите полностью отключить IPv6-проксирование, можно указать "::/0".

Примечание: На Linux иногда необходимо отключить rp_filter, чтобы интерфейс мог получать трафик от других интерфейсов.

sysctl net.ipv4.conf.default.rp_filter=2
sysctl net.ipv4.conf.all.rp_filter=2

Известные проблемы совместимости:

ОС Проблема
macOS Имя TUN-интерфейса должно быть utun с последующим числом, например utun123.
Windows Server 2022 Для работы необходимо отключить Windows Firewall.
CentOS 7 Для работы необходимо отключить фаервол. Для ядер до 4.17 автоматически добавляемые маршруты не будут работать корректно (причина). Обновите ядро до 4.17 или выше, или выполните ip rule del from all goto 9010; ip -6 rule del from all goto 9010 после запуска клиента Hysteria.
FreeBSD Не поддерживается