System & Network NetBox IPAM
Bài 23 · Giai đoạn 4 — DevOps & Quản lý

Triển khai NetBox IPAM + DCIM

Quản lý không gian địa chỉ IP (IPAM) và hạ tầng mạng (DCIM).

VM245 · node2 Ubuntu Server 24.04.5 LTS 10.11.45.45 2 vCPU · 4 GB · 30 GB

Bối cảnh & Lý do triển khai

Vị trí trong chuỗi bài: Bài 23 thuộc Giai đoạn 4 — DevOps & Quản lý, nối tiếp Bài 22. Gitea CI/CD và đứng trước Bài 24. OpenVAS / Greenbone.
Mức độ cần thiết: 🟢 Tùy chọn — Nhưng rất có ích khi lab > 20 thiết bị

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ụcNội dung
Ứng dụng trong DNIP Address Management, VLAN tracking, rack documentation, cable management, network topology
Tác dụng chínhREST API cho Ansible dynamic inventory, IPAM cho 5 VLAN + 30 VM, device/rack visualization
Nếu không triển khaiQuả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 đâyAnsible/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ủIPVLAN · NodeVai trò trong bài này
netbox (NetBox IPAM) · VM24510.11.45.4545 (MGMT) · node2Má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.21145 (MGMT) · cluster HOATRANHUBNode Proxmox chứa VM245; tạo VM tại đây.
pihole (Pi-hole DNS) · VM24710.11.45.5345 (MGMT) · node3DNS 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) · VM23410.11.25.4025 (SEC) · node1Nhà 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) · VM24210.11.25.4225 (SEC) · node1Cấ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.1Quản trị 10.100.100.0/24 · thiết bị mạngPolicy 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) · VM23510.11.45.3545 (MGMT) · node2Alertmanager 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) · VM10110.11.45.1745 (MGMT) · node4Sao 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ínhGiá trị
VMID245
Hostnamenetbox
Nodenode2 (10.11.45.211)
IP10.11.45.45/24
Gateway10.11.45.1
DNS10.11.45.53 (Pi-hole)
VLANVLAN_MGMT (tag 45)
vCPU2
RAM4 GB
Disk30 GB (Ceph)
OSUbuntu Server 24.04.5 LTS (noble)
Port8080 (HTTP)

Phiên bản phần mềm sử dụng (đã xác minh 2026-10-15):

Thành phầnPhiên bảnGhi chú
Ubuntu Server24.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 Engine29.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 / Buildx5.6.0 / 0.38.0Lệnh docker compose
netbox-docker5.1.1 (nhánh release)https://github.com/netbox-community/netbox-docker; nhánh release trôi theo thời gian
NetBox4.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 / Valkey18-alpine / 9.1-alpineContainer trong compose của netbox-docker (không cài trên host)
Python trên host3.12 + gói python3-requestsChỉ để chạy script nhập dữ liệu mục 4.2; NetBox có Python riêng trong image
01

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)

1
Đăng nhập Proxmox Web UI → chọn Node: node2 → nhấn Create VM (góc trên phải)
2
General:
  • VM ID: 245
  • Name: netbox
  • Bỏ tick Start after created
3
OS:
  • 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
4
System:
  • Machine: q35
  • SCSI Controller: VirtIO SCSI single
  • BIOS: SeaBIOS
  • Qemu Agent: ☑
5
Disks:
  • Bus/Device: SCSI 0, Storage: vm-ceph
  • Disk size: 30 GiB, Cache: Write back, Discard: ☑
6
CPU:
  • Sockets: 1, Cores: 2, Type: x86-64-v2-AES
7
Memory:
  • Memory (MiB): 4096
8
Network:
  • Bridge: vmbr0, VLAN Tag: 45, Model: VirtIO (paravirtualized), Firewall: ☐
9
Confirm: Xem lại → Finish → Start VM → Console để bắt đầu cài Ubuntu.
Proxmox → Create VM → tab Confirm: VM 245 netbox trên node2, 2 core, 4096 MiB RAM, disk 30 GiB vm-ceph, VLAN Tag 45 trước khi Finish.
Proxmox → Create VM → tab Confirm: VM 245 netbox trên node2, 2 core, 4096 MiB RAM, disk 30 GiB vm-ceph, VLAN Tag 45 trước khi Finish.

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, gateway 10.11.45.1, DNS 10.11.45.53
Lưu ý: Nếu Pi-hole (VM247) chưa được deploy, dùng DNS tạm 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
Dòng 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.
02

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)
Terminal VM245: docker compose ps trong /opt/netbox cho thấy 5 container netbox-netbox-1, netbox-netbox-worker-1, netbox-postgres-1, netbox-redis-1, netbox-redis-cache-1 đều running (healthy).
Terminal VM245: docker compose ps trong /opt/netbox cho thấy 5 container netbox-netbox-1, netbox-netbox-worker-1, netbox-postgres-1, netbox-redis-1, netbox-redis-cache-1 đều 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

Trình duyệt tại http://10.11.45.45:8080: trang đăng nhập NetBox và trang Home sau khi đăng nhập bằng tài khoản admin.
Trình duyệt tại http://10.11.45.45:8080: trang đăng nhập NetBox và trang Home sau khi đăng nhập bằng tài khoản admin.
03

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
Authentik Admin → Providers: netbox-oidc (OAuth2/OpenID, Confidential), hai Redirect URI /oauth/complete/oidc/, scopes openid email profile.
Authentik Admin → Providers: netbox-oidc (OAuth2/OpenID, Confidential), hai Redirect URI /oauth/complete/oidc/, scopes openid email profile.

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
Trang đăng nhập NetBox sau khi restart netbox và worker: có lựa chọn đăng nhập SSO qua Authentik (OIDC) bên cạnh form tài khoản thường.
Trang đăng nhập NetBox sau khi restart netbox và worker: có lựa chọn đăng nhập SSO qua Authentik (OIDC) bên cạnh form tài khoản thường.

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.

  1. 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
  1. 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ả netbox lẫn netbox-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
  1. Tạo lại container và kiểm tra (phải up -d --force-recreate, restart khô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.

04

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))
"
NetBox → Admin → Authentication → API Tokens: token v2 lab-import của user admin vừa tạo (key dạng nbt_..., phần token được che) để dùng cho script nhập dữ liệu.
NetBox → Admin → Authentication → API Tokens: token v2 lab-import của user admin vừa tạo (key dạng nbt_..., phần token được che) để dùng cho script nhập dữ liệu.
Token v2 (NetBox >= 4.5) chỉ hiện plaintext một lần lúc tạo, cần 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
NetBox → IPAM → IP Addresses: 16 địa chỉ lab do script nhập (ví dụ 10.11.45.45 netbox.hoatranlabs.local, 10.11.25.40 authentik.hoatranlabs.local), trạng thái Active.
NetBox → IPAM → IP Addresses: 16 địa chỉ lab do script nhập (ví dụ 10.11.45.45 netbox.hoatranlabs.local, 10.11.25.40 authentik.hoatranlabs.local), trạng thái Active.
Danh sách mẫu gồm cả 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.
05

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
Pi-hole Admin (http://10.11.45.53/admin) → Settings → Local DNS Records: bản ghi netbox.hoatranlabs.local trỏ tới 10.11.45.45 trong danh sách.
Pi-hole Admin (http://10.11.45.53/admin) → Settings → Local DNS Records: bản ghi netbox.hoatranlabs.local trỏ tới 10.11.45.45 trong danh sách.

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.

06

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
07

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"
08

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: container alertmanager trê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 }}"}}]
NetBox → Operations → Integrations → Webhooks → Add: Name IP Change Alert, URL http://prometheus.hoatranlabs.local:9093/api/v2/alerts, POST, application/json và Body template dạng mảng alert của Alertmanager.
NetBox → Operations → Integrations → Webhooks → Add: Name IP Change Alert, URL http://prometheus.hoatranlabs.local:9093/api/v2/alerts, POST, application/json và Body template dạng mảng alert của Alertmanager.

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-Clients tạ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-docker enable thành công
  • PBS đã backup snapshot VM245

Tài Liệu Tham Khảo

Cập nhật: 2026-10-15 (Ubuntu Server 24.04 LTS)

Zalo