TrueNAS Unifi Controller — 특정 이더넷 인터페이스에 연결하기

TrueNAS SCALE의 Apps(Docker 기반)로 Unifi Controller를 올릴 때, "이 컨테이너를 특정 물리 이더넷 포트에만 붙이고 싶다"는 요구가 종종 생긴다. 결론부터 말하면 TrueNAS SCALE Apps에는 컨테이너를 물리 NIC에 직접 바인딩하는 옵션이 없다. 대신 **해당 이더넷에 할당된 IP 주소를 골라, 서비스 포트를 그 IP에만 발행(publish)**하는 방식으로 사실상 같은 효과를 낸다.

이 글은 Unifi Controller 설치 화면을 기준으로 UI 구조를 확인하고, 특정 인터페이스에 연결하기 위한 실제 설정 순서를 정리한 것이다.

핵심 개념: 포트를 "특정 IP에만" 발행한다

TrueNAS SCALE Apps는 내부적으로 Docker를 사용하지만, 관리 UI에서 컨테이너를 물리 포트에 매핑하는 항목을 노출하지 않는다. 그래서 접근 방식이 바뀐다.

• 원하는 이더넷 인터페이스에 IP 주소를 먼저 할당한다.
• 앱 설치 시 각 서비스 포트를 0.0.0.0(모든 인터페이스)이 아니라 그 IP에만 발행한다.

이렇게 하면 해당 서비스는 지정한 인터페이스의 IP를 통해서만 접근 가능해진다.

설치 화면에서 확인한 UI 구조

Unifi Controller 설치 화면을 열어 각 항목을 확인한 결과는 다음과 같다.

Network Configuration 섹션에는 WebUI/API Port, Inform Controller Port, Portal HTTPS/HTTP Port 등 여러 포트 항목이 있다. 각 포트마다 Host IPs 필드가 있고, Add를 누르면 호스트에 이미 구성된 IP 목록이 드롭다운으로 나타난다.

현재 시스템에서는 드롭다운에 다음 세 개만 보였다.

즉 목록에 원하는 인터페이스의 IP가 없다면, 그 인터페이스에 IP를 먼저 할당해야 선택지에 등장한다.

혼동하기 쉬운 두 항목도 짚어 둔다.

• Networks 필드: 툴팁을 확인하면 "The docker networks to join"이다. 물리 NIC가 아니라 Docker 내부 네트워크에 참여시키는 용도이므로 이 목적과는 무관하다. 비워 둔다.
• Host Network 체크박스: 호스트의 네트워크 스택 전체를 그대로 사용한다. 특정 인터페이스만 고르는 것과는 성격이 다르므로 체크하지 않는 것을 권장한다.

설정 순서

1. System > Network > Interfaces에서 사용하려는 이더넷 포트에 IP 주소를 할당한다.
2. Apps > Discover > Unifi Controller > Install로 진입한다.
3. Timezone 등 기본 설정을 입력한다.
4. Network Configuration에서 노출할 각 포트의 Host IPs → Add → 1번에서 할당한 IP를 선택한다. (기본값 0.0.0.0 대신)
5. Host Network 체크박스는 해제 상태로 두고, Networks 필드는 비워 둔다.
6. Storage / Resources Configuration 등 나머지 항목을 확인한다. (기본값 유지 가능)
7. 설정을 재확인한 뒤 Install을 클릭한다.

정리

TrueNAS SCALE Apps에서 "특정 이더넷 인터페이스에 연결"은 물리 포트 바인딩이 아니라 IP 기반 포트 발행으로 풀어야 한다. 순서만 지키면 어렵지 않다 — 인터페이스에 IP를 먼저 할당하고, 각 포트의 Host IPs를 그 IP로 지정하면 된다. Host Network와 Networks 필드는 이 목적에 맞지 않으니 건드리지 않는 편이 깔끔하다.

주의

TrueNAS SCALE version 25.10.4 기준이다.