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

ACL

ACL, часто используемый в сочетании с исходящими каналами, — это очень мощная функция сервера Hysteria, позволяющая настраивать обработку запросов клиентов. Например, вы можете использовать ACL для блокировки определённых адресов, для использования разных исходящих каналов для разных сайтов или чтобы направлять каждого пользователя через свой исходящий канал.

Начиная с версии 2.14.0, правила ACL записываются как выражения, которые могут учитывать адрес назначения, протокол, адрес клиента и идентификатор аутентификации клиента. Устаревший синтаксис из предыдущих версий по-прежнему поддерживается.

Правила

Правила задаются в acl.rules в конфигурации сервера:

acl:
  rules:
    - outbound: some_proxy # (1)!
      match: auth.id == "alice" # (2)!
    - outbound: reject
      match: geoip("cn") || suffix("example.com")
    - outbound: default
      match: proto == "udp" && dst.port == 53 && cidr("8.8.8.8")
      hijack: 1.1.1.1 # (3)!
    - outbound: direct # (4)!
  1. Имя исходящего канала, который используется, если правило подходит. Один из ваших исходящих каналов или встроенный канал. Регистр не учитывается.
  2. Необязательно. Выражение, которое определяет, подходит ли правило к запросу.
  3. Необязательно. Перенаправить соединение на этот адрес. Должен быть IPv4/IPv6-адресом, а не доменным именем. Порт не меняется.
  4. Правило без match подходит ко всем запросам. Обычно размещается в конце как правило по умолчанию для всего остального.

Правила проверяются сверху вниз, и используется первое правило, соответствующее запросу. Если ни одно правило не соответствует, используется исходящий канал по умолчанию (первый в списке).

Правила также можно хранить в отдельном файле и указать его в acl.rulesFile. Файл содержит тот же список, без ключей acl: и rules::

- outbound: some_proxy
  match: auth.id == "alice"
- outbound: direct

Выражения

match записывается на языке expr. Самое полезное из него:

  • Сравнение: ==, !=, <, <=, >, >=
  • Логика: && (или and), || (или or), ! (или not) и скобки для группировки
  • Списки и диапазоны: auth.id in ["alice", "bob"], dst.port in 8000..8999
  • Строки: startsWith, endsWith, contains и matches для регулярных выражений, например dst.host matches "^cdn[0-9]+"

Результатом выражения правила должно быть true или false. Функции времени, такие как now() и date(), недоступны.

Переменные

Переменная Описание
proto "tcp" или "udp"
dst.host Запрошенный хост: доменное имя (в нижнем регистре, без точки в конце) или IP-адрес, как его отправил клиент. Если включён анализ протоколов и домен удалось определить, здесь будет этот домен.
dst.port Запрошенный порт
dst.ipv4, dst.ipv6 IPv4- и IPv6-адреса, в которые разрешается хост (см. Сопоставление доменов и IP). Пустая строка, если адреса нет.
auth.id Идентификатор аутентификации клиента. При аутентификации userpass это имя пользователя. При аутентификации http — id, который вернул ваш сервер аутентификации, а при аутентификации command — вывод команды. При аутентификации password всегда user.
client.ip, client.port IP-адрес и порт, с которых подключается клиент

Функции сопоставления

Функция Соответствует
domain("example.com") Точно доменному имени (не включает поддомены). Поддерживает подстановочный знак *, например domain("*.example.com") или domain("*.google.*").
suffix("example.com") Домену и всем его поддоменам: example.com, www.example.com и т. д.
cidr("10.0.0.0/8") IPv4/IPv6 CIDR или одному адресу, например cidr("1.1.1.1") или cidr("2001:db8::/32")
geoip("cn") Коду страны GeoIP
geosite("netflix") Категории GeoSite. Поддерживает атрибуты, например geosite("google@cn").
legacy("geoip:cn") Любому адресу в устаревшем синтаксисе, например legacy("suffix:example.com"). Используется преобразованными устаревшими правилами.

С одним аргументом функция сопоставления проверяет назначение запроса: его имя хоста, IPv4-адрес, в который он разрешается, или IPv6-адрес, в который он разрешается. Поэтому geoip("cn") также соответствует запросам к доменам, которые разрешаются в китайские IP-адреса.

С двумя аргументами функция проверяет второй аргумент. Это полезно для сопоставления адреса клиента, например geoip("cn", client.ip) или cidr("192.168.0.0/16", client.ip).

Первый аргумент должен быть записан прямо в правиле в виде строки. Hysteria подготавливает все функции сопоставления при запуске, поэтому geoip(auth.id) использовать нельзя.

Чтобы увидеть доступные категории GeoSite, посмотрите здесь:

Поведение сопоставления

Сопоставление доменов и IP

При обработке запросов на основе доменов Hysteria сначала разрешает домен, а затем пытается сопоставить результат как с доменными, так и с IP-правилами. Это означает, что правило, основанное на IP-адресе, будет применяться ко всем соединениям, которые в конечном итоге ведут к этому IP, независимо от того, использовал ли клиент IP-адрес или доменное имя.

Для сопоставления используются только первый IPv4- и первый IPv6-адрес домена.

Ошибки

Правила проверяются при запуске сервера. Такие ошибки, как неизвестная переменная, выражение, результат которого не true и не false, неизвестный исходящий канал или неизвестный код страны GeoIP, останавливают сервер с сообщением, в котором указано ошибочное правило:

invalid config: acl.rules: error at rules[0]: type acl.Auth has no field idd (1:6)
 | auth.idd == "alice"
 | .....^

Если выражение завершается ошибкой во время вычисления, например int(auth.id) > 100 при нечисловом идентификаторе, правило считается неподходящим.

Встроенные исходящие каналы

Если явно не переопределены в списке исходящих каналов, Hysteria предоставляет следующие встроенные каналы:

  • direct — прямой исходящий канал с конфигурацией по умолчанию (auto, без привязки)
  • reject — отклонить соединение
  • default — использовать первый исходящий канал в списке; если список пуст, эквивалентно direct

Примеры

Предположим, что есть следующий список исходящих каналов:

outbounds:
  - name: v4_only
    type: direct
    direct:
      mode: 4
  - name: v6_only
    type: direct
    direct:
      mode: 6
  - name: some_proxy
    type: socks5
    socks5:
      addr: ohno.moe:1080
acl:
  rules:
    # Весь трафик пользователя "alice" — через some_proxy
    - outbound: some_proxy
      match: auth.id == "alice"

    # Пользователи "bob" и "carol" не могут использовать UDP
    - outbound: reject
      match: auth.id in ["bob", "carol"] && proto == "udp"

    # Использовать v6_only для Google
    - outbound: v6_only
      match: suffix("google.com")

    # Использовать v4_only для Twitter, кроме пользователя "dave"
    - outbound: v4_only
      match: suffix("twitter.com") && auth.id != "dave"

    # Неанглийские IDN-домены также поддерживаются
    - outbound: v6_only
      match: domain("战狼*.中国")

    # Блокировать QUIC и SMTP
    - outbound: reject
      match: (proto == "udp" && dst.port == 443) || (proto == "tcp" && dst.port == 25)

    # Блокировать Китай и Северную Корею
    - outbound: reject
      match: geoip("cn") || geoip("kp")

    # Блокировать Facebook и рекламу Google
    - outbound: reject
      match: geosite("facebook") || geosite("google@ads")

    # Только клиенты из офисной сети могут обращаться к 10.0.0.0/8
    - outbound: reject
      match: cidr("10.0.0.0/8") && !cidr("192.0.2.0/24", client.ip)

    # Подменить DNS-запросы к 8.8.8.8 на 1.1.1.1, используя исходящий канал по умолчанию (первый)
    - outbound: default
      match: proto == "udp" && dst.port == 53 && cidr("8.8.8.8")
      hijack: 1.1.1.1

    # Прямое соединение для всего остального
    - outbound: direct

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

acl:
  rules:
    - outbound: reject
      match: geoip("cn") || geosite("facebook")
    - outbound: reject
      match: cidr("10.0.0.0/8") || cidr("172.16.0.0/12") || cidr("192.168.0.0/16") || cidr("fc00::/7")

Проверка правил

hysteria acl test показывает, какое правило и какой исходящий канал сервер использовал бы для запроса, никуда не подключаясь. Команда читает конфигурацию сервера, указанную в -c:

hysteria acl test -c server.yaml --auth alice example.com:443
Request:   tcp example.com:443, auth.id "alice"
Resolved:  ipv4 172.66.147.243, ipv6 2606:4700:10::6814:179a
Rule:      rules[0]: some_proxy, match: auth.id == "alice"
Outbound:  some_proxy
hysteria acl test -c server.yaml --proto udp 8.8.8.8:53
Request:   udp 8.8.8.8:53
Resolved:  ipv4 8.8.8.8
Rule:      rules[9]: default, match: proto == "udp" && dst.port == 53 && cidr("8.8.8.8")
Outbound:  v4_only
Hijacked:  1.1.1.1:53
Параметр По умолчанию Значение
--proto tcp tcp или udp
--auth Пусто Идентификатор аутентификации клиента (auth.id)
--client Нет Адрес клиента, IP или IP:порт (client.ip, client.port)
--ipv4, --ipv6 Разрешать Использовать эти адреса вместо разрешения хоста
--no-resolve Выкл. Не разрешать хост, у него не будет IP-адресов

По умолчанию хост разрешается резолвером из конфигурации сервера, так же как это делает сервер. Анализ протоколов не имитируется: хост используется как указан.

Устаревший синтаксис

До версии 2.14.0 правила ACL использовали другой синтаксис и задавались через acl.file или acl.inline. Этот синтаксис по-прежнему поддерживается: при запуске Hysteria преобразует такие правила в выражения, и они работают так же, как раньше, за одним исключением, описанным ниже.

acl:
  inline:
    - reject(geoip:cn)
    - reject(all, udp/443)
    - direct(all)

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

  • outbound(address)
  • outbound(address, proto/port)
  • outbound(address, proto/port, hijack_address)
  • # Это комментарий

Типы адресов

Поле address может быть одним из следующих:

  • Один IPv4/IPv6-адрес, например 1.1.1.1 или 2606:4700:4700::1111
  • IPv4/IPv6 CIDR, например 73.0.0.0/8 или 2001:db8::/32
  • Доменное имя, например example.com (не включает поддомены)
  • Доменное имя с подстановочным знаком, например *.example.com или *.google.*
  • Суффикс домена, например suffix:example.com (соответствует example.com и всем его поддоменам)
  • Код страны GeoIP, например geoip:cn или geoip:us
  • Категория GeoSite, например geosite:netflix или geosite:google (поддерживает атрибуты, например geosite:google@cn)
  • all — соответствует всем адресам

Протокол/порт

  • tcp или tcp/* — все TCP-порты
  • udp или udp/* — все UDP-порты
  • tcp/80 — TCP-порт 80
  • udp/53 — UDP-порт 53
  • udp/20000-30000 — UDP-порты с 20000 по 30000
  • */443 — TCP и UDP порт 443
  • *, */* или опущено — оба протокола и все порты

ПРИМЕЧАНИЕ: До версии 2.14.0 диапазон портов, начинающийся с 0 (например udp/0-100), или порт 0 (например tcp/0) соответствовал всем портам. Теперь он соответствует только указанным портам.

Подмена адреса

Если указан, соединение, соответствующее этому правилу, будет перенаправлено на указанный адрес. Адрес подмены должен быть IPv4/IPv6-адресом, а не доменным именем.

Устаревшие правила в rules

Список rules может также содержать устаревшие правила, так что можно добавлять новые правила (например, для отдельных пользователей) в существующий список, не преобразуя его. Запись legacy содержит одну или несколько строк устаревших правил, а запись legacyFile подключает файл с устаревшими правилами. Их правила проверяются на этом месте списка:

acl:
  rules:
    - outbound: some_proxy
      match: auth.id == "alice"
    - legacy: reject(geoip:cn)
    - legacy: |
        reject(geosite:facebook)
        reject(all, tcp/25)
    - legacyFile: /etc/hysteria/acl.txt
    - outbound: direct

Ошибки в устаревших записях указывают и запись, и строку, например error at rules[3] (/etc/hysteria/acl.txt) line 2: outbound v6_only not found.

Преобразование устаревших правил

hysteria acl translate выводит устаревшие правила в виде эквивалентного списка rules — именно его Hysteria и выполняет внутри:

hysteria acl translate acl.txt
acl:
  rules:
    - outbound: v6_only
      match: legacy("suffix:google.com")
    - outbound: reject
      match: proto == "udp" && dst.port == 443
    - outbound: reject
      match: legacy("geoip:cn")
    - outbound: default
      match: legacy("8.8.4.4") && proto == "udp" && dst.port == 53
      hijack: 1.1.1.1
    - outbound: direct

Если файл не указан, правила читаются со стандартного ввода. Проверяется только синтаксис: имена исходящих каналов и имена GeoIP/GeoSite проверяются, когда сервер загружает правила.