NetBox란 무엇인가?
NetBox는 데이터센터 내 물리적 및 논리적 자산을 통합 관리하기 위한 오픈소스 기반 DCIM (Data Center Infrastructure Management) 및 IPAM (IP Address Management) 솔루션이다. Python의 Django 프레임워크로 구축되었으며, 정형화된 메타데이터 관리와 API 기반 자동화를 통해 네트워크 인프라스트럭처의 가시성과 일관성을 제공한다.
핵심 기능 요약
- DCIM 기능: 랙(Rack), 장비(Device), 포트(Interface), 전원(PDU), 케이블 등 물리 인프라 요소를 계층적으로 모델링
- IPAM 기능: IP 주소 및 서브넷 할당, VLAN/VRF 구조화, 충돌 방지 로직 및 자동화된 주소 할당 기능 포함
- 시각화: 물리적 연결성과 논리적 종속성에 대한 시각적 표현 제공
- 자동화 인터페이스: RESTful API, Webhook, GitOps 기반 변경 이력 연동 지원
- 확장성: 플러그인 프레임워크와 사용자 정의 필드를 통한 커스터마이징
시스템 환경 및 컴포넌트 구성
사전 조건
- 운영체제: CentOS 7.9 (Docker 및 Compose 지원 가능)
- 서버 구성: 단일 NetBox 전용 노드 권장 (자원 충돌 방지를 위해 다른 서비스와의 병행 사용 지양)
- 사용자 규모: 중소규모 팀(1~10명) 사용에 최적화
Docker Compose 내 주요 컨테이너 설명
| 컨테이너 이름 | 역할 설명 |
|---|---|
netbox |
Django 앱 서버 (API 및 UI 제공) |
netbox-worker |
Celery 기반 비동기 작업 큐 처리 |
netbox-housekeeping |
주기적 정리 작업 (세션, 로그 등) |
netbox-postgres |
PostgreSQL 데이터베이스 엔진 |
netbox-redis |
캐시 및 비동기 메시지 브로커 |
netbox-nginx |
리버스 프록시 및 정적 콘텐츠 서빙 (옵션) |
설치 및 배포 절차
1단계: Docker 및 Compose 설치
yum install -y yum-utils device-mapper-persistent-data lvm2
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
yum install -y docker-ce
systemctl enable --now docker
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
2단계: NetBox 컨테이너 환경 구성
git clone https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
cp env.example .env
vi netbox.env # 환경 변수 파일 열기 (TIME_ZONE, SUPERUSER, HTTP_PORT 등 설정)
# 예시 설정 항목:
SKIP_SUPERUSER=false
TIME_ZONE=Asia/Seoul
SUPERUSER_NAME=admin
SUPERUSER_PASSWORD=admin
SUPERUSER_EMAIL=admin@example.com
ALLOWED_HOSTS=*
HTTP_PORT=8000
SECRET_KEY=<복잡한_랜덤_문자열>
# 설정 후 변경 사항 반영:
docker compose down && docker compose up -d
또는 .env 파일 대신 아래의 개별 환경파일을 사용:
/root/netbox-docker/
├── docker-compose.yml
├── netbox.env # NetBox 메인 설정
├── postgres.env # PostgreSQL 환경 변수
├── redis.env # Redis 환경 변수
└── redis-cache.env # Redis Cache 설정
3단계: 포트 매핑 설정 추가 (중요)
docker-compose.override.yml 파일을 생성하거나 다음과 같이 구성:
- 아래 가이드대로 만들어도 되지만 docker-compose.override.yml.example를 복사하여 사용해도 됨.
- cp docker-compose.override.yml.example docker-compose.override.yml
version: '3.4'
services:
netbox:
ports:
- "8000:8080"
이 설정이 없다면 웹 UI는 외부에서 접속할 수 없습니다.
4단계: 컨테이너 이미지 배포 및 실행
docker compose down # 재시작 시 필수
docker compose up -d
5단계: 서비스 접근 테스트
- 접속 URL:
http://<서버 IP>:8000 - 기본 로그인: admin / admin (최초 로그인 후 비밀번호 변경 필수)
환경 변수 주요 항목 정리
| 변수명 | 설명 |
|---|---|
TIME_ZONE |
NetBox 서버의 시간대 (예: Asia/Seoul) |
SUPERUSER_NAME |
초기 관리자 계정 ID |
SUPERUSER_PASSWORD |
초기 관리자 비밀번호 |
SUPERUSER_EMAIL |
초기 관리자 이메일 |
HTTP_PORT |
컨테이너 외부에서 접근할 포트 |
SECRET_KEY |
Django의 보안 키. 복잡하고 유일한 문자열 사용 필수 |
ALLOWED_HOSTS |
허용할 호스트 이름 또는 IP 목록 (쉼표로 구분) |
주요 기능 정리
- 장비(Device), 랙(Rack), 포트, 케이블, 전원, 위치 등의 자산 문서화
- IP 주소, 서브넷, VLAN, VRF 관리
- 시각화 기반 연결 추적
- 웹 UI 및 REST API 지원
- Webhook, GitOps, SSO, LDAP 연동 가능 (설정 필요)
운영 및 유지보수
백업
docker compose exec netbox-postgres pg_dump netbox > netbox_backup.sql
업그레이드
docker compose down
git pull
docker compose pull
docker compose up -d
관리자 계정 비밀번호 변경
docker compose exec netbox bash
python3 manage.py changepassword admin
오류 해결 사례
문제: 웹 접속이 되지 않음
- 원인:
docker-compose.override.yml에서 포트 매핑 누락 - 해결: override.yml 파일에
8000:8080추가 후docker compose up -d
문제: 컨테이너 unhealthy
- 원인:
.env또는netbox.env에서SECRET_KEY,ALLOWED_HOSTS등이 누락되었거나 잘못됨 - 해결: 해당 항목 보완 후 재시작
결론
NetBox는 네트워크 및 서버 자산을 문서화하고 구조화할 수 있는 강력한 인프라 관리 툴이다.
Docker 기반의 손쉬운 설치와 웹 UI, REST API를 통해 중소규모 이상의 팀에서도 유연하게 활용 가능하다.
구축 시에는 환경변수 구성, 포트 매핑, 컨테이너 상태 점검이 핵심이며, 이를 통해 안정적인 운영과 확장 가능한 구조를 구현할 수 있다.
