Triển khai NetBox IPAM + DCIM
Quản lý không gian địa chỉ IP (IPAM) và hạ tầng mạng (DCIM).
Bối cảnh & Lý do triển khai
Khi hạ tầng mở rộng, quản lý IP bằng Excel/Notion nhanh chóng trở nên lộn xộn: IP conflict, không biết IP nào đang dùng, không có lịch sử thay đổi. NetBox là "source of truth" cho network — tất cả IP, VLAN, rack, cable đều được document tập trung và là nguồn dữ liệu cho automation tools (Ansible/Terraform).
| Mục | Nội dung |
|---|---|
| Ứng dụng trong DN | IP Address Management, VLAN tracking, rack documentation, cable management, network topology |
| Tác dụng chính | REST API cho Ansible dynamic inventory, IPAM cho 5 VLAN + 30 VM, device/rack visualization |
| Nếu không triển khai | Quản lý IP thủ công bằng Excel — dễ conflict, không scalable, không có API cho automation |
| Các service phụ thuộc vào đây | Ansible/Terraform đọc inventory từ NetBox API; Grafana có thể link dashboard với device |
Danh sách máy chủ & IP liên quan
Bảng dưới liệt kê các máy chủ mà bài này tạo hoặc kết nối tới. Địa chỉ, VMID, VLAN và node lấy từ bảng quy hoạch chung của lab, dùng thống nhất cho cả bộ bài lab.
| Máy chủ | IP | VLAN · Node | Vai trò trong bài này |
|---|---|---|---|
| netbox (NetBox IPAM) · VM245 | 10.11.45.45 | 45 (MGMT) · node2 | Máy chủ của bài — Ubuntu Server 24.04 LTS chạy NetBox 4.7 bằng netbox-docker (Docker Compose); web và REST API qua HTTP cổng 8080. |
| node2 (Proxmox VE) | 10.11.45.211 | 45 (MGMT) · cluster HOATRANHUB | Node Proxmox chứa VM245; tạo VM tại đây. |
| pihole (Pi-hole DNS) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | DNS của VM (kèm 8.8.8.8 dự phòng) và bản ghi netbox.hoatranlabs.local về 10.11.45.45 trong Local DNS (bài 12). |
| authentik (Authentik SSO) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | Nhà cung cấp OIDC cho NetBox: provider netbox-oidc, endpoint cổng 9443, cấu hình trong configuration.py (bài 14). |
| step-ca (step-CA PKI) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Cấp root CA (roots.pem) để container NetBox tin cert HTTPS cổng 9443 của Authentik qua REQUESTS_CA_BUNDLE (mục 3.3, bài 13). |
| FortiGate (firewall) | 10.100.100.1 | Quản trị 10.100.100.0/24 · thiết bị mạng | Policy Allow-NetBox-Clients cho VLAN 25, 65, 75 truy cập TCP 8080 tới NetBox; VLAN_MGMT cùng VLAN với NetBox nên không cần policy (mục 5.2). |
| prometheus (Prometheus + Alertmanager) · VM235 | 10.11.45.35 | 45 (MGMT) · node2 | Alertmanager cổng 9093 nhận webhook của NetBox khi IP được tạo, sửa hoặc xóa (bài 15). |
| pbs01 (PBS Primary) · VM101 | 10.11.45.17 | 45 (MGMT) · node4 | Sao lưu snapshot VM245, mục cuối của checklist (bài 04). |
Gateway của mỗi VLAN là địa chỉ .1. Tên DNS nội bộ do Pi-hole phân giải (bài 12). Tên in đậm là hostname; FQDN = hostname + .hoatranlabs.local. Script import_lab_ips.py (Phần 4.2) còn nhập IP của node1, node3, node4, vaultwarden, openvas, mailu, mediamtx, ups01 và ops01 vào NetBox nhưng bài không cấu hình gì trên các máy đó.
Tổng Quan
NetBox là nền tảng IPAM (IP Address Management) và DCIM (Data Center Infrastructure Management) mã nguồn mở do NetDev Community phát triển. Trong lab HOATRANLABS, NetBox đóng vai trò là source of truth cho toàn bộ hạ tầng mạng: quản lý IP allocation, VLAN, rack, kết nối cable, và inventory thiết bị.
Lý do cần NetBox:
- Hiện tại các IP trong lab được ghi chú thủ công → dễ trùng lặp, khó tracking
- Khi hạ tầng mở rộng (VM mới, VLAN mới) cần có tool quản lý tập trung
- Tích hợp Authentik SSO → đăng nhập một lần cho toàn lab
- API REST đầy đủ → tích hợp với Ansible/Terraform automation sau này
Thông tin VM:
| Thuộc tính | Giá trị |
|---|---|
| VMID | 245 |
| Hostname | netbox |
| Node | node2 (10.11.45.211) |
| IP | 10.11.45.45/24 |
| Gateway | 10.11.45.1 |
| DNS | 10.11.45.53 (Pi-hole) |
| VLAN | VLAN_MGMT (tag 45) |
| vCPU | 2 |
| RAM | 4 GB |
| Disk | 30 GB (Ceph) |
| OS | Ubuntu Server 24.04.5 LTS (noble) |
| Port | 8080 (HTTP) |
Phiên bản phần mềm sử dụng (đã xác minh 2026-10-15):
| Thành phần | Phiên bản | Ghi chú |
|---|---|---|
| Ubuntu Server | 24.04.5 LTS (noble) | ISO ubuntu-24.04.5-live-server-amd64.iso; hỗ trợ chuẩn tới 04/2029; Python hệ thống 3.12 (PEP 668) |
| Docker Engine | 29.9.1 (docker-ce 5:29.9.1-1~ubuntu.24.04~noble) | Repo chính thức download.docker.com/linux/ubuntu noble stable |
| Docker Compose plugin / Buildx | 5.6.0 / 0.38.0 | Lệnh docker compose |
| netbox-docker | 5.1.1 (nhánh release) | https://github.com/netbox-community/netbox-docker; nhánh release trôi theo thời gian |
| NetBox | 4.7.x (image netboxcommunity/netbox:v4.7-5.1.1; bản mới nhất 4.7.3 ngày 2026-10-13) | Chạy trong container; NetBox 4.7 yêu cầu PostgreSQL 15+, image dùng PostgreSQL 18 nên không phụ thuộc PostgreSQL 16 của Ubuntu |
| PostgreSQL / Valkey | 18-alpine / 9.1-alpine | Container trong compose của netbox-docker (không cài trên host) |
| Python trên host | 3.12 + gói python3-requests | Chỉ để chạy script nhập dữ liệu mục 4.2; NetBox có Python riêng trong image |
Tạo VM245 trên Proxmox
Tạo VM trên Proxmox (node2) · Cài đặt Ubuntu Server 24.04 LTS · Cập nhật hệ thống
1.1 Tạo VM trên Proxmox (node2)
SSH vào node2 (10.11.45.211) rồi chạy:
Cách 1: Web UI Proxmox (GUI)
- VM ID:
245 - Name:
netbox - Bỏ tick Start after created
- Storage:
local(hoặc nơi chứa ISO) - ISO Image:
ubuntu-24.04.5-live-server-amd64.iso - Guest OS Type:
Linux, Version:6.x - 2.6 Kernel
- Machine:
q35 - SCSI Controller:
VirtIO SCSI single - BIOS:
SeaBIOS - Qemu Agent: ☑
- Bus/Device:
SCSI 0, Storage:vm-ceph - Disk size:
30 GiB, Cache:Write back, Discard: ☑
- Sockets:
1, Cores:2, Type:x86-64-v2-AES
- Memory (MiB):
4096
- Bridge:
vmbr0, VLAN Tag:45, Model:VirtIO (paravirtualized), Firewall: ☐
Cách 2: CLI (qm create)
qm create 245 --name netbox \
--memory 4096 \
--cores 2 \
--net0 virtio,bridge=vmbr0,tag=45 \
--scsi0 vm-ceph:30 \
--scsihw virtio-scsi-pci \
--ide2 local:iso/ubuntu-24.04.5-live-server-amd64.iso,media=cdrom \
--boot "order=ide2;scsi0" \
--ostype l26 \
--agent enabled=1 \
--onboot 1
1.2 Cài đặt Ubuntu Server 24.04 LTS
Khởi động VM và cài Ubuntu Server 24.04 LTS (ISO ubuntu-24.04.5-live-server-amd64.iso, bản point mới nhất của dòng 24.04 trên releases.ubuntu.com, kiểm 2026-10-15; hỗ trợ chuẩn tới 04/2029) qua console. Các tùy chọn quan trọng:
- Hostname:
netbox - Username:
sysadmin(hoặc theo chuẩn lab) - IP tĩnh:
10.11.45.45/24, gateway10.11.45.1, DNS10.11.45.53
8.8.8.8 trong lúc cài. Sau khi Pi-hole lên rồi mới đổi về 10.11.45.53.
Cấu hình netplan sau khi cài xong. Tên card mạng trên VM q35 thường là ens18 hoặc enp6s18: kiểm bằng ip -br link rồi đặt đúng tên vào ethernets:. Xem file netplan có sẵn bằng ls /etc/netplan/; trên Ubuntu 24.04 cloud-init thường ghi /etc/netplan/50-cloud-init.yaml (bản cài cũ dùng 00-installer-config.yaml), sửa trực tiếp file đang có. Nếu muốn cloud-init không ghi đè cấu hình mạng ở lần khởi động sau, tạo /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg với nội dung network: {config: disabled}.
# /etc/netplan/50-cloud-init.yaml (hoặc file netplan hiện có)
network:
version: 2
ethernets:
ens18:
addresses:
- 10.11.45.45/24
routes:
- to: default
via: 10.11.45.1
nameservers:
addresses:
- 10.11.45.53
- 8.8.8.8
search:
- hoatranlabs.local
# netplan cảnh báo nếu file cấu hình cho phép user thường đọc ("too open"): giới hạn quyền trước khi áp dụng
chmod 600 /etc/netplan/*.yaml
netplan apply
1.3 Cập nhật hệ thống
Chạy bằng quyền root (sudo -i). Ubuntu 24.04 dùng Python 3.12 theo PEP 668 (môi trường "externally managed"): pip3 install ngoài virtualenv bị chặn, nên thư viện requests cho script ở mục 4.2 cài bằng gói apt python3-requests. Bản thân NetBox chạy trong container (có Python riêng), không dùng Python của VM.
# (Ubuntu 24.04: needrestart có thể hiện hộp thoại chọn dịch vụ cần khởi động lại; đặt biến này để tự xử lý)
export NEEDRESTART_MODE=a
apt update && apt upgrade -y
apt install -y ca-certificates curl git python3 python3-requests
# Gỡ gói Docker không chính thức nếu có (docker.io, docker-compose-v2, podman-docker... của Ubuntu)
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
apt-get remove -y "$pkg" 2>/dev/null || true
done
# Cài Docker CE + Compose plugin từ repo chính thức của Docker (suite noble, deb822 + Signed-By, không dùng apt-key)
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
tee /etc/apt/sources.list.d/docker.sources > /dev/null << EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
systemctl enable --now docker
usermod -aG docker sysadmin
# Xác nhận (kiểm 2026-10-15 trên repo noble: docker-ce 29.9.1, Compose plugin 5.6.0, Buildx 0.38.0)
docker --version && docker compose version
Suites: được shell thay bằng noble nhờ heredoc không đặt nháy (<< EOF); mở /etc/apt/sources.list.d/docker.sources kiểm tra lại trước khi apt update. usermod -aG docker sysadmin chỉ có hiệu lực sau khi sysadmin đăng xuất và đăng nhập lại. Docker chỉ hỗ trợ iptables-nft/iptables-legacy, và cổng container đã publish (8080) có thể đi vòng qua luật ufw, nên lọc truy cập ở FortiGate (mục 5.2) thay vì chỉ dựa vào ufw.
Cài Đặt NetBox via Docker Compose
Clone repo và chuẩn bị · Tạo file cấu hình môi trường · Tạo docker-compose override để expose port 8080
NetBox community cung cấp repo Docker Compose chính thức tại netbox-community/netbox-docker.
2.1 Clone repo và chuẩn bị
git clone -b release https://github.com/netbox-community/netbox-docker.git /opt/netbox
cd /opt/netbox
2.2 Tạo file cấu hình môi trường
# Tạo SECRET_KEY ngẫu nhiên
SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")
echo "SECRET_KEY generated: $SECRET_KEY"
# Tạo pepper cho API token v2 (NetBox >= 4.5 bắt buộc có; bản cũ hơn bỏ qua biến này)
API_TOKEN_PEPPER=$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")
cat > /opt/netbox/env/netbox.env << EOF
SUPERUSER_NAME=admin
[email protected]
SUPERUSER_PASSWORD=Admin@NetBox2024
ALLOWED_HOSTS=netbox.hoatranlabs.local 10.11.45.45 localhost
SECRET_KEY=${SECRET_KEY}
API_TOKEN_PEPPER_1=${API_TOKEN_PEPPER}
DB_NAME=netbox
DB_USER=netbox
DB_PASSWORD=NetBox@DB2024
DB_HOST=postgres
REDIS_HOST=redis
REDIS_PASSWORD=NetBox@Redis2024
REDIS_CACHE_HOST=redis-cache
REDIS_CACHE_PASSWORD=NetBox@RCache2024
EOF
cat > /opt/netbox/env/postgres.env << EOF
POSTGRES_DB=netbox
POSTGRES_USER=netbox
POSTGRES_PASSWORD=NetBox@DB2024
EOF
cat > /opt/netbox/env/redis.env << EOF
REDIS_PASSWORD=NetBox@Redis2024
EOF
cat > /opt/netbox/env/redis-cache.env << EOF
REDIS_PASSWORD=NetBox@RCache2024
EOF
2.3 Tạo docker-compose override để expose port 8080
# /opt/netbox/docker-compose.override.yml
# (không khai báo `version:`: Docker Compose v2 trở lên coi khóa này là lỗi thời và chỉ cảnh báo)
services:
netbox:
ports:
- "8080:8080"
environment:
- ALLOWED_HOSTS=netbox.hoatranlabs.local 10.11.45.45 localhost
2.4 Khởi động NetBox
cd /opt/netbox
docker compose pull
docker compose up -d
# Theo dõi quá trình khởi tạo (lần đầu mất 3-5 phút để migrate DB)
docker compose logs -f netbox | grep -E "(startup|error|migration)"
2.5 Kiểm tra containers đang chạy
docker compose ps
Kết quả mong đợi — tất cả container phải ở trạng thái running:
NAME IMAGE STATUS
netbox-netbox-1 netboxcommunity/netbox:v4.7-5.1.1 running (healthy)
netbox-netbox-worker-1 netboxcommunity/netbox:v4.7-5.1.1 running (healthy)
netbox-postgres-1 postgres:18-alpine running (healthy)
netbox-redis-1 valkey/valkey:9.1-alpine running (healthy)
netbox-redis-cache-1 valkey/valkey:9.1-alpine running (healthy)
(Tag trong ví dụ lấy từ docker-compose.yml nhánh release của netbox-docker 5.1.1 ngày 2026-10-15; nhánh này thay đổi theo thời gian nên tag thực tế trên máy của bạn có thể khác. Cần kiểm lại trên máy thật.)
2.6 Kiểm tra truy cập
curl -s http://10.11.45.45:8080 | grep -o "<title>[^<]*"
# Kết quả: <title>Home | NetBox
Truy cập qua browser: http://10.11.45.45:8080
Đăng nhập: admin / Admin@NetBox2024
Tích Hợp Authentik SSO
Tạo OAuth2 Provider trong Authentik (VM234 – 10.11.25.40) · Cấu hình NetBox để dùng OIDC · Cho container NetBox tin root CA step-CA
3.1 Tạo OAuth2 Provider trong Authentik (VM234 – 10.11.25.40)
Đăng nhập Authentik Admin Console → Applications → Providers → Create:
- Type: OAuth2/OpenID Provider
- Name:
netbox-oidc - Client Type: Confidential
- Redirect URIs:
http://netbox.hoatranlabs.local:8080/oauth/complete/oidc/
http://10.11.45.45:8080/oauth/complete/oidc/
- Scopes:
openid,email,profile - Ghi lại Client ID và Client Secret
Tạo Application trong Authentik:
- Name: NetBox
- Provider:
netbox-oidc - Launch URL:
http://netbox.hoatranlabs.local:8080
3.2 Cấu hình NetBox để dùng OIDC
Tạo file cấu hình trong NetBox container volume:
# Tìm đường dẫn volume configuration
docker inspect netbox-netbox-1 | grep -A2 "Mounts"
# Thêm vào file configuration/configuration.py
cat >> /opt/netbox/configuration/configuration.py << 'EOF'
# ============================================================
# Authentik SSO Configuration
# ============================================================
REMOTE_AUTH_ENABLED = True
REMOTE_AUTH_BACKEND = 'social_core.backends.open_id_connect.OpenIdConnectAuth'
SOCIAL_AUTH_PIPELINE = (
'social_core.pipeline.social_auth.social_details',
'social_core.pipeline.social_auth.social_uid',
'social_core.pipeline.social_auth.auth_allowed',
'social_core.pipeline.social_auth.social_user',
'social_core.pipeline.user.get_username',
'social_core.pipeline.user.create_user',
'social_core.pipeline.social_auth.associate_user',
'social_core.pipeline.social_auth.load_extra_data',
'social_core.pipeline.user.user_details',
)
SOCIAL_AUTH_OIDC_OIDC_ENDPOINT = 'https://authentik.hoatranlabs.local:9443/application/o/netbox/'
SOCIAL_AUTH_OIDC_KEY = '<CLIENT_ID_FROM_AUTHENTIK>'
SOCIAL_AUTH_OIDC_SECRET = '<CLIENT_SECRET_FROM_AUTHENTIK>'
SOCIAL_AUTH_OIDC_IGNORE_DEFAULT_SCOPE = True
SOCIAL_AUTH_OIDC_SCOPE = ['openid', 'profile', 'email']
EOF
Khởi động lại NetBox:
cd /opt/netbox
docker compose restart netbox netbox-worker
3.3 Cho container NetBox tin root CA step-CA
Sau mục 3.2 nút đăng nhập SSO đã hiện, nhưng NetBox gọi Authentik qua HTTPS cổng 9443 (cert do step-CA cấp) bằng thư viện Python requests. requests dùng bundle certifi đi kèm chứ không đọc trust store của hệ điều hành, nên nếu container chưa có root CA thì đăng nhập SSO báo lỗi TLS (certificate verify failed). Cách xử lý: đưa bundle CA của VM245 (đã gồm root CA step-CA) vào container và trỏ REQUESTS_CA_BUNDLE tới bundle đó. Dùng cả bundle hệ thống thay vì chỉ file root CA để NetBox vẫn tin các CA công cộng.
- Trust root CA step-CA trên VM245 (cách ở bài 21 mục 7; hoặc chạy script bài 13 Bước 9):
curl -fsSLk https://step-ca.hoatranlabs.local:9000/roots.pem \
-o /usr/local/share/ca-certificates/hoatranlabs-root.crt
# Đối chiếu với: step certificate fingerprint /etc/step-ca/certs/root_ca.crt (chạy trên VM242)
openssl x509 -in /usr/local/share/ca-certificates/hoatranlabs-root.crt -noout -fingerprint -sha256
update-ca-certificates
- Ghi lại
/opt/netbox/docker-compose.override.yml(giữ phần cổng vàALLOWED_HOSTSở mục 2.3, thêm mount bundle CA và biến môi trường cho cảnetboxlẫnnetbox-worker):
services:
netbox:
ports:
- "8080:8080"
environment:
- ALLOWED_HOSTS=netbox.hoatranlabs.local 10.11.45.45 localhost
- REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
- SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
volumes:
- /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
netbox-worker:
environment:
- REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
- SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
volumes:
- /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
- Tạo lại container và kiểm tra (phải
up -d --force-recreate,restartkhông nạp mount và biến mới):
cd /opt/netbox
docker compose up -d --force-recreate netbox netbox-worker
docker exec netbox-netbox-1 /opt/netbox/venv/bin/python -c "
import requests
print(requests.get('https://authentik.hoatranlabs.local:9443/application/o/netbox/.well-known/openid-configuration').status_code)
"
# Kỳ vọng: 200
Mỗi lần thêm CA mới vào VM245 (update-ca-certificates) cũng cần tạo lại hai container này để chúng nhận bundle mới.
Nhập Dữ Liệu IP Ban Đầu
Lấy API Token · Script nhập VLAN và prefix của lab
4.1 Lấy API Token
Đăng nhập NetBox → Admin → Authentication → API Tokens → Add
Hoặc qua CLI:
docker exec -it netbox-netbox-1 python3 /opt/netbox/netbox/manage.py shell -c "
from users.models import Token, User
user = User.objects.get(username='admin')
token = Token(user=user, description='lab-import')
token.save()
print('Token: nbt_%s.%s' % (token.key, token.token))
"
API_TOKEN_PEPPER_1 đã đặt ở mục 2.2; dùng trong API với header Authorization: Bearer nbt_<key>.<token> (token v1 cũ dùng Authorization: Token <token>).
4.2 Script nhập VLAN và prefix của lab
#!/usr/bin/env python3
# /opt/scripts/import_lab_ips.py
# Chạy: python3 import_lab_ips.py
import requests
import json
NETBOX_URL = "http://10.11.45.45:8080"
API_TOKEN = "nbt_<KEY>.<TOKEN>" # token v2 (NetBox >= 4.5), lấy ở mục 4.1
headers = {
"Authorization": f"Bearer {API_TOKEN}", # token v1 cũ dùng: f"Token {API_TOKEN}"
"Content-Type": "application/json",
}
def post(endpoint, data):
r = requests.post(f"{NETBOX_URL}/api{endpoint}", headers=headers, json=data)
if r.status_code in (200, 201):
print(f" OK: {data}")
return r.json()
else:
print(f" ERR {r.status_code}: {r.text[:120]}")
return None
# 1. Tạo VLAN Group
print("=== Tạo VLAN Group ===")
vlan_group = post("/ipam/vlan-groups/", {
"name": "HOATRANLABS",
"slug": "hoatranlabs",
"description": "Lab HOATRANLABS – 5 VLANs"
})
vlan_group_id = vlan_group["id"] if vlan_group else None
# 2. Tạo các VLAN
print("\n=== Tạo VLANs ===")
vlans = [
{"name": "VLAN_MGMT", "vid": 45, "description": "Management Network 10.11.45.0/24"},
{"name": "VLAN_SEC", "vid": 25, "description": "Security Network 10.11.25.0/24"},
{"name": "VLAN_DMZ", "vid": 35, "description": "DMZ Network 10.11.35.0/24"},
{"name": "VLAN_SRV", "vid": 65, "description": "Services Network 10.11.65.0/24"},
{"name": "VLAN_STORAGE", "vid": 85, "description": "Storage Network 10.11.85.0/24"},
]
vlan_ids = {}
for v in vlans:
if vlan_group_id:
v["group"] = vlan_group_id
result = post("/ipam/vlans/", v)
if result:
vlan_ids[v["vid"]] = result["id"]
# 3. Tạo Prefixes
print("\n=== Tạo Prefixes ===")
prefixes = [
{"prefix": "10.11.45.0/24", "vlan_vid": 45, "description": "VLAN_MGMT"},
{"prefix": "10.11.25.0/24", "vlan_vid": 25, "description": "VLAN_SEC"},
{"prefix": "10.11.35.0/24", "vlan_vid": 35, "description": "VLAN_DMZ"},
{"prefix": "10.11.65.0/24", "vlan_vid": 65, "description": "VLAN_SRV"},
{"prefix": "10.11.85.0/24", "vlan_vid": 85, "description": "VLAN_STORAGE"},
]
for p in prefixes:
vid = p.pop("vlan_vid")
if vid in vlan_ids:
p["vlan"] = vlan_ids[vid]
post("/ipam/prefixes/", p)
# 4. Tạo IP Addresses cho các VM quan trọng
print("\n=== Tạo IP Addresses ===")
ips = [
# VLAN_MGMT
{"address": "10.11.45.210/24", "dns_name": "node1.hoatranlabs.local", "description": "PVE node1"},
{"address": "10.11.45.211/24", "dns_name": "node2.hoatranlabs.local", "description": "PVE node2"},
{"address": "10.11.45.212/24", "dns_name": "node3.hoatranlabs.local", "description": "PVE node3"},
{"address": "10.11.45.213/24", "dns_name": "node4.hoatranlabs.local", "description": "PVE node4"},
{"address": "10.11.45.17/24", "dns_name": "pbs01.hoatranlabs.local", "description": "Proxmox Backup Server VM101"},
{"address": "10.11.45.19/24", "dns_name": "ups01.hoatranlabs.local", "description": "UPS ups01 (NMC/SNMP, NUT)"},
{"address": "10.11.45.20/24", "dns_name": "ops01.hoatranlabs.local", "description": "ops01 VM290 (Ansible/OpenTofu, bastion; clone từ template tpl-ubuntu-2404)"},
{"address": "10.11.45.35/24", "dns_name": "prometheus.hoatranlabs.local", "description": "Prometheus VM235"},
{"address": "10.11.45.45/24", "dns_name": "netbox.hoatranlabs.local", "description": "NetBox IPAM (this VM)"},
{"address": "10.11.45.53/24", "dns_name": "pihole.hoatranlabs.local", "description": "Pi-hole DNS VM247"},
# VLAN_SEC
{"address": "10.11.25.40/24", "dns_name": "authentik.hoatranlabs.local", "description": "Authentik SSO VM234"},
{"address": "10.11.25.42/24", "dns_name": "step-ca.hoatranlabs.local", "description": "step-CA PKI VM242"},
{"address": "10.11.25.43/24", "dns_name": "vaultwarden.hoatranlabs.local", "description": "Vaultwarden VM243"},
{"address": "10.11.25.44/24", "dns_name": "openvas.hoatranlabs.local", "description": "Greenbone OpenVAS VM244"},
# VLAN_DMZ
{"address": "10.11.35.46/24", "dns_name": "mailu.hoatranlabs.local", "description": "Mailu Mail Server VM246"},
# VLAN_SRV
{"address": "10.11.65.41/24", "dns_name": "mediamtx.hoatranlabs.local", "description": "MediaMTX RTSP VM241"},
]
for ip in ips:
post("/ipam/ip-addresses/", {
"address": ip["address"],
"dns_name": ip.get("dns_name", ""),
"description": ip.get("description", ""),
"status": "active",
})
print("\n=== Import hoàn tất ===")
# Thư viện requests đã cài bằng apt ở mục 1.3 (python3-requests).
# Ubuntu 24.04 chặn `pip3 install requests` ngoài venv (PEP 668); nếu cần bản mới hơn thì dùng venv:
# apt install -y python3-venv && python3 -m venv /opt/scripts/venv && /opt/scripts/venv/bin/pip install requests
# Chạy script
python3 /opt/scripts/import_lab_ips.py
ups01 (10.11.45.19) và ops01 (VM290, 10.11.45.20, máy Ansible/OpenTofu của lab, tạo ở bài 07). Hai template cloud-init tpl-ubuntu-2404 (VMID 9000) và tpl-ubuntu-2404-docker (VMID 9001) cũng ở bài 07 không có IP cố định nên không có dòng trong script; nếu muốn quản lý VM trong NetBox (Virtualization → Virtual Machines) thì tạo thêm hai VM này với trạng thái Offline.
DNS và Cấu Hình Mạng
Thêm DNS record cho NetBox trong Pi-hole · Cấu hình FortiGate firewall
5.1 Thêm DNS record cho NetBox trong Pi-hole
Đăng nhập Pi-hole Admin (http://10.11.45.53/admin) → Settings → Local DNS Records:
netbox.hoatranlabs.local → 10.11.45.45
5.2 Cấu hình FortiGate firewall
NetBox (10.11.45.45) nằm trong VLAN_MGMT nên các máy cùng VLAN truy cập http://10.11.45.45:8080 trực tiếp, không đi qua FortiGate và không cần policy. Chỉ lưu lượng từ VLAN khác mới cần policy; ví dụ dưới đây cho VLAN_SEC (25), VLAN_SRV (65) và VLAN_USR (75) vào cổng 8080 (bỏ interface nào lab chưa có):
# FortiGate CLI
config firewall address
edit "NetBox-VM245"
set subnet 10.11.45.45 255.255.255.255
next
end
config firewall service custom
edit "TCP_8080"
set tcp-portrange 8080
next
end
config firewall policy
edit 0
set name "Allow-NetBox-Clients"
set srcintf "vlan25" "vlan65" "vlan75"
set dstintf "vlan45"
set srcaddr "all"
set dstaddr "NetBox-VM245"
set service "TCP_8080"
set schedule "always"
set action accept
set logtraffic all
next
end
NetBox gọi Authentik (VLAN_MGMT → VLAN_SEC, cổng 9443) đã có rule Allow-Authentik-Admin ở bài 14; NetBox gọi Alertmanager trên VM235 (mục 8.2) cùng VLAN_MGMT nên không qua firewall.
Backup và Bảo Trì
Backup database NetBox · Khởi động tự động khi reboot
6.1 Backup database NetBox
#!/bin/bash
# /opt/scripts/netbox-backup.sh
BACKUP_DIR="/opt/netbox-backups"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"
# Dump PostgreSQL
docker exec netbox-postgres-1 pg_dump -U netbox netbox | \
gzip > "${BACKUP_DIR}/netbox_db_${DATE}.sql.gz"
# Backup media files (uploaded images, etc.)
docker cp netbox-netbox-1:/opt/netbox/netbox/media \
"${BACKUP_DIR}/media_${DATE}" 2>/dev/null || true
# Giữ lại 7 bản backup gần nhất
ls -t "${BACKUP_DIR}"/*.sql.gz | tail -n +8 | xargs -r rm
echo "Backup completed: ${BACKUP_DIR}/netbox_db_${DATE}.sql.gz"
chmod +x /opt/scripts/netbox-backup.sh
# Cài cronjob backup hàng ngày lúc 3:00 AM
echo "0 3 * * * /opt/scripts/netbox-backup.sh >> /var/log/netbox-backup.log 2>&1" | crontab -
6.2 Khởi động tự động khi reboot
# Systemd service để start docker compose khi boot
cat > /etc/systemd/system/netbox-docker.service << 'EOF'
[Unit]
Description=NetBox Docker Compose
Requires=docker.service
After=docker.service network-online.target
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/netbox
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
[Install]
WantedBy=multi-user.target
EOF
systemctl enable netbox-docker
Xử Lý Sự Cố
NetBox không truy cập được · Database connection error · Migration errors khi update
7.1 NetBox không truy cập được
# Kiểm tra container status
cd /opt/netbox && docker compose ps
# Xem logs netbox container
docker compose logs --tail=50 netbox
# Xem logs worker (RQ)
docker compose logs --tail=50 netbox-worker
# Kiểm tra port binding
ss -tlnp | grep 8080
7.2 Database connection error
# Test kết nối postgres từ netbox container
docker exec netbox-netbox-1 python3 -c "
import psycopg
conn = psycopg.connect(host='postgres', dbname='netbox', user='netbox', password='NetBox@DB2024')
print('DB OK')
conn.close()
"
# Restart postgres nếu cần
docker compose restart postgres
docker compose restart netbox netbox-worker
7.3 Migration errors khi update
# Chạy migration thủ công
docker exec -it netbox-netbox-1 python3 /opt/netbox/netbox/manage.py migrate
# Nếu lỗi, check version compatibility
docker compose images | grep netbox
7.4 OIDC/SSO không hoạt động
# Kiểm tra endpoint Authentik từ NetBox container
# (lỗi "certificate verify failed" nghĩa là container chưa tin root CA step-CA: làm lại mục 3.3)
docker exec netbox-netbox-1 curl -s \
"https://authentik.hoatranlabs.local:9443/application/o/netbox/.well-known/openid-configuration" \
| python3 -m json.tool
# Xem Django logs
docker compose logs netbox | grep -i "social\|oidc\|auth"
Tích Hợp Nâng Cao
Kết nối NetBox API với Ansible · Webhooks — thông báo khi IP thay đổi
8.1 Kết nối NetBox API với Ansible
# inventory/netbox_inventory.yml
plugin: netbox.netbox.nb_inventory
api_endpoint: http://10.11.45.45:8080
token:
type: Bearer # token v2 (NetBox >= 4.5) dùng "Authorization: Bearer"
value: nbt_<KEY>.<TOKEN> # lấy ở mục 4.1
validate_certs: false
config_context: true
group_by:
- device_roles
- platforms
- site
Dạng ngắn token: <chuỗi> luôn gửi header Authorization: Token ... (kiểu token v1); token v2 theo tài liệu NetBox dùng Bearer, nên phải khai token dạng type + value như trên. Cách khai này có từ collection netbox.netbox 3.14.0 (tháng 8/2023), vì vậy cần cài collection từ 3.14.0 trở lên (ansible-galaxy collection install netbox.netbox); nên dùng bản mới (hiện là 3.23.1, đã được kiểm thử với NetBox 4.5 + token v2).
8.2 Webhooks — thông báo khi IP thay đổi
Ở NetBox 4.x (bản netbox-docker release đang cài), webhook và sự kiện kích hoạt là hai đối tượng riêng. Trước hết tạo webhook: Operations → Integrations → Webhooks → Add:
- Name: IP Change Alert
- URL:
http://prometheus.hoatranlabs.local:9093/api/v2/alerts(Alertmanager: containeralertmanagertrên VM235, cổng 9093 – bài 15; hoặc endpoint tùy chỉnh) - HTTP method:
POST, HTTP content type:application/json - Body template (Alertmanager chỉ nhận mảng alert, không nhận payload mặc định của NetBox):
[{"labels": {"alertname": "NetBoxIPChange", "severity": "info", "event": "{{ event }}"}, "annotations": {"summary": "{{ event }} {{ object_type }}: {{ data.address }}"}}]
Sau đó tạo Event Rule gắn webhook với sự kiện: Operations → Integrations → Event Rules → Add:
- Name: IP Change Alert
- Object types: IPAM > IP Address
- Event types: Object created, Object updated, Object deleted
- Action type: Webhook, chọn webhook
IP Change Alert
Checklist Triển Khai
- VM245 tạo thành công trên node2, có IP 10.11.45.45
- Ubuntu Server 24.04 LTS cài xong, IP tĩnh đã cấu hình
- Docker CE (repo
noble) và Docker Compose plugin đã cài,python3-requestsđã cài bằng apt - Tất cả NetBox containers ở trạng thái
running - Truy cập được
http://10.11.45.45:8080→ thấy trang đăng nhập - Đăng nhập admin thành công
- DNS record
netbox.hoatranlabs.local→10.11.45.45đã thêm vào Pi-hole - Authentik OIDC provider tạo xong, client ID/secret lấy được
- Container NetBox tin root CA step-CA (
REQUESTS_CA_BUNDLE, mục 3.3), gọi được discovery của Authentik qua HTTPS cổng 9443 - OIDC cấu hình trong
configuration.py, SSO đăng nhập được - (Nếu truy cập từ VLAN khác) policy FortiGate
Allow-NetBox-Clientstạo xong (mục 5.2) - Script import VLAN/IP đã chạy thành công
- API Token đã tạo và lưu lại
- Backup cronjob đã cài
- Systemd service
netbox-dockerenable thành công - PBS đã backup snapshot VM245
Tài Liệu Tham Khảo
- NetBox Docker: https://github.com/netbox-community/netbox-docker
- NetBox Docs: https://docs.netbox.dev/
- pynetbox: https://pynetbox.readthedocs.io/
- Authentik OIDC: https://docs.goauthentik.io/docs/providers/oauth2/
- Docker Engine trên Ubuntu (repo apt, deb822): https://docs.docker.com/engine/install/ubuntu/
- Bản phát hành NetBox: https://github.com/netbox-community/netbox/releases · netbox-docker: https://github.com/netbox-community/netbox-docker/releases
- Ubuntu 24.04 ISO: https://releases.ubuntu.com/24.04/
Cập nhật: 2026-10-15 (Ubuntu Server 24.04 LTS)