TUN

Создает TUN-интерфейс. Трафик, направленный в этот интерфейс, обрабатывается Xray. В настоящее время поддерживаются Windows, Linux, macOS и FreeBSD.

На Android и iOS TUN FD должен передаваться внешним приложением через переменную окружения XRAY_TUN_FD, при этом для перенаправления трафика используется интерфейс, назначенный системой. Он не может запускаться самостоятельно и служит лишь способом для приложения передавать трафик в Xray.

На Linux эту переменную окружения можно опционально использовать для передачи TUN FD в некоторых облегченных или непривилегированных реализациях.

InboundConfigurationObject

InboundConfigurationObject соответствует элементу settings в InboundObject.

json

{
  "inbounds": [
    {
      // ...
      "protocol": "tun",
      "settings": {
        "name": "utun10",
        "desc": "Wintun",
        "mtu": 1500,
        "gateway": ["10.0.0.1/16", "fc00::1/64"],
        "dns": ["1.1.1.1", "8.8.8.8"],
        "userLevel": 0,
        "autoSystemRoutingTable": ["0.0.0.0/0", "::/0"],
        "autoOutboundsInterface": "auto",
        "autoSystemDnsToGateway": false,
        "autoSystemWfpBlockLeak": ["dns", "misconfigtun"]
      }
    }
  ]
}

name: string

Имя создаваемого TUN-интерфейса. По умолчанию "utunN".

Где N — случайное число в диапазоне от 10 до 1024.

В macOS имя должно иметь вид utunN, а во FreeBSD — tunN. В Windows уже существующий адаптер Wintun с таким именем используется повторно.

desc: string

Описание имени сетевого интерфейса в Windows. По умолчанию Wintun. Эта строка объединяется со словом "Tunnel", образуя "xxx Tunnel".

В Windows можно использовать route print для просмотра подробной информации.

mtu: number

Значение MTU интерфейса. По умолчанию 1500.

gateway: [string]

Список префиксов адресов, назначаемых TUN-интерфейсу, обычно отдельно для IPv4 и IPv6, например "10.0.0.1/16" и "fc00::1/64".

Если параметр не задан, результат зависит от системы: в Linux Xray не назначает адресов; в Windows система сама назначает TUN-интерфейсу локальные адреса канала (IPv6 сразу, IPv4 из 169.254.0.0/16 через несколько секунд); в macOS и FreeBSD используется 169.254.10.1/30. macOS и FreeBSD используют только первый IPv4-префикс.

В Windows с IPv6, отключённым через DisabledComponents (установлен бит 0x10, например 0xFF), ошибки настройки записей IPv6 здесь, в dns и в autoSystemRoutingTable, а также очистки DNS-серверов IPv6, когда в dns их нет, только записываются в журнал. В остальных случаях они не дают TUN-интерфейсу запуститься.

dns: [string]

Список DNS-серверов, назначаемых TUN-интерфейсу, например "1.1.1.1" и "8.8.8.8".

Параметр действует только в Windows, где серверы назначаются TUN-интерфейсу. Windows отправляет запросы им, а также DNS-серверам других интерфейсов; "dns" в autoSystemWfpBlockLeak блокирует последние. Запросы к этим серверам идут через TUN-интерфейс, только если серверы входят в gateway или autoSystemRoutingTable. В Xray это обычный трафик на порт 53: правило маршрутизации может передать его DNS-исходящему, иначе он пересылается этим серверам, как любой другой трафик. Адреса TUN-интерфейса не регистрируются в DNS, а кэш DNS очищается при запуске и остановке TUN-интерфейса.

Если используется autoOutboundsInterface, DNS-сервер localhost в Xray обходит эти серверы (если только их не использует и другой интерфейс), так как его запросы к ним вернулись бы в TUN-интерфейс.

В Linux и FreeBSD системный DNS не берется из этого параметра, см. autoSystemDnsToGateway; в macOS системный DNS не настраивается.

userLevel: number

Уровень пользователя. Для соединения будет использоваться локальная политика, соответствующая этому уровню пользователя.

Значение userLevel соответствует значению level в policy. Если не указано, по умолчанию равно 0.

autoSystemRoutingTable: [string]

Список целевых префиксов, которые Xray автоматически добавляет в системную таблицу маршрутизации, чтобы трафик направлялся в этот TUN-интерфейс. Каждый элемент задается в формате CIDR. Например, "0.0.0.0/0" означает весь IPv4-трафик, а "::/0" означает весь IPv6-трафик.

В настоящее время поддерживается на Windows, Linux, macOS и FreeBSD.

autoOutboundsInterface: string

Автоматически привязывает исходящие соединения Xray к физическому сетевому интерфейсу, чтобы трафик, создаваемый самим Xray, не отправлялся обратно в TUN и не образовывал петлю.

Если соединение не удаётся привязать к этому интерфейсу, оно завершается с ошибкой, а не уходит без привязки, иначе оно могло бы вернуться в TUN-интерфейс и образовать петлю. В Windows подходит и интерфейс только с IPv4 или только с IPv6: соединения отсутствующей версии IP завершаются с ошибкой, а не уходят через другой интерфейс.

Соединения к адресам loopback не привязываются. Во FreeBSD соединения Xray вместо этого переводятся во вторую таблицу маршрутизации (FIB 1), повторяющую физический маршрут по умолчанию; для этого загрузочный параметр net.fibs должен быть не меньше 2, иначе Xray не запускается.

В Windows эта привязка соблюдается, только пока у этого интерфейса для версий IP, маршрутизируемых в TUN-интерфейс, выключены weak host send и пересылка (forwarding); иначе Windows отправляет собственные соединения Xray в TUN-интерфейс, где они зависают. Поэтому, пока работает TUN-интерфейс, Xray выключает на этом интерфейсе weak host send и включает его обратно при остановке. Пересылку, которая нужна мобильному хот-споту и общему доступу к подключению к Интернету, Xray не трогает, а выводит предупреждение: настройте хот-спот на раздачу TUN-интерфейса (Параметры → Сеть и Интернет → Мобильный хот-спот, выберите TUN-интерфейс как подключение для раздачи), тогда устройства хот-спота тоже будут работать через Xray. TUN-интерфейс появляется в этом списке, только пока работает Xray.

Эквивалентно автоматической установке sockopt.interface для всех исходящих соединений (при этом дополнительно охватывает и некоторые запросы, для которых нельзя настроить параметры исходящего соединения, например различные локальные режимы встроенного DNS); может быть переопределено вручную заданным sockopt.

Значение по умолчанию — null, то есть параметр не задан. Можно указать конкретное имя интерфейса или "auto", чтобы Xray выбрал его автоматически. Если задан autoSystemRoutingTable, но это поле явно не указано, Xray будет обрабатывать его как "auto".

autoSystemDnsToGateway: true | false

Этот параметр действует только в Linux и FreeBSD. По умолчанию false.

Если параметр включен, Xray направляет системный резолвер на TUN-интерфейс, чтобы системные DNS-запросы шли через Xray: в Linux — systemd-resolved (через resolvectl) на первый IPv4-адрес из gateway плюс один (например, 10.0.0.1/16 → 10.0.0.2), а без IPv4 — на первый IPv6-адрес плюс один (например, fc00::1/64 → fc00::2); во FreeBSD — через resolvconf(8) на сам первый IPv4-адрес из gateway (например, 10.0.0.1/16 → 10.0.0.1), так как TUN-интерфейс там получает следующий адрес. Без gateway Xray сообщает об ошибке и не запускается. Адрес не берется из dns, иначе система опрашивала бы эти серверы напрямую, мимо TUN-интерфейса.

Запросы на этот адрес должен обрабатывать Xray, поэтому нужно правило маршрутизации, которое передает порт 53 этого входящего подключения DNS-исходящему. Перед изменением системного DNS Xray проверяет это и не запускается, если такой запрос не дойдет до DNS-исходящего или если собственный DNS Xray может обращаться к системному резолверу (нет DNS-серверов или задан localhost), что привело бы к петле.

В Linux нужен запущенный systemd-resolved версии 240 или новее. Во FreeBSD resolvconf должен записывать файлы резолвера (без resolvconf=NO и без inclusive_interfaces, охватывающего TUN-интерфейс, в resolvconf.conf); с local_unbound нужно отключить проверку DNSSEC в unbound, так как дополнительные запросы проверки не получают ответа через DNS-исходящее. Если системный DNS изменить не удается, Xray не запускается. При обычном завершении Xray настройка отменяется; если Xray был принудительно завершен (например, SIGKILL), выполните resolvectl revert <интерфейс> в Linux или resolvconf -d <интерфейс> во FreeBSD.

autoSystemWfpBlockLeak: [string]

Рекомендуется задать как минимум ["dns", "misconfigtun"], чтобы блокировать утечки DNS и трафик версии IP без маршрутов.

Этот параметр действует только в Windows и требует autoSystemRoutingTable, иначе Xray сообщает об ошибке и не запускается. По умолчанию он пуст, то есть фильтры не добавляются. Xray добавляет фильтры Windows Filtering Platform (WFP), с которыми трафик других программ может уходить только через TUN-интерфейс; каждый вид выбирается значением в списке:

"dns": означает "53", "853" (DNS over TLS и QUIC) и "windnsclient". Windows отправляет запросы DNS-серверам всех интерфейсов, каждому через его собственный интерфейс независимо от маршрутов, а другие программы обращаются к DNS-серверу в локальной сети (например, 192.168.1.1, выданному DHCP) по более точному маршруту, так что без этого такие серверы по-прежнему опрашивались бы мимо TUN-интерфейса.
"windnsclient": служба «DNS-клиент» (Dnscache), кроме разрешения имён в локальной сети (LLMNR, mDNS). В Windows 11, Windows Server 2022 и новее она может отправлять запросы по DNS over HTTPS или TLS на любой порт; более ранние версии обращаются только к порту 53, так что там это значение ничего не делает.
"tcp", "udp": этот протокол на все порты, а с /<порт> или /<от>-<до> (от 1 до 65535) — на некоторые, например "tcp/853" или "udp/10-20". Одни лишь порты означают оба протокола, например "53" или "10-20".
"icmp": ICMP и ICMPv6, например ping.
"misconfigtun": версия IP (IPv4 или IPv6), для которой в autoSystemRoutingTable нет маршрутов, так что её трафик шёл бы мимо TUN-интерфейса. Если IPv6 отключён через DisabledComponents, это значение охватывает IPv6 независимо от маршрутов, так как ошибки настройки IPv6 тогда только записываются в журнал, а до перезагрузки, которая применяет этот параметр, IPv6 продолжает работать.
"all": весь трафик в обоих направлениях. Доступ к локальной сети тогда пропадает, если не направить её тоже в TUN-интерфейс; так же перестают работать входящие соединения к другим программам, другие VPN и виртуальные машины, NAT которых работает как программа на хосте.
"allexceptlan": как "all", но трафик в локальную сеть и из неё остаётся разрешён, например для принтеров или трансляции на телевизор: частные адреса, локальные адреса канала, адреса групповой рассылки и широковещательный адрес (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 224.0.0.0/4, 255.255.255.255, fc00::/7, fe80::/10, ff00::/8), но не глобальные адреса IPv6. Он включает "dns", а остальные значения действуют и там. "all" имеет приоритет над ним.

CIDR перед значением ограничивает его своими адресами, CIDR IPv6 — в квадратных скобках, например "8.8.8.8/32:all", "1.1.1.0/24:53" или "[::/0]:all" (только IPv6). Он ограничивает и то, что значение означает или включает: так, "0.0.0.0/0:allexceptlan" оставляет DNS через IPv6 открытым.

Loopback, DHCP, DHCPv6 и обнаружение соседей IPv6 всегда остаются разрешены. Пока фильтры действуют, исходящие соединения самого Xray также обходят блокирующие правила брандмауэра Windows. Если добавить фильтры не удалось, Xray не запускается; они удаляются при завершении Xray, даже аварийном.

Чтобы удерживать DNS системы внутри TUN-интерфейса с помощью "all", "allexceptlan", "dns", "windnsclient" или любого значения, охватывающего порт 53 TCP или UDP, даже лишь для некоторых адресов, нужен dns, иначе Xray сообщает об ошибке и не запускается. Серверы из dns тогда должны входить в gateway или autoSystemRoutingTable либо быть адресами loopback, например 127.0.0.1, а DNS-серверы, к которым нужно обращаться напрямую, следует указывать в собственных настройках DNS Xray.

Фильтры мешают в некоторых случаях: с "dns" — локальный DNS-резолвер, который сам отправляет запросы через другой интерфейс, DNS другого VPN, виртуальные машины, NAT которых разрешает имена на хосте, или вход в captive portal; с "misconfigtun" — IPv4 или IPv6 в локальной сети, когда маршрутов этой версии в TUN-интерфейс нет.

Советы по использованию

Если autoSystemRoutingTable не настроен, маршруты для направления трафика в созданный TUN-интерфейс по-прежнему нужно добавлять вручную, иначе он останется просто сетевым интерфейсом. Для более тонкой маршрутизации систему тоже придётся настраивать вручную.

Даже с маршрутами системный DNS может утекать мимо TUN-интерфейса: в Windows задайте dns и как минимум ["dns"] в autoSystemWfpBlockLeak; в Linux и FreeBSD используйте autoSystemDnsToGateway; в macOS настройте системный DNS сами, например на сервер, маршрутизируемый в TUN-интерфейс.

Ответы на ping (ICMP Echo) формирует сам Xray, поэтому они не показывают, доступен ли адрес назначения.

Если вы хотите проксировать только один или несколько процессов, будет очень полезна маршрутизация по имени процесса в системе маршрутизации Xray.

WARNING

Остерегайтесь возможных петель трафика (traffic loops). После настройки маршрутизации запросы, отправляемые Xray, могут быть направлены обратно в Xray и образовать петлю. В первую очередь используйте autoOutboundsInterface, чтобы избежать этой проблемы. Если нужен ручной контроль, можно использовать interface в sockopt для привязки к реальному физическому сетевому интерфейсу. Команды ipconfig (Windows) и ip a (Linux) помогут найти имя нужного вам интерфейса. Или используйте sendThrough для исходящих соединений. Он доступен непосредственно в OutboundObject и не имеет такой глубокой вложенности, как sockOpt.interface. Здесь необходимо использовать IP-адрес сетевой карты, например 192.168.1.2 (как видите, его недостатком является отсутствие автоматической поддержки dual-stack, пожалуйста, выбирайте в соответствии с фактически используемым IP для исходящего трафика).