hostAddressLoopback в WSL: доступ по IPv4 Windows-хоста

Что именно меняет hostAddressLoopback

В обычной проверке легко перепутать три разные вещи: loopback 127.0.0.1, LAN-адрес Windows и адрес, на котором фактически слушает приложение. По документации Microsoft, hostAddressLoopback относится к mirrored networking и разрешает использовать дополнительные локальные IPv4, назначенные Windows-хосту, для связи host↔WSL. Адрес 127.0.0.1 в mirrored mode доступен независимо от этой опции. Поэтому симптом для этой настройки очень конкретный: localhost работает или не является целью, а приложению требуется обращаться по IPv4 интерфейса Windows, например 192.168.x.x. Если проблема возникает только при доступе с другого компьютера сети, это уже не тот же самый сценарий: там нужно отдельно проверять bind сервиса, профиль сети и firewall. Не стоит включать экспериментальный флаг «на всякий случай» — сначала зафиксируйте адрес и направление соединения.

Совет: Сначала запишите, кто клиент и кто сервер: Windows→WSL или WSL→Windows, а также какой конкретно IPv4 используется. Это сразу отсекает половину ложных диагнозов.

Какие условия должны быть выполнены

Параметр применяется только к WSL 2 в mirrored networking. Microsoft помечает hostAddressLoopback как экспериментальную настройку и указывает требование Windows 11 версии 22H2 или новее. Глобальная конфигурация WSL хранится в `%UserProfile%\.wslconfig`; это не `/etc/wsl.conf` внутри конкретного дистрибутива. В секции `[wsl2]` должен быть задан `networkingMode=mirrored`, а `hostAddressLoopback=true` помещается в `[experimental]`. После изменения `.wslconfig` уже работающая WSL-VM не обязана мгновенно перечитать файл. Самый воспроизводимый способ — сохранить файл, выполнить `wsl --shutdown`, затем снова запустить нужный дистрибутив. Учтите, что `wsl --shutdown` завершает все работающие дистрибутивы WSL 2, поэтому перед командой остановите незавершённые процессы.

Предупреждение: `wsl --shutdown` выключает всю WSL 2 VM, а не только окно текущего терминала. Не запускайте команду во время длительной сборки, копирования или вычислений внутри WSL.

Что проверить до изменения

• Версия WSL. дистрибутив работает как WSL 2. глобальные .wslconfig-параметры относятся к WSL 2
• Режим сети. networkingMode=mirrored. hostAddressLoopback в других режимах не применяется
• Целевой адрес. дополнительный IPv4 Windows. 127.0.0.1 не требует этого флага
• Слушающий сокет. сервис принимает нужный адрес/порт. флаг не меняет bind приложения
• Firewall. правило допускает трафик. mirrored traffic может фильтроваться Windows/Hyper-V Firewall

Важно: Тестируйте один заранее выбранный адрес и порт до и после изменения. Если одновременно поменять bind, firewall и `.wslconfig`, станет непонятно, что именно помогло.

Как выбрать правильный IPv4 для теста

На Windows получите адрес нужного интерфейса через `ipconfig` или PowerShell `Get-NetIPAddress -AddressFamily IPv4`. Не используйте случайный адрес из списка: выберите тот интерфейс, через который должен идти сценарий — Ethernet, Wi‑Fi, VPN или другой локальный адаптер. Затем определите порт сервиса и проверьте, что он действительно слушает его. Для Windows-сервиса это можно сделать `Get-NetTCPConnection -State Listen`; для сервиса в Linux — `ss -lntp`. Если процесс привязан только к `127.0.0.1`, попытка прийти на LAN-IP может не сработать независимо от hostAddressLoopback. Для HTTP удобно сравнивать один и тот же URL через `curl`, меняя только адрес. Такой контрольный тест отделяет маршрутизацию WSL от поведения самого приложения.

Как включить hostAddressLoopback

1. 1: Закройте или сохраните работу во всех дистрибутивах WSL, где есть важные фоновые процессы.
2. 2: Откройте `%UserProfile%\.wslconfig` в Windows. Если файла нет, создайте его как обычный текстовый файл без дополнительного расширения.
3. 3: В секции `[wsl2]` задайте `networkingMode=mirrored`. В отдельной секции `[experimental]` задайте `hostAddressLoopback=true`.
4. 4: Сохраните файл и выполните в PowerShell `wsl --shutdown`, затем снова запустите дистрибутив.
5. 5: Из WSL обратитесь к заранее выбранному IPv4 Windows-хоста и порту, например `curl http://192.168.1.10:8080/`. Для обратного направления выполните аналогичный тест с Windows.
6. 6: Если соединения нет, не добавляйте новые параметры: сначала проверьте bind сервиса и firewall теми же адресом и портом.

Почему параметр включён, а соединения всё равно нет

Первая частая причина — приложение слушает не тот интерфейс. Сервер, связанный только с loopback, не обязан принимать запрос на адрес физического адаптера. Вторая причина — фильтрация. В mirrored mode Windows Firewall и правила, относящиеся к Hyper‑V, могут участвовать в обработке трафика; hostAddressLoopback не является командой «разрешить всё». Третья причина — выбран не тот IPv4, особенно при VPN и нескольких адаптерах. Четвёртая — конфигурация не была перечитана после изменения. Проверьте эти пункты по одному. Полезный приём: временно запустить простой тестовый HTTP-сервис на заранее известном интерфейсе и порту, а затем сравнить `127.0.0.1` и нужный IPv4. Так видно, проблема в WSL-маршруте или в конкретном приложении.

Как отличить hostAddressLoopback от внешнего доступа из LAN

hostAddressLoopback решает локальную связь между хостом и WSL через адрес, назначенный хосту. Он не означает, что сервис автоматически становится доступен с телефона, другого компьютера или из Интернета. Для внешнего клиента важны адрес, на котором слушает сервер, правила Windows Firewall, сетевой профиль, маршрутизация и возможные ограничения VPN. Если локальный запрос Windows↔WSL по нужному IPv4 проходит, а запрос с соседнего устройства нет, настройка hostAddressLoopback уже не является первым подозреваемым. Не открывайте широкий входящий доступ ради диагностики. Создавайте правило только для нужного протокола, порта и сети, а после теста удаляйте временные разрешения.

Чек-лист воспроизводимого результата

• дистрибутив подтверждён как WSL 2
• в `.wslconfig` включён `networkingMode=mirrored`
• `hostAddressLoopback=true` находится в `[experimental]`
• после правки выполнен полный перезапуск WSL
• тестируется конкретный дополнительный IPv4 Windows, а не 127.0.0.1
• сервис слушает ожидаемый интерфейс и порт
• firewall проверен отдельно
• до и после изменения используется один и тот же клиентский тест

Когда лучше удалить настройку

Если приложению достаточно `localhost`, оставлять hostAddressLoopback ради «стабильности сети» смысла нет: он предназначен не для этого. Также уберите параметр, если A/B-тест показал одинаковый результат при true и false. Чем меньше экспериментальных ключей в `.wslconfig`, тем легче разбирать проблему после обновлений WSL или Windows. Сохраните рабочий минимальный конфиг и кратко подпишите для себя, зачем нужен каждый нестандартный параметр. При повторной диагностике начинайте с базовой схемы: версия WSL, режим сети, адрес сервера, bind, порт, firewall — и только затем возвращайтесь к hostAddressLoopback. Такой порядок позволяет не маскировать настоящую причину сетевого сбоя набором несвязанных твиков.

Что учитывать

Первая частая причина — приложение слушает не тот интерфейс. Сервер, связанный только с loopback, не обязан принимать запрос на адрес физического адаптера. Вторая причина — фильтрация. В mirrored mode Windows Firewall и правила, относящиеся к Hyper‑V, могут участвовать в обработке трафика; hostAddressLoopback не является командой «разрешить всё». Третья причина — выбран не тот IPv4, особенно при VPN и нескольких адаптерах. Четвёртая — конфигурация не была перечитана после изменения. Проверьте…

Источники и проверка

Фактическая часть сверена по первичным источникам (в т.ч. Advanced settings configuration in WSL). Пример и формулировки — редакция N1RO на 2026-09-20.

• Advanced settings configuration in WSL
• Accessing network applications with WSL