ignoredPorts в WSL: занятый Windows порт в mirrored mode

Когда ignoredPorts действительно нужен

Начните с текста ошибки и владельца сокета. Настройка имеет смысл, когда Windows уже использует номер порта, а Linux-приложение внутри WSL должно слушать тот же номер для трафика, который остаётся в Linux. Microsoft описывает именно такую семантику: в mirrored networking перечисленные порты разрешается bind'ить Linux-приложениям, несмотря на использование этих номеров Windows. Это отличается от ситуации, когда порт занят другим Linux-процессом: ignoredPorts не позволит двум обычным Linux-сокетам конкурировать за один endpoint. Также это не лечит `connection refused`, если процесс вообще не запущен. Сначала подтвердите конфликт, иначе параметр усложнит конфиг и не изменит симптом.

Совет: Перед правкой запишите PID/процесс, который занимает порт в Windows, и вывод `ss` в WSL. Так можно доказать, что решается именно межсистемный конфликт номера.

Как найти, кто держит порт

Для TCP в Windows удобно использовать `Get-NetTCPConnection -LocalPort 3000` и затем сопоставить `OwningProcess` с процессом. Для UDP есть `Get-NetUDPEndpoint -LocalPort 3000`. В WSL проверьте `ss -lntp` для TCP и `ss -lnup` для UDP; при недостатке прав имя процесса может быть скрыто, тогда повторите с `sudo`. Важно различать «порт уже слушается» и «клиентское соединение использует этот номер временно». Для ignoredPorts интерес представляет именно привязка слушающего Linux-приложения. Если номер свободен в Windows, сначала ищите обычную Linux-причину: другой процесс, неверные права, некорректный адрес bind или настройку самого приложения.

Что ignoredPorts делает и чего не делает

• Windows слушает 3000, Linux тоже должен bind 3000. может разрешить Linux bind в mirrored mode
• Другой Linux-процесс уже слушает 3000. не устраняет Linux↔Linux конфликт
• Нужно открыть порт для устройства в LAN. не заменяет bind и firewall
• Нужен port forwarding Windows→WSL. это не механизм перенаправления
• WSL работает в NAT. параметр для mirrored mode не применим

Важно: Не путайте успешный `bind()` с доступностью сервиса. После запуска проверяйте отдельно Linux-клиент, Windows-клиент и, если нужно, внешний клиент.

Как записать ignoredPorts в `.wslconfig`

Глобальный файл находится в `%UserProfile%\.wslconfig`. В `[wsl2]` должен быть `networkingMode=mirrored`; список ignoredPorts относится к `[experimental]`. Значение — строка с номерами через запятую, например `ignoredPorts=3000,9000,9090`. Не добавляйте диапазоны, описания или префиксы `tcp:`/`udp:`, если документация этого не предусматривает. Чем короче список, тем понятнее поведение. Если конфликтует один сервис, начните с одного порта. После сохранения выполните `wsl --shutdown`, потому что правка глобальной конфигурации должна примениться при новом запуске WSL. Если у вас одновременно меняется несколько сетевых параметров, тестируйте их по одному — иначе причинность потеряется.

Предупреждение: Не копируйте длинный список портов из чужого конфига. Исключение должно соответствовать реальной задаче, которую вы можете воспроизвести до правки.

Как провести проверку на одном порту

1. 1: В Windows подтвердите, что нужный номер действительно занят слушающим процессом.
2. 2: В WSL убедитесь, что этот же номер не занят другим Linux-процессом.
3. 3: Сохраните исходную ошибку запуска Linux-приложения — она будет контрольной точкой.
4. 4: В `.wslconfig` включите mirrored networking и добавьте конкретный номер в `ignoredPorts`.
5. 5: Выполните `wsl --shutdown`, запустите дистрибутив и повторите ту же команду запуска приложения.
6. 6: Проверьте `ss -lntp` или `ss -lnup`: появился ли ожидаемый Linux-сокет.
7. 7: Отдельно протестируйте клиентов из Linux и Windows; доступность не следует автоматически из факта успешного bind.

Почему приложение запустилось, но Windows его не видит

Такой результат не противоречит назначению ignoredPorts. Документация описывает возможность слушать порт для трафика исключительно внутри Linux, несмотря на использование этого номера Windows. То есть основная проверка параметра — исчез ли межсистемный конфликт bind и появился ли Linux-сокет. Если задача требует именно Windows→Linux на том же номере, нужно разбирать маршрутизацию mirrored mode и то, какой процесс Windows уже владеет номером. Нельзя ожидать, что два разных сервера одновременно будут однозначно получать один входящий поток только потому, что им разрешено использовать одинаковое число. Для внешнего доступа также остаются bind-адрес приложения и firewall.

Как диагностировать TCP, UDP и wildcard-bind

Порт — не единственный параметр сокета. Отдельно учитываются протокол и локальный адрес. TCP 5353 и UDP 5353 — разные сокеты; привязка к `127.0.0.1:3000`, `0.0.0.0:3000` и конкретному интерфейсу тоже имеет разные последствия. Поэтому при диагностике не ограничивайтесь командой, которая показывает только номер. Сравните протокол, адрес и процесс. Если приложение умеет выбирать interface/listen address, зафиксируйте его явно на время теста. Это особенно важно для dev-серверов, DNS-инструментов и контейнеров, где один процесс может создавать несколько listener'ов. ignoredPorts отвечает только за описанный Microsoft конфликт Windows/WSL и не делает все комбинации адресов эквивалентными.

Что проверить перед тем, как оставить исключение

• WSL 2 работает в `networkingMode=mirrored`
• конфликт подтверждён на стороне Windows
• в WSL нет второго процесса-владельца
• в список внесены только необходимые номера
• после изменения выполнен `wsl --shutdown`
• Linux-приложение действительно создало listener
• доступность из Windows проверена отдельно от bind
• firewall не объявлен причиной без отдельного теста

Когда лучше сменить порт приложения

ignoredPorts полезен, когда одинаковый номер является частью реального локального сценария, например его ожидает Linux-стек или контейнер. Но если номер выбран произвольно dev-сервером, смена порта часто проще и прозрачнее. Конфигурационное исключение создаёт дополнительную зависимость от mirrored networking и экспериментального поведения WSL; другой разработчик или будущая машина могут не иметь такого же файла `.wslconfig`. Для командного проекта лучше документировать причину каждого исключения рядом с настройкой запуска приложения. После обновления WSL повторите короткий A/B-тест: удалите порт из ignoredPorts, перезапустите WSL и убедитесь, что исключение всё ещё необходимо. Если обычный bind уже работает, лишний параметр можно убрать.

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

Такой результат не противоречит назначению ignoredPorts. Документация описывает возможность слушать порт для трафика исключительно внутри Linux, несмотря на использование этого номера Windows. То есть основная проверка параметра — исчез ли межсистемный конфликт bind и появился ли Linux-сокет. Если задача требует именно Windows→Linux на том же номере, нужно разбирать маршрутизацию mirrored mode и то, какой процесс Windows уже владеет номером. Нельзя ожидать, что два разных сервера одновременно…

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

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

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