Triển khai step-CA + PKI nội bộ
Hạ tầng khoá công khai nội bộ — cấp TLS certificate tự động.
Bối cảnh & Lý do triển khai
Không có PKI nội bộ, có hai lựa chọn tệ: (1) dùng HTTP thuần — dữ liệu không mã hóa; (2) dùng self-signed cert — browser liên tục cảnh báo "không an toàn", user bỏ qua cảnh báo tạo thói quen nguy hiểm. step-CA là Root CA nội bộ tin cậy, cấp cert tự động với auto-renewal, không cần domain public.
| Mục | Nội dung |
|---|---|
| Ứng dụng trong DN | TLS cho tất cả service intranet, zero-trust internal networking, mTLS giữa microservices |
| Tác dụng chính | Cấp cert cho Authentik/Gitea/Harbor/Vaultwarden/Mailu/Headscale...; auto-renew qua systemd timer |
| Nếu không triển khai | HTTP không mã hóa hoặc self-signed cert liên tục gây cảnh báo browser, không thể dùng mTLS |
| Các service phụ thuộc vào đây | Mọi service HTTPS nội bộ trong lab (Authentik, Gitea, Harbor, Vaultwarden, Mailu, Headscale...) đều cần cert từ step-CA để enable HTTPS; giao diện web các node Proxmox VE / PBS xin cert qua ACME provisioner acme (bài 09) |
Phiên bản: 1.2 | Ngày cập nhật: 2026-10-15
Cluster: HOATRANHUB (PVE 9.2.20) | Tác giả: HoatranLabs
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 |
|---|---|---|---|
| step-ca (step-CA PKI) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Máy chủ của bài — Root CA nội bộ chạy bằng Docker Compose (smallstep/step-ca:0.30.2, dữ liệu /etc/step-ca, Ubuntu 24.04); API và ACME cổng 9000, node_exporter cổng 9100. |
| node1 (Proxmox VE) | 10.11.45.210 | 45 (MGMT) · cluster HOATRANHUB | Node Proxmox chứa VM242 (VLAN tag 25, storage vm-ceph, backup lên pbs-primary); node1–node4 cũng xin cert web qua ACME provisioner acme (bài 09). |
| FortiGate (firewall) | 10.100.100.1 | Quản trị 10.100.100.0/24 · thiết bị mạng | Gateway VLAN_SEC của VM242, cần Running trước khi triển khai; cổng 9000 do Docker publish nên ufw không lọc được (lọc nguồn ở FortiGate), ufw trên VM242 chỉ kiểm soát 9100, 22. |
| pihole (Pi-hole DNS) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | DNS khi cài OS cho VM242, DNS cho container step-ca (dns: 10.11.45.53) và nơi thêm A record step-ca.hoatranlabs.local, pki.hoatranlabs.local (bài 12). |
| authentik (Authentik SSO) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | Nhận cert cấp thủ công bằng step ca certificate (/opt/authentik/certs), tự gia hạn bằng systemd timer 2 lần mỗi ngày (bài 14). |
| harbor (Harbor Registry) · VM239 | 10.11.45.39 | 45 (MGMT) · node2 | Nhận cert qua ACME provisioner, lưu ở /etc/ssl/harbor, SAN gồm tên miền và IP của Harbor (bài 21). |
| gitea (Gitea + Actions) · VM240 | 10.11.45.40 | 45 (MGMT) · node2 | Nhận cert qua ACME provisioner, lưu ở /opt/gitea/ssl, gia hạn bằng step ca renew + systemd timer (bài 22). |
| mailu (Mailu Mail Server) · VM246 | 10.11.35.46 | 35 (DMZ) · node2 | Nằm trong bảng inventory cert: mail.hoatranlabs.local, cert tại /opt/mailu/certs, gia hạn bằng systemd timer, hạn 90 ngày (bài 16). |
| vaultwarden (Vaultwarden) · VM243 | 10.11.25.43 | 25 (SEC) · node1 | Nằm trong bảng inventory cert: cert tại /etc/ssl/vaultwarden, gia hạn bằng systemd timer, hạn 90 ngày (bài 19). |
| headscale (Headscale VPN) · VM232 | 10.11.35.10 | 35 (DMZ) · node2 | Nằm trong bảng inventory cert: cert tại /etc/ssl/headscale, gia hạn bằng systemd timer, hạn 90 ngày (bài 20). |
| prometheus (Prometheus + Alertmanager) · VM235 | 10.11.45.35 | 45 (MGMT) · node2 | Scrape node_exporter cổng 9100 của VM242; ufw trên VM242 chỉ cho nguồn này vào cổng 9100 (bài 15). |
| pbs01 (PBS Primary) · VM101 | 10.11.45.17 | 45 (MGMT) · node4 | Lưu backup VM242: pbs-primary daily 01:00 Snapshot, và file-level /etc/step-ca, /opt/step-ca (namespace vm-step-ca); có thể xin cert ACME (bài 04, bài 09). |
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.
Phụ thuộc (Dependencies)
| Thành phần | VMID | IP | Trạng thái cần có |
|---|---|---|---|
| PVE node1 | — | 10.11.45.210 | Running |
| FortiGate (gateway VLAN_SEC) | — | 10.11.25.1 | Running |
| Pi-hole DNS | VM247 | 10.11.45.53 | Running |
| Prometheus (scrape) | VM235 | 10.11.45.35 | Running |
| PBS Backup (pbs01) | VM101 | 10.11.45.17 | Running |
Ceph storage pool vm-ceph | — | — | Healthy |
Lưu ý quan trọng: step-CA là PKI core, nên triển khai trước hoặc song song với Authentik (VM234). Sau khi có Root CA, tất cả service HTTPS (Authentik, Gitea, Harbor, Vaultwarden...) nên dùng cert từ step-CA thay vì self-signed.
Tổng Quan Kiến Trúc PKI
┌────────────────────────────────────┐
│ VM242: step-ca (Docker container) │
│ 10.11.25.42 | VLAN_SEC tag=25 │
│ step-ca API :9000 │
│ ACME endpoint:9000/acme/ │
│ node_exporter:9100 (host) │
└──────────────┬─────────────────────┘
│ issues TLS certs
┌──────────────────────┼──────────────────────┐
│ │ │
┌───────▼────────┐ ┌─────────▼───────┐ ┌─────────▼───────┐
│ Manual issuance│ │ ACME auto-renew │ │ step CLI enroll │
│ step ca cert │ │ certbot/acme.sh │ │ on each VM │
│ (one-time) │ │ (systemd timer) │ │ │
└────────────────┘ └─────────────────┘ └─────────────────┘
Phương án triển khai (quy tắc của series: có image chính thức thì ưu tiên Docker, rồi LXC, cuối cùng mới cài trực tiếp lên VM):
| Phương án | Trạng thái trong bài | Lý do chọn / không chọn | Cách chuyển đổi |
|---|---|---|---|
Docker Compose trên VM242 (image smallstep/step-ca) | Khuyến nghị — Bước 2–7 | Smallstep phát hành image chính thức, tag theo từng phiên bản nên ghim được 0.30.2; dữ liệu nằm ở bind mount /etc/step-ca nên đường dẫn /etc/step-ca/certs/root_ca.crt mà các bài khác tham chiếu và bản backup PBS in-VM (bài 04 mục 5.7) không đổi; nâng cấp bằng cách đổi tag rồi docker compose up -d; VMID, IP, VLAN, node giữ nguyên | Từ .deb sang Docker (và ngược lại): mục "Phụ Lục" cuối bài |
| LXC không đặc quyền (template Ubuntu 24.04) | Không dùng | LXC chỉ thay VM cho dịch vụ nhẹ không có Docker phù hợp; step-ca đã có image chính thức nên chọn Docker. Docker không chạy trong LXC (Proxmox không khuyến nghị), nên LXC chỉ hợp với cách .deb + systemd | Tạo LXC rồi làm theo mục "Phụ Lục"; giữ IP 10.11.25.42 và chuyển /etc/step-ca sang |
VM cài trực tiếp: gói .deb + systemd | Phương án thay thế (mục "Phụ Lục") | PKI không phụ thuộc Docker daemon; một file binary tĩnh, ít thành phần hơn | Dừng container, đổi chủ sở hữu và đường dẫn trong ca.json, bật unit systemd (mục "Phụ Lục") |
Cân nhắc khi chạy PKI trong container:
- PKI phụ thuộc Docker daemon:
docker.serviceđược bật khi boot, container córestart: unless-stoppedvà VM242 cóstartup order=1(Bước 1), nên step-CA lên trước Authentik và các service dùng cert. VM242 chỉ chạy duy nhất CA này. - Khóa Root/Intermediate (
/etc/step-ca/secrets/) nằm trong bind mount do uid 1000 (usersteptrong image) sở hữu, thư mục quyền 700 và khóa vẫn mã hóa bằng mật khẩu. Mật khẩu để trong file quyền 600 nạp bằng Docker secret, không ghi vào compose hay biến môi trường (docker inspecthiển thị biến môi trường của container). - Quyền dùng Docker daemon tương đương root trên VM242: chỉ
sysadmin(quasudo) quản trị VM này; không thêm user khác vào nhómdocker.
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 (ISO ubuntu-24.04.5-live-server-amd64.iso) | Hỗ trợ chuẩn tới 04/2029; systemd 255 (chỉ cần cho phương án .deb + systemd ở mục "Phụ Lục") |
| 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, cùng bản với bài 22; nếu dựng VM242 từ template 9001 (bài 07) thì Docker đã có sẵn |
| Docker Compose plugin / Buildx | 5.6.0 / 0.38.0 | Lệnh docker compose |
step-ca (image smallstep/step-ca:0.30.2) | 0.30.2 | Tag 0.30.2 có trên Docker Hub (cập nhật 2026-03-23, index digest sha256:a2b17872…bc8270, trùng tag latest); ghim tag, không dùng latest. Nâng từ 0.27.4 vì lỗ hổng CVE-2025-44005 (xem Bước 3); binary trong image: /usr/local/bin/step-ca |
step CLI (step-cli_0.31.0-1_amd64.deb) | 0.31.0 | Giá trị dùng chung của cả series; cài trên VM242 (host) và mọi máy client từ GitHub Releases; gói đặt binary /usr/bin/step-cli và postinst tạo lệnh step bằng update-alternatives (đã kiểm nội dung gói ngày 2026-10-15). CLI nằm trong image là bản do Smallstep đóng gói lúc build, xem bằng docker exec step-ca step version |
| node_exporter | 1.12.1 | Giá trị dùng chung của cả series; chạy trên host bằng systemd (agent không đóng container), cổng 9100 |
step-ca (step-ca_0.30.2-1_amd64.deb) | 0.30.2 | Chỉ dùng cho phương án thay thế .deb + systemd (mục "Phụ Lục"); binary /usr/bin/step-ca |
Tạo VM242
Chạy trên node1:
Cách 1: Web UI Proxmox (GUI)
- VM ID:
242 - Name:
step-ca - Bỏ tick Start after created
- Storage:
local(hoặc nơi chứa ISO) - ISO Image:
ubuntu-24.04.5-live-server-amd64.iso(tải từ https://releases.ubuntu.com/24.04/) - 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(thường làvm-ceph) - Disk size:
20 GiB, Cache:Write back, Discard: ☑
- Sockets:
1, Cores:2, Type:x86-64-v2-AES
- Memory (MiB):
2048
- Bridge:
vmbr0, VLAN Tag:25, Model:VirtIO (paravirtualized), Firewall: ☐
Cách 2: CLI (qm create)
qm create 242 \
--name step-ca \
--memory 2048 \
--cores 2 \
--net0 virtio,bridge=vmbr0,tag=25 \
--scsi0 vm-ceph:20 \
--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 \
--startup order=1,up=20
startup order=1: step-CA nên khởi động trước Authentik và các service dùng cert.
Cài đặt OS Ubuntu Server 24.04 LTS (kiểm tra tên NIC bằng ip -br link: VM q35 thường là enp6s18 hoặc ens18; netplan do bộ cài/cloud-init ghi ở /etc/netplan/50-cloud-init.yaml):
Hostname : step-ca
Username : sysadmin
Password : <mật khẩu mạnh>
IP : 10.11.25.42/24
Gateway : 10.11.25.1
DNS : 10.11.45.53
Eject ISO sau khi cài:
qm set 242 --ide2 none
Chuẩn Bị Hệ Thống
Chạy bằng quyền root (sudo -i). Bước này cài hệ thống, Docker Engine (repo chính thức, suite noble, dạng deb822 docker.sources + Signed-By, không dùng apt-key) và tạo thư mục dữ liệu cho container.
# Ubuntu 24.04: needrestart có thể hiện hộp thoại hỏi khi apt cập nhật thư viện, đặt chế độ tự động để script không bị dừng
export NEEDRESTART_MODE=a
apt update && apt upgrade -y
apt install -y curl wget ca-certificates openssl qemu-guest-agent
systemctl enable --now qemu-guest-agent
# 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 từ repo chính thức (suite noble)
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
# 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
systemctl is-enabled docker # enabled: Docker tự chạy khi boot, kéo theo container có restart policy
# Thư mục dữ liệu CA (bind mount vào /home/step của container) và thư mục compose + secret
# uid:gid 1000:1000 = user `step` trong image smallstep/step-ca (STEPUID=STEPGID=1000 trong Dockerfile của step-cli);
# trên host uid 1000 thường trùng user sysadmin của bộ cài, không sao: container chỉ cần quyền ghi theo số uid
install -d -o 1000 -g 1000 -m 755 /etc/step-ca
install -d -m 755 /opt/step-ca
install -d -o 1000 -g 1000 -m 700 /opt/step-ca/secrets
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. Nếu VM242 được clone từ template 9001 (Ubuntu 24.04 + Docker, bài 07) thì Docker đã có sẵn: chỉ cần chạy các lệnh kiểm tra phiên bản và ba lệnh install -d cuối.
Cài step CLI và Tải Image step-ca
# 1) step CLI trên host (gói .deb chính thức, Ubuntu 24.04 amd64, GitHub Releases): dùng cho `step certificate fingerprint`,
# `step ca root`, `step ca certificate`... ngay trên VM242 và là lệnh mà các bài khác gọi khi hướng dẫn "chạy trên VM242".
# Bản mới xem tại https://github.com/smallstep/cli/releases (0.31.0 = giá trị dùng chung của series)
STEP_VERSION="0.31.0"
cd /tmp
wget "https://github.com/smallstep/cli/releases/download/v${STEP_VERSION}/step-cli_${STEP_VERSION}-1_amd64.deb"
# Gói đặt binary /usr/bin/step-cli và script postinst tạo lệnh `step` (update-alternatives: /usr/bin/step -> /usr/bin/step-cli)
apt install -y "./step-cli_${STEP_VERSION}-1_amd64.deb"
step version
# 2) Image step-ca: GHIM TAG phiên bản, không dùng :latest (nâng cấp có chủ đích ở Bước 7).
# Tag 0.30.2 = bản stable mới nhất trên Docker Hub (https://hub.docker.com/r/smallstep/step-ca/tags), xác minh 2026-10-15
STEP_CA_IMAGE="smallstep/step-ca:0.30.2"
docker pull "${STEP_CA_IMAGE}"
docker run --rm --entrypoint step-ca "${STEP_CA_IMAGE}" version # Smallstep CA/0.30.2 ...
docker image inspect "${STEP_CA_IMAGE}" --format '{{index .RepoDigests 0}}'
# Digest index của tag 0.30.2 (Docker Hub, 2026-10-15): sha256:a2b17872915c193259b75a5474c398326f41bd199f0842093e52cf4182bc8270
step ca init / step ca provisioner add ghi ca.json): cần kiểm lại trên máy thật.
Tạo Password File Cho Root CA
# Tạo mật khẩu bảo vệ private key của Root CA / Intermediate CA (cũng là mật khẩu của provisioner [email protected])
# LƯU MẬT KHẨU NÀY VÀO VAULT HOẶC NƠI AN TOÀN
( umask 077; openssl rand -base64 32 | tr -d '\n' > /opt/step-ca/secrets/ca_password ) # subshell: umask 077 không lan sang các lệnh sau trong phiên root
chown 1000:1000 /opt/step-ca/secrets/ca_password # uid của user `step` trong container (Bước 2)
chmod 600 /opt/step-ca/secrets/ca_password
echo "Root CA password:"
cat /opt/step-ca/secrets/ca_password; echo
File này là Docker secret: compose (Bước 5) mount nó vào container tại /run/secrets/step_ca_password và entrypoint của image đọc qua DOCKER_STEPCA_INIT_PASSWORD_FILE, nên mật khẩu không nằm trong docker-compose.yml hay biến môi trường. Lần khởi tạo đầu tiên, entrypoint chép mật khẩu sang /home/step/secrets/password (= /etc/step-ca/secrets/password trên host) để step-ca đọc mỗi lần khởi động. Vì bản sao đó nằm trong thư mục dữ liệu nên bản backup /etc/step-ca (Bước 13) cũng chứa mật khẩu: kho backup phải được mã hóa và hạn chế quyền truy cập.
Khởi Tạo Root CA
Tạo file compose. Lần chạy đầu, entrypoint của image thấy chưa có config/ca.json nên tự chạy step ca init theo các biến DOCKER_STEPCA_INIT_* (root + intermediate, provisioner JWK, provisioner ACME); những lần sau các biến này bị bỏ qua.
cat > /opt/step-ca/docker-compose.yml << 'EOF'
name: step-ca
services:
step-ca:
image: smallstep/step-ca:0.30.2 # ghim tag; nâng cấp ở Bước 7
container_name: step-ca
restart: unless-stopped
environment:
# Chỉ được đọc MỘT lần, khi /home/step/config/ca.json chưa tồn tại
DOCKER_STEPCA_INIT_NAME: "HoatranLabs Internal CA"
DOCKER_STEPCA_INIT_DNS_NAMES: "step-ca.hoatranlabs.local,10.11.25.42" # tên đầu tiên = ca-url trong defaults.json
DOCKER_STEPCA_INIT_ADDRESS: ":9000"
DOCKER_STEPCA_INIT_PROVISIONER_NAME: "[email protected]"
DOCKER_STEPCA_INIT_DEPLOYMENT_TYPE: "standalone"
DOCKER_STEPCA_INIT_ACME: "true" # tạo sẵn provisioner ACME tên "acme"
DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT: "false" # giữ ca.json làm nguồn cấu hình (policy ở bài 09)
DOCKER_STEPCA_INIT_PASSWORD_FILE: /run/secrets/step_ca_password
secrets:
- step_ca_password
ports:
- "9000:9000" # API + ACME của step-ca
volumes:
- /etc/step-ca:/home/step # dữ liệu CA (certs, config, secrets, db) nằm trên host, owner uid 1000
extra_hosts:
- "step-ca.hoatranlabs.local:127.0.0.1" # `step ca health` trong container gọi chính nó, không phụ thuộc DNS
dns:
- 10.11.45.53 # Pi-hole (bài 12): container phân giải nodeN.hoatranlabs.local khi xác thực http-01 (bài 09)
healthcheck:
test: ["CMD-SHELL", "step ca health 2>/dev/null | grep -q '^ok'"]
interval: 30s
timeout: 5s
retries: 3
start_period: 20s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
security_opt:
- no-new-privileges:true
networks:
- step-ca-net
networks:
step-ca-net:
name: step-ca-net
driver: bridge
secrets:
step_ca_password:
file: /opt/step-ca/secrets/ca_password
EOF
chmod 644 /opt/step-ca/docker-compose.yml # file không chứa bí mật
cd /opt/step-ca
docker compose config -q && echo "compose hợp lệ"
docker compose up -d
docker compose logs -f step-ca # Ctrl+C để thoát; chờ khoảng "Your PKI is ready to go" và "Serving HTTPS on :9000"
Giải thích các lựa chọn chính:
-
DOCKER_STEPCA_INIT_*: giữ đúng chính sách trước đây (tên CAHoatranLabs Internal CA, SANstep-ca.hoatranlabs.local+10.11.25.42, cổng:9000, provisioner JWK[email protected], provisioner ACMEacme, kiểu triển khaistandalone). Không bậtDOCKER_STEPCA_INIT_REMOTE_MANAGEMENTđể provisioner và policy vẫn nằm trongca.jsonnhư Bước 6 và bài 09; README của image trên Docker Hub ghi bật là "recommended", nếu bật thì phải quyết định ngay lúc khởi tạo và cách quản trị provisioner thay đổi (cần kiểm lại trên máy thật). -
/etc/step-ca:/home/step: bind mount, thư mục host do uid 1000 sở hữu (Bước 2). Đường dẫn trên host giữ nguyên/etc/step-ca/certs/root_ca.crtcho mọi bài khác, PBS backup vàdistribute-root-ca.sh; còn trong container là/home/step/...(các đường dẫn trongca.jsoncũng là/home/step/...). -
extra_hosts+dns: container không đọc/etc/hostscủa host.extra_hostsgiúp healthcheck gọi về chính nó;dnstrỏ tới Pi-hole để step-ca phân giải tên node khi xác thựchttp-01. Chưa có Pi-hole thì bỏ dòngdns(container dùng DNS của host) và thêm các tên node vàoextra_hosts. -
logging:json-filevớimax-size/max-fileđể log không phình ra đĩa 20 GiB; Alloy (bài 33, khốiloki.source.dockervới nhãnjob="docker-containers") đọc log container qua Docker API nên thu được log của containerstep-canếu bạn cài Alloy trên VM242. -
no-new-privileges: tiến trình trong container không tự nâng quyền.step-canghe cổng 9000 (> 1024) nên không cần capability nào (Dockerfile của image có đặt sẵn file capabilitycap_net_bind_servicecho binarystep-ca, không dùng tới ở cổng này); nếu container báooperation not permittedkhi khởi động, bỏ hai dòngsecurity_opt(cần kiểm lại trên máy thật). - Mạng bridge riêng
step-ca-net; cổng 9000 được publish trên mọi địa chỉ của VM242. Docker bỏ qua luậtufwkhi publish cổng nên phải lọc nguồn ở FortiGate, xem ghi chú ở Bước 12.
Container vừa khởi tạo CA nên log của nó có dòng Your CA administrative password is: ... (chính là mật khẩu ở Bước 4). Tạo lại container để xóa log đó:
cd /opt/step-ca
docker compose up -d --force-recreate # container mới: log mới, dữ liệu vẫn nằm ở /etc/step-ca
docker compose logs --tail=20 step-ca # không còn dòng mật khẩu
docker compose ps # sau khoảng 30-60 giây: STATUS "Up ... (healthy)"
Sau khi init, chỉnh quyền cho phần công khai: certs/ chỉ chứa chứng chỉ nên cho user thường trên host đọc (các bài khác chạy scp/cat /etc/step-ca/certs/root_ca.crt từ đây), còn secrets/, db/, config/ giữ nguyên quyền 700 của uid 1000:
chmod 755 /etc/step-ca/certs
chmod 644 /etc/step-ca/certs/*.crt
chmod 600 /etc/step-ca/secrets/password # bản sao mật khẩu do entrypoint tạo
Ghi lại Root CA Fingerprint (dùng để trust CA trên các VM):
# Xem fingerprint Root CA (step CLI cài trên host ở Bước 3)
step certificate fingerprint /etc/step-ca/certs/root_ca.crt
# Ví dụ output: a1b2c3d4e5f6... (64 ký tự hex)
# LƯU GIÁ TRỊ NÀY LẠI
# Cùng giá trị, đọc từ trong container: docker exec step-ca step certificate fingerprint /home/step/certs/root_ca.crt
Xem cấu trúc thư mục sau khi init:
ls -ln /etc/step-ca/ # cột chủ sở hữu hiện 1000 1000 (uid:gid của user `step` trong container)
# certs/ - root_ca.crt, intermediate_ca.crt
# config/ - ca.json (cấu hình CA), defaults.json (ca-url, root, fingerprint cho step CLI trong container)
# db/ - badger database
# secrets/ - root_ca_key, intermediate_ca_key (bảo vệ bằng password), password (bản sao mật khẩu cho step-ca)
# templates/ - certificate templates
Cấu Hình Thêm Provisioner ACME
ACME provisioner cho phép service tự động xin và renew cert (tương thích Let's Encrypt API). Provisioner đặt tên acme nên Directory URL là https://step-ca.hoatranlabs.local:9000/acme/acme/directory; Harbor, Gitea (Bước 10) và các node Proxmox VE / PBS (mục "ACME Provisioner Cho Proxmox VE" bên dưới, bài 09) cùng dùng provisioner này. Provisioner acme đã được tạo ở Bước 5 nhờ DOCKER_STEPCA_INIT_ACME: "true", nên bước này chỉ kiểm tra (và thêm bằng tay nếu thiếu). Các lệnh quản trị chạy bằng step bên trong container qua docker exec (STEPPATH của container là /home/step, nên --ca-config trỏ /home/step/config/ca.json; thư mục /etc/step-ca ở host là cùng dữ liệu đó):
# Xem danh sách provisioner NGAY TỪ ca.json (kiểm tra offline; chạy bằng root vì thư mục config/ chỉ uid 1000 và root đọc được)
python3 -c "import json; [print(p['type'], p['name']) for p in json.load(open('/etc/step-ca/config/ca.json'))['authority']['provisioners']]"
# Kết quả mong đợi (2 dòng):
# JWK [email protected]
# ACME acme
# Cách khác: hỏi CA qua API bằng step CLI trong container (ca-url và root lấy từ /home/step/config/defaults.json)
docker exec step-ca step ca provisioner list
# CHỈ chạy khi thiếu provisioner "acme" (vd. CA từng khởi tạo mà không bật DOCKER_STEPCA_INIT_ACME): thêm vào ca.json rồi nạp lại cấu hình
docker exec step-ca step ca provisioner add acme --type ACME --ca-config /home/step/config/ca.json
docker kill -s HUP step-ca
Chỉnh sửa ca.json để cấu hình default cert lifetime:
cat /etc/step-ca/config/ca.json
Tìm và cập nhật phần "claims" trong ca.json:
"claims": {
"minTLSCertDuration": "5m",
"maxTLSCertDuration": "2160h",
"defaultTLSCertDuration": "2160h",
"disableRenewalNotification": false,
"minHostSSHCertDuration": "5m",
"maxHostSSHCertDuration": "1680h",
"minUserSSHCertDuration": "5m",
"maxUserSSHCertDuration": "24h"
}
# Sửa file ca.json trên host (chạy bằng root; dùng python3 để parse JSON an toàn)
python3 << 'EOF'
import json
with open('/etc/step-ca/config/ca.json', 'r') as f:
config = json.load(f)
config['authority']['claims'] = {
"minTLSCertDuration": "5m",
"maxTLSCertDuration": "2160h",
"defaultTLSCertDuration": "2160h",
"disableRenewalNotification": False
}
with open('/etc/step-ca/config/ca.json', 'w') as f:
json.dump(config, f, indent=4)
print("ca.json updated successfully")
EOF
chown 1000:1000 /etc/step-ca/config/ca.json # giữ chủ sở hữu là uid của user `step` trong container
# Nạp lại cấu hình: step-ca nhận SIGHUP là đọc lại ca.json (hoặc restart: xem Bước 7)
docker kill -s HUP step-ca
Vận Hành Container (Kiểm Tra, Tự Khởi Động, Reload, Nâng Cấp)
Container đã chạy từ Bước 5. Kiểm tra trạng thái, healthcheck và chính sách khởi động lại:
cd /opt/step-ca
docker compose ps # step-ca: Up ... (healthy)
docker inspect step-ca --format 'health={{.State.Health.Status}} restart={{.HostConfig.RestartPolicy.Name}}'
# health=healthy restart=unless-stopped
docker compose logs --tail=30 step-ca
Kiểm tra CA đang chạy:
curl -sk https://step-ca.hoatranlabs.local:9000/health | python3 -m json.tool
# Kết quả mong đợi: {"status": "ok"}
Tự khởi động: docker.service được bật khi boot (Bước 2) và container có restart: unless-stopped, nên sau khi VM242 khởi động lại (hoặc Docker daemon khởi động lại) step-ca tự chạy lại; riêng container bạn đã chủ động docker compose stop thì giữ nguyên trạng thái dừng. Thử bằng reboot, rồi docker compose ps phải báo healthy sau khoảng một phút.
Reload cấu hình (sau khi sửa ca.json, thêm provisioner, đặt policy ở bài 09): step-ca đọc lại cấu hình khi nhận SIGHUP, hoặc restart container:
docker kill -s HUP step-ca # nạp lại ca.json, không ngắt container
docker compose -f /opt/step-ca/docker-compose.yml restart step-ca # nếu cần restart hẳn
docker compose -f /opt/step-ca/docker-compose.yml logs --tail=20 step-ca
Chạy CLI quản trị: lệnh step ngoài container dùng cấu hình ~/.step của host, còn lệnh quản trị CA phải chạy trong container (STEPPATH /home/step). Tạo alias stepca để gõ ngắn (đăng nhập lại để có hiệu lực; trong script dùng docker exec step-ca step ..., không có -it):
cat > /etc/profile.d/step-ca.sh << 'EOF'
alias stepca='docker exec -it step-ca step'
EOF
# Ví dụ sau khi đăng nhập lại: stepca ca provisioner list ; stepca certificate fingerprint /home/step/certs/root_ca.crt
Nâng cấp image (đổi tag, không dùng latest). Tag mới xem tại https://hub.docker.com/r/smallstep/step-ca/tags và ghi chú phát hành tại https://github.com/smallstep/certificates/releases; backup trước (Bước 13):
cd /opt/step-ca
NEW_TAG="<tag mới, dạng 0.30.x>"
BK="/root/step-ca-data-$(date +%F).tgz"
docker compose stop step-ca
tar -C /etc -czpf "$BK" step-ca && chmod 600 "$BK" # chứa khóa + mật khẩu: giữ chặt hoặc chép ra offline rồi xóa
sed -i "s#smallstep/step-ca:[0-9][0-9.]*#smallstep/step-ca:${NEW_TAG}#" docker-compose.yml
grep 'image:' docker-compose.yml
docker compose pull
docker compose up -d
docker exec step-ca step-ca version
curl -sk https://step-ca.hoatranlabs.local:9000/health
Nâng cấp không chạy lại step ca init vì ca.json đã có; dữ liệu CA ở /etc/step-ca giữ nguyên. Quay lại bản cũ: đặt lại tag cũ rồi docker compose up -d (nếu bản mới đã ghi db/ thì khôi phục từ file .tgz).
Cài node_exporter
# node_exporter 1.12.1: giá trị dùng chung của cả series (đã xác minh 2026-10-15)
NODE_EXPORTER_VERSION="1.12.1"
cd /tmp
wget -q "https://github.com/prometheus/node_exporter/releases/download/v${NODE_EXPORTER_VERSION}/node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64.tar.gz"
tar xzf "node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64.tar.gz"
cp "node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64/node_exporter" /usr/local/bin/
chmod 755 /usr/local/bin/node_exporter
id node_exporter &>/dev/null || useradd -rs /bin/false node_exporter
cat > /etc/systemd/system/node_exporter.service << 'EOF'
[Unit]
Description=Prometheus Node Exporter
After=network-online.target
[Service]
User=node_exporter
Group=node_exporter
Type=simple
Restart=on-failure
ExecStart=/usr/local/bin/node_exporter --web.listen-address=:9100
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now node_exporter
Phân Phối Root CA Certificate Đến Tất Cả VM
Script cài Root CA cert lên từng VM Ubuntu để browser và OS tin tưởng:
#!/bin/bash
# distribute-root-ca.sh
# Chạy bằng root trên MỖI VM Ubuntu (và trên mỗi node Proxmox VE / PBS, bài 09) sau khi step-CA đã chạy
# Biến: CA_URL, CA_FINGERPRINT (lấy từ Bước 5)
CA_URL="https://step-ca.hoatranlabs.local:9000"
CA_FINGERPRINT="REPLACE_WITH_FINGERPRINT_FROM_STEP_5"
CERT_PATH="/usr/local/share/ca-certificates/hoatranlabs-root.crt"
echo "[1/3] Cài step CLI (gói .deb, chạy được trên Ubuntu 24.04, Debian và Proxmox VE)..."
STEP_VERSION="0.31.0"
cd /tmp
wget -q "https://github.com/smallstep/cli/releases/download/v${STEP_VERSION}/step-cli_${STEP_VERSION}-1_amd64.deb"
apt-get install -y "./step-cli_${STEP_VERSION}-1_amd64.deb"
echo "[2/3] Tải Root CA cert..."
step ca root "${CERT_PATH}" \
--ca-url "${CA_URL}" \
--fingerprint "${CA_FINGERPRINT}"
echo "[3/3] Trust Root CA..."
chmod 644 "${CERT_PATH}"
update-ca-certificates
echo "Done. Root CA trusted on $(hostname)"
Phát Hành TLS Certificate Cho Service
Cấp cert thủ công (one-time) cho Authentik:
# Chạy trên VM234 (Authentik) sau khi đã trust Root CA (thư mục /opt/authentik/certs/ tạo ở bài 14)
# Thư mục này được mount vào container worker tại /certs: Authentik tự import authentik.crt + authentik.key
# thành key pair `authentik`, rồi gán cho Brand ở bài 14 mục 7.3-7.4
# Khi đã có --san thì tên subject không tự thành SAN, nên khai báo cả tên lẫn IP (giống Harbor/Gitea bên dưới):
# truy cập https://10.11.25.40:9443 bằng IP không bị lệch tên
step ca certificate "authentik.hoatranlabs.local" \
/opt/authentik/certs/authentik.crt \
/opt/authentik/certs/authentik.key \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--root /usr/local/share/ca-certificates/hoatranlabs-root.crt \
--provisioner [email protected] \
--san authentik.hoatranlabs.local \
--san 10.11.25.40 \
--not-after 2160h
Cấp cert cho Harbor (theo bài 21):
# Chạy trên VM239 (Harbor)
mkdir -p /etc/ssl/harbor
step ca certificate "harbor.hoatranlabs.local" \
/etc/ssl/harbor/harbor.crt \
/etc/ssl/harbor/harbor.key \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--root /usr/local/share/ca-certificates/hoatranlabs-root.crt \
--provisioner acme \
--san harbor.hoatranlabs.local \
--san 10.11.45.39
Cấp cert qua ACME provisioner cho Gitea (theo bài 22):
# Chạy trên VM240 (Gitea); gia hạn bằng step ca renew + systemd timer (xem bài 22)
mkdir -p /opt/gitea/ssl
step ca certificate "gitea.hoatranlabs.local" \
/opt/gitea/ssl/cert.pem \
/opt/gitea/ssl/key.pem \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--root /usr/local/share/ca-certificates/hoatranlabs-root.crt \
--provisioner acme \
--san gitea.hoatranlabs.local \
--san 10.11.45.40
chmod 640 /opt/gitea/ssl/key.pem
ACME Provisioner Cho Proxmox VE / PBS (bài 09)
Bài 09 dùng step-CA làm ACME CA để cấp chứng chỉ cho giao diện web (cổng 8006) của các node Proxmox VE và, tùy chọn, PBS/PDM. Phía step-CA chỉ cần provisioner acme (tạo lúc khởi tạo ở Bước 5, kiểm ở Bước 6, dùng chung với Harbor/Gitea) cùng vài điều kiện mạng và tin cậy bên dưới; lệnh phía Proxmox (pvenode acme ...) nằm ở bài 09. Nếu đi tuần tự, hoàn thành bài 13 trước khi làm bài 09.
Thêm và kiểm tra provisioner acme (chạy trên VM242):
# Lệnh quản trị giống Bước 6: chạy `step` trong container. Xem trước, chỉ chạy lệnh add nếu CHƯA thấy provisioner "acme"
# (Bước 5 đã bật sẵn bằng DOCKER_STEPCA_INIT_ACME)
docker exec step-ca step ca provisioner list
# Phải có một provisioner "type": "ACME", "name": "acme"
docker exec step-ca step ca provisioner add acme --type ACME --ca-config /home/step/config/ca.json
docker kill -s HUP step-ca # ca.json sửa bằng CLI phải được nạp lại (SIGHUP) hoặc restart: docker compose -f /opt/step-ca/docker-compose.yml restart step-ca
# Kiểm tra từ máy khách bất kỳ đã có Root CA (không cần vào container): danh sách provisioner là thông tin công khai của CA
step ca provisioner list --ca-url https://step-ca.hoatranlabs.local:9000 --root /etc/step-ca/certs/root_ca.crt # trên VM242; máy khác dùng --root /usr/local/share/ca-certificates/hoatranlabs-root.crt
curl -s --cacert /etc/step-ca/certs/root_ca.crt https://step-ca.hoatranlabs.local:9000/acme/acme/directory | python3 -m json.tool
# Kết quả mẫu: có các khóa newNonce, newAccount, newOrder, revokeCert, keyChange
Directory URL cho Proxmox: https://step-ca.hoatranlabs.local:9000/acme/acme/directory (tên provisioner acme nằm giữa /acme/ và /directory). Thời hạn chứng chỉ do claims quyết định (client ACME không tự chọn được): claims toàn cục ở Bước 6 (defaultTLSCertDuration = maxTLSCertDuration = 2160h, tức 90 ngày) áp dụng cho acme. Theo tài liệu Proxmox, dịch vụ pve-daily-update thử gia hạn khi chứng chỉ đã hết hạn hoặc còn dưới 30 ngày, nên 90 ngày là phù hợp. Muốn đặt thời hạn riêng cho provisioner này (CA không bật remote management nên phải sửa thẳng ca.json bằng --ca-config): docker exec step-ca step ca provisioner update acme --x509-default-dur 720h --x509-max-dur 720h --ca-config /home/step/config/ca.json rồi docker kill -s HUP step-ca (720h chỉ minh hoạ cú pháp; với Proxmox đừng đặt ≤ 720h, xem bài 09 mục 6.2; tên cờ --x509-*-dur và --ca-config đối chiếu với mã nguồn step CLI 0.31.0, command/ca/provisioner/update.go; chạy thật trên CA của lab: cần kiểm lại trên máy thật).
Điều kiện để node Proxmox đặt hàng thành công:
| # | Yêu cầu | Chi tiết |
|---|---|---|
| 1 | Node → step-CA, TCP 9000 | VLAN 45 → VLAN 25: đã nằm trong quy tắc "Tất cả VM → 9000" và ufw allow from 10.11.0.0/16 (Bước 12) |
| 2 | step-CA → node, TCP 80 | Với challenge http-01, VM242 (10.11.25.42) gọi ngược http://node1.hoatranlabs.local/.well-known/acme-challenge/...; plugin Standalone của Proxmox mở cổng 80 tạm thời trong lúc xác thực. Mở policy FortiGate VLAN 25 → VLAN 45 (10.11.45.210–213, thêm pbs01 10.11.45.17 nếu cấp cho PBS) cổng 80, và cho phép 10.11.25.42 → cổng 80 trong firewall của node (bài 05) |
| 3 | DNS hai chiều | Container step-ca (không chỉ VM242) phân giải được node1…node4.hoatranlabs.local và pbs01.hoatranlabs.local (bản ghi trong Pi-hole, bài 12; compose đã đặt dns: 10.11.45.53): kiểm bằng docker exec step-ca getent hosts node1.hoatranlabs.local; node phân giải được step-ca.hoatranlabs.local |
| 4 | Node tin cậy Root CA | Chạy distribute-root-ca.sh (Bước 9) bằng root trên từng node; script dùng gói .deb nên chạy được trên Proxmox VE (Debian) và update-ca-certificates có sẵn. Việc pvenode chấp nhận CA nội bộ qua kho tin cậy hệ thống: cần kiểm lại trên máy thật |
| 5 | Giờ hệ thống chính xác | Lệch giờ giữa node và VM242 làm chứng chỉ báo "chưa có hiệu lực" |
Tóm tắt phía Proxmox (chi tiết, đa node và xử lý lỗi ở bài 09):
# Trên node1 (lặp lại cho node2–node4 với tên nodeN tương ứng)
pvenode acme account register default [email protected] --directory https://step-ca.hoatranlabs.local:9000/acme/acme/directory
pvenode config set --acme domains=node1.hoatranlabs.local
pvenode acme cert order
# Kết quả mẫu: "Placing ACME order ... Status is 'valid'! ... Setting pveproxy certificate and key ... Restarting pveproxy ... Task OK"
Cấu Hình Auto-Renew với step CLI + systemd Timer
Trên mỗi VM dùng cert từ step-CA, thiết lập auto-renew:
# Tạo script renew
cat > /usr/local/bin/renew-cert-authentik.sh << 'EOF'
#!/bin/bash
set -e
CERT="/opt/authentik/certs/authentik.crt"
KEY="/opt/authentik/certs/authentik.key"
CA_URL="https://step-ca.hoatranlabs.local:9000"
ROOT_CA="/usr/local/share/ca-certificates/hoatranlabs-root.crt"
# Renew khi cert đã qua 66% thời hạn (mặc định của step certificate needs-renewal)
# Authentik không đọc file cert trực tiếp: worker import cặp cert/key từ /certs (= /opt/authentik/certs
# trên host, bài 14 mục 7.3) vào database, nên sau khi renew phải import lại rồi restart server để HTTPS :9443 dùng cert mới
step certificate needs-renewal "${CERT}" && \
step ca renew --force "${CERT}" "${KEY}" \
--ca-url "${CA_URL}" \
--root "${ROOT_CA}" && \
docker compose -f /opt/authentik/docker-compose.yml exec -T worker \
ak import_certificate --certificate /certs/authentik.crt --private-key /certs/authentik.key --name authentik && \
docker compose -f /opt/authentik/docker-compose.yml restart server || true
EOF
chmod +x /usr/local/bin/renew-cert-authentik.sh
# Tạo systemd service renew
cat > /etc/systemd/system/renew-cert-authentik.service << 'EOF'
[Unit]
Description=Renew Authentik TLS Certificate
After=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/local/bin/renew-cert-authentik.sh
EOF
# Tạo systemd timer (chạy 2 lần mỗi ngày)
cat > /etc/systemd/system/renew-cert-authentik.timer << 'EOF'
[Unit]
Description=Timer for Authentik cert renewal
Requires=renew-cert-authentik.service
[Timer]
OnCalendar=*-*-* 03,15:00:00
RandomizedDelaySec=600
Persistent=true
[Install]
WantedBy=timers.target
EOF
systemctl daemon-reload
systemctl enable --now renew-cert-authentik.timer
Bảng Inventory Certificate
| Service | VM | Domain | Cert Path | Renew Method | Expiry |
|---|---|---|---|---|---|
| Authentik | VM234 | authentik.hoatranlabs.local | /opt/authentik/certs/authentik.crt | systemd timer | 90 ngày |
| Mailu | VM246 | mail.hoatranlabs.local | /opt/mailu/certs/cert.pem | systemd timer | 90 ngày |
| Gitea | VM240 | gitea.hoatranlabs.local | /opt/gitea/ssl/cert.pem | systemd timer | 90 ngày |
| Harbor | VM239 | harbor.hoatranlabs.local | /etc/ssl/harbor/harbor.crt | systemd timer | 90 ngày |
| Vaultwarden | VM243 | vaultwarden.hoatranlabs.local | /etc/ssl/vaultwarden/vaultwarden.crt | systemd timer | 90 ngày |
| step-CA | VM242 | step-ca.hoatranlabs.local | /etc/step-ca/certs/ | Internal | 10 năm |
| Headscale | VM232 | headscale.hoatranlabs.local | /etc/ssl/headscale/headscale.crt | systemd timer | 90 ngày |
| Proxmox VE (node1–node4) | — | node1…node4.hoatranlabs.local | /etc/pve/local/pveproxy-ssl.pem (bài 09) | ACME (pve-daily-update, provisioner acme) | 90 ngày |
Cấu Hình DNS và Firewall
Thêm A records trong Pi-hole:
| Domain | IP |
|---|---|
| step-ca.hoatranlabs.local | 10.11.25.42 |
| pki.hoatranlabs.local | 10.11.25.42 |
Quy tắc firewall (VLAN_SEC):
| Nguồn | Đích | Port | Protocol | Mục đích |
|---|---|---|---|---|
| Tất cả VM | 10.11.25.42 | 9000 | TCP | Xin / renew cert |
| 10.11.45.35 (Prometheus) | 10.11.25.42 | 9100 | TCP | Metrics scrape |
| Admin VLAN | 10.11.25.42 | 22 | TCP | SSH admin |
| 10.11.25.42 (step-CA) | node1–node4 (10.11.45.210–213), pbs01 (10.11.45.17) | 80 | TCP | step-CA xác thực challenge http-01 khi Proxmox/PBS xin cert qua ACME (bài 09); mở trên FortiGate, VM242 mặc định cho phép kết nối đi ra |
Mở port trên VM242:
ufw allow from 10.11.0.0/16 to any port 9000 proto tcp
# Site phụ (node5, node6, pbsdr01 — bài 09 xin chứng chỉ ACME từ đây); cần thêm policy FortiGate 10.100.100.0/24 -> 10.11.25.42:9000
ufw allow from 10.100.100.0/24 to any port 9000 proto tcp
ufw allow from 10.11.45.35 to any port 9100 proto tcp
ufw allow from 10.11.45.0/24 to any port 22 proto tcp
ufw enable
9000:9000 trong compose) đi qua chuỗi iptables riêng của Docker nên bỏ qua luật ufw ở trên: hai dòng ufw allow ... port 9000 chỉ còn tác dụng ghi nhận ý định, còn lọc nguồn thật sự phải làm ở FortiGate (bảng quy tắc phía trên). Cổng 9100 (node_exporter) và 22 chạy trên host nên vẫn do ufw kiểm soát. Không dùng 127.0.0.1:9000:9000 vì các VM khác cần gọi cổng 9000 qua IP 10.11.25.42. Lưu ý FortiGate chỉ thấy lưu lượng đi qua nó: máy cùng VLAN 25 (ví dụ Authentik 10.11.25.40) gọi thẳng VM242 mà không qua FortiGate. Muốn lọc nguồn cả trường hợp đó ngay trên VM242, thêm luật vào chuỗi DOCKER-USER của iptables (chuỗi dành cho luật của quản trị viên, xem mục "Docker and ufw" trong https://docs.docker.com/engine/network/packet-filtering-firewalls/); luật cụ thể cần kiểm lại trên máy thật.
Cấu Hình Backup PBS
Đăng nhập PVE → Datacenter → Backup → Add:
Node : node1
Storage : pbs-primary (pbs01, 10.11.45.17)
Schedule : daily 01:00
VMs : 242
Mode : Snapshot
Retention : mặc định (retention do Prune Job trên PBS quản lý, bài 04 mục 7)
Backup file-level từ trong VM242 (PBS in-VM, bài 04 mục 5.7): job vzdump ở trên chụp cả đĩa VM, còn bước này đưa riêng dữ liệu CA (/etc/step-ca: khóa mã hóa, config/, db/) và file compose (/opt/step-ca) vào namespace vm-step-ca, để khôi phục từng file mà không phải dựng lại VM. Token vm-backup@pbs!step-ca và namespace tạo sẵn theo bài 04 mục 5.7.
# Cài proxmox-backup-client trên Ubuntu 24.04 (cách chuẩn của series): repo client-only pbs-client, suite trixie,
# dạng deb822 + Signed-By. Gói proxmox-backup-client-static là bản tĩnh (chỉ phụ thuộc qrencode), nên không vướng glibc của noble.
# (Cần kiểm lại trên máy thật: apt trên Ubuntu 24.04 nhận repo suite trixie và chạy được binary static.)
wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg -O /usr/share/keyrings/proxmox-archive-keyring.gpg
cat > /etc/apt/sources.list.d/pbs-client.sources << 'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pbs-client
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
apt update && apt install -y proxmox-backup-client-static
# Dừng container trong lúc backup để Badger (/etc/step-ca/db) nhất quán. CA ngừng cấp/gia hạn cert trong ít phút;
# chứng chỉ đã cấp vẫn hợp lệ. Chọn giờ vắng (client gia hạn lại ở lần timer kế tiếp).
cd /opt/step-ca
docker compose stop step-ca
export PBS_PASSWORD='<TOKEN_SECRET>' # secret của token vm-backup@pbs!step-ca
export PBS_FINGERPRINT='<FINGERPRINT>' # fingerprint của pbs01 (bài 04 mục 5.3), cần khi chứng chỉ PBS là tự ký
proxmox-backup-client backup \
step-ca-data.pxar:/etc/step-ca \
step-ca-compose.pxar:/opt/step-ca \
--repository 'vm-backup@[email protected]:syno-primary' \
--ns vm-step-ca
docker compose start step-ca
docker compose ps
/etc/step-ca chứa khóa Root/Intermediate (đã mã hóa), secrets/password và config/; /opt/step-ca chứa docker-compose.yml và secrets/ca_password. Vì thế token backup, namespace vm-step-ca và kho PBS phải được hạn chế quyền như chính khóa CA; nên bật mã hóa phía client của proxmox-backup-client (--keyfile) nếu kho PBS dùng chung với dữ liệu thường. Khôi phục: docker compose stop step-ca, restore hai thư mục về đúng đường dẫn, kiểm tra chủ sở hữu bằng ls -ln /etc/step-ca (phải là 1000 1000), docker compose up -d.
Backup offline Root CA key (quan trọng nhất):
# Tạo thư mục backup (chỉ root đọc được)
mkdir -p /opt/backup-pki
chmod 700 /opt/backup-pki
# Xuất Root CA cert (public, an toàn để backup)
cp /etc/step-ca/certs/root_ca.crt /opt/backup-pki/
cp /etc/step-ca/certs/intermediate_ca.crt /opt/backup-pki/
# Backup encrypted Root CA private key (CHỈ lưu offline, USB hoặc vault)
# Private key đã được mã hóa bằng mật khẩu ở /opt/step-ca/secrets/ca_password (bản sao: /etc/step-ca/secrets/password); lưu mật khẩu RIÊNG với file khóa
cp /etc/step-ca/secrets/root_ca_key /opt/backup-pki/root_ca_key.enc
# SAO CHÉP /opt/backup-pki/ RA USB / OFFSITE STORAGE
Xử Lý Sự Cố (Troubleshooting)
step-ca không khởi động:
cd /opt/step-ca
docker compose ps # Exit / Restarting / (unhealthy)?
docker compose logs --tail=50 step-ca
# Thường gặp: sai mật khẩu, file permission (chủ sở hữu /etc/step-ca khác 1000), port đã dùng
# Kiểm tra port 9000 (docker-proxy phải đang giữ cổng)
ss -tlnp | grep 9000
# Trạng thái healthcheck gần nhất
docker inspect step-ca --format '{{json .State.Health}}'
# Chạy thử foreground để xem lỗi
docker compose stop step-ca && docker compose up step-ca # Ctrl+C rồi docker compose up -d
Triệu chứng trong docker compose logs | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
there is no ca.json config file; please run step ca init, or provide config parameters via DOCKER_STEPCA_INIT_ vars | Thiếu DOCKER_STEPCA_INIT_NAME/DOCKER_STEPCA_INIT_DNS_NAMES, hoặc bind mount sai (thư mục host trống/khác /etc/step-ca) | Kiểm tra environment: và dòng volumes: trong docker-compose.yml, ls /etc/step-ca/config/ca.json |
permission denied khi ghi /home/step/... hoặc mở ca.json/db | Thư mục host do root sở hữu (ví dụ do Docker tự tạo) hoặc sai uid | chown -R 1000:1000 /etc/step-ca rồi chmod 755 /etc/step-ca /etc/step-ca/certs, khởi động lại container |
Lỗi đọc/giải mã khóa intermediate_ca_key (thông báo thường có chữ decrypt hoặc password; nguyên văn cần kiểm lại trên máy thật) | Mật khẩu trong /etc/step-ca/secrets/password không khớp khóa | Đặt lại đúng mật khẩu đã lưu ở Bước 4, quyền 600, owner 1000 |
operation not permitted ngay khi exec step-ca | Tùy chọn no-new-privileges không tương thích môi trường của bạn (cần kiểm lại trên máy thật) | Bỏ security_opt trong compose rồi docker compose up -d |
Container unhealthy nhưng curl -k .../health từ host vẫn ok | extra_hosts bị xóa nên step ca health trong container phân giải sai tên | Khôi phục dòng extra_hosts: step-ca.hoatranlabs.local:127.0.0.1 |
Cert bị từ chối (certificate not trusted):
# Kiểm tra Root CA đã được trust chưa
cat /etc/ssl/certs/hoatranlabs-root.pem
# Nếu rỗng: chạy lại distribute-root-ca.sh
# Verify cert chain
openssl verify -CAfile /usr/local/share/ca-certificates/hoatranlabs-root.crt \
/opt/authentik/certs/authentik.crt
# Kết quả mong đợi: /opt/authentik/certs/authentik.crt: OK
ACME certificate request thất bại:
# Kiểm tra ACME endpoint
curl -sk https://step-ca.hoatranlabs.local:9000/acme/acme/directory | python3 -m json.tool
# Kiểm tra provisioner ACME tồn tại (chạy trong container, giống Bước 6)
docker exec step-ca step ca provisioner list
# Thiếu "acme": thêm lại bằng `docker exec step-ca step ca provisioner add acme ...` + `docker kill -s HUP step-ca` (Bước 6)
# Xem log CA lúc client xin cert
docker compose -f /opt/step-ca/docker-compose.yml logs --tail=50 step-ca
Proxmox báo lỗi khi pvenode acme cert order (bài 09):
| Triệu chứng | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
certificate verify failed / unable to get local issuer certificate khi đăng ký account | Node chưa tin Root CA | Chạy distribute-root-ca.sh (Bước 9) trên node, kiểm tra curl https://step-ca.hoatranlabs.local:9000/health không cần -k |
Order invalid, challenge http-01 timeout/connection refused | step-CA không vào được cổng 80 của node (FortiGate hoặc firewall node), hoặc DNS của container step-ca (không đọc /etc/hosts của VM242) không phân giải nodeN | Từ VM242: curl -v http://node1.hoatranlabs.local/ (kết nối được là đủ); trong container: docker exec step-ca getent hosts node1.hoatranlabs.local; mở policy tcp/80 VLAN 25 → VLAN 45 |
acme: provisioner not found / 404 ở Directory URL | Sai tên provisioner trong URL | Dùng đúng https://step-ca.hoatranlabs.local:9000/acme/acme/directory; kiểm tra bằng docker exec step-ca step ca provisioner list |
| Cert đã cấp nhưng trình duyệt vẫn cảnh báo | Trình duyệt/máy khách chưa tin Root CA | Cài root_ca.crt vào máy khách (GPO, hoặc import thủ công) |
Cert sắp hết hạn không tự renew:
# Kiểm tra timer
systemctl list-timers | grep renew-cert
# Chạy renew thủ công
/usr/local/bin/renew-cert-authentik.sh
# Kiểm tra thời hạn cert còn lại
step certificate inspect /opt/authentik/certs/authentik.crt --short
Checklist Hoàn Thành
- VM242 tạo thành công (Ubuntu Server 24.04 LTS), IP 10.11.25.42/24, VLAN_SEC tag=25
- Docker Engine từ repo
download.docker.com(suite noble) + Compose plugin (docker --version,docker compose version);systemctl is-enabled dockerbáoenabled - step CLI 0.31.0 cài từ gói
.debtrên host (step version); imagesmallstep/step-ca:0.30.2đã pull, ghim tag trong compose (docker exec step-ca step-ca version); không còn dùng step-ca 0.27.4 (CVE-2025-44005) - Root CA khởi tạo thành công tại /etc/step-ca/ (bind mount của container, owner 1000:1000);
certs/*.crtđọc được từ host (644) - Root CA fingerprint đã ghi lại và lưu an toàn
- Root CA password lưu trong vault/offline;
/opt/step-ca/secrets/ca_passwordquyền 600, không có mật khẩu trong compose; log khởi tạo đã xóa (up -d --force-recreate) - Container
step-cachạy ổn định (docker compose psbáoUp ... (healthy)),restart: unless-stopped, giới hạn log json-file 10m x 5 - ACME provisioner
acmecó trong ca.json (DOCKER_STEPCA_INIT_ACME);https://step-ca.hoatranlabs.local:9000/acme/acme/directorytrả về JSON - CA health check trả về {"status": "ok"}
- Root CA cert phân phối đến tất cả VM (update-ca-certificates)
- TLS cert cấp cho Authentik, Harbor, Gitea thành công
- Auto-renew systemd timer chạy trên từng VM có cert
- node_exporter 1.12.1 chạy, Prometheus scrape được
- (Làm bài 09) Node Proxmox tin Root CA, step-CA vào được cổng 80 của node,
pvenode acme cert orderbáoTask OK - DNS: step-ca.hoatranlabs.local, pki.hoatranlabs.local trỏ đúng IP
- Firewall cho phép port 9000 từ tất cả VM nội bộ
- Backup PBS định kỳ cho VM242 (job vzdump +
proxmox-backup-clientcho/etc/step-cavà/opt/step-ca, namespacevm-step-ca) - Root CA private key backup offline (USB/vault)
Phụ Lục: Phương Án Thay Thế — Cài Gói .deb + systemd (Không Dùng Docker)
Dùng khi VM242 không được phép cài Docker, hoặc khi muốn PKI không phụ thuộc Docker daemon (chạy trong LXC không đặc quyền cũng theo cách này). Dữ liệu vẫn ở /etc/step-ca nên client, các bài khác và backup không đổi; khác nhau ở cách chạy, chủ sở hữu thư mục và đường dẫn ghi trong ca.json.
| Việc | Docker (cách của bài) | Gói .deb + systemd |
|---|---|---|
| Chạy / dừng | docker compose up -d / docker compose stop step-ca | systemctl enable --now step-ca / systemctl stop step-ca |
Nạp lại ca.json | docker kill -s HUP step-ca | systemctl reload step-ca |
| Restart | docker compose restart step-ca | systemctl restart step-ca |
| Xem log | docker compose logs step-ca | journalctl -u step-ca |
| Lệnh quản trị CA | docker exec step-ca step ... --ca-config /home/step/config/ca.json | sudo -u step env STEPPATH=/etc/step-ca step ... --ca-config /etc/step-ca/config/ca.json |
| Xem phiên bản | docker exec step-ca step-ca version | step-ca version |
Chủ sở hữu /etc/step-ca | uid:gid 1000:1000 | user hệ thống step |
| Mật khẩu CA | /etc/step-ca/secrets/password (từ Docker secret) | /etc/step-ca/password.txt |
| Nâng cấp | đổi tag image, docker compose up -d | apt install ./step-ca_<phiên bản>-1_amd64.deb |
Cài mới bằng gói .deb (thay cho phần Docker của Bước 2–5; vẫn cài step CLI 0.31.0 như Bước 3 nhưng bỏ docker pull, và bỏ Bước 4 vì mật khẩu tạo ở đây):
# Gói step-ca đặt /usr/bin/step-ca và KHÔNG tạo user `step`, KHÔNG kèm unit systemd: tạo user và unit bên dưới
useradd --system --no-create-home --shell /bin/false step
install -d -o step -g step -m 755 /etc/step-ca
STEP_CA_VERSION="0.30.2"
cd /tmp
wget "https://github.com/smallstep/certificates/releases/download/v${STEP_CA_VERSION}/step-ca_${STEP_CA_VERSION}-1_amd64.deb"
apt install -y "./step-ca_${STEP_CA_VERSION}-1_amd64.deb"
step-ca version
( umask 077; openssl rand -base64 32 | tr -d '\n' > /etc/step-ca/password.txt )
chown step:step /etc/step-ca/password.txt
# STEPPATH=/etc/step-ca để init tạo certs/, config/, secrets/, db/ tại đó. Không dùng --root/--key (chỉ dành cho root CA đã có sẵn)
sudo -u step env STEPPATH=/etc/step-ca step ca init \
--name "HoatranLabs Internal CA" \
--dns "step-ca.hoatranlabs.local" \
--dns "10.11.25.42" \
--address ":9000" \
--provisioner "[email protected]" \
--password-file /etc/step-ca/password.txt \
--deployment-type standalone \
--acme
chmod 755 /etc/step-ca/certs
chmod 644 /etc/step-ca/certs/*.crt
cat > /etc/systemd/system/step-ca.service << 'EOF'
[Unit]
Description=Smallstep Certificate Authority
Documentation=https://smallstep.com/docs/step-ca
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=step
Group=step
Environment=STEPPATH=/etc/step-ca
ExecStart=/usr/bin/step-ca /etc/step-ca/config/ca.json \
--password-file /etc/step-ca/password.txt
ExecReload=/bin/kill --signal HUP $MAINPID
Restart=on-failure
RestartSec=5s
# Security hardening
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/etc/step-ca
ProtectHome=yes
PrivateTmp=yes
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now step-ca
systemctl status step-ca
Từ Bước 6 trở đi mọi thứ giống bài, chỉ thay lệnh theo bảng trên (claims sửa trên /etc/step-ca/config/ca.json rồi systemctl reload step-ca).
Chuyển đổi giữa hai cách (cần kiểm lại trên máy thật): trong container STEPPATH là /home/step nên config/ca.json và config/defaults.json ghi đường dẫn tuyệt đối /home/step/...; bản .deb dùng /etc/step-ca/.... Khi chuyển phải đổi đường dẫn trong hai file này và đổi chủ sở hữu thư mục dữ liệu, rồi đối chiếu lại fingerprint root CA (phải không đổi).
# Docker -> .deb + systemd
cd /opt/step-ca && docker compose down
chown -R step:step /etc/step-ca
sed -i 's#/home/step#/etc/step-ca#g' /etc/step-ca/config/ca.json /etc/step-ca/config/defaults.json
cp /etc/step-ca/secrets/password /etc/step-ca/password.txt && chown step:step /etc/step-ca/password.txt && chmod 600 /etc/step-ca/password.txt
# rồi tạo unit systemd như trên (ExecStart dùng --password-file /etc/step-ca/password.txt) và: systemctl enable --now step-ca
# .deb + systemd -> Docker
systemctl disable --now step-ca
chown -R 1000:1000 /etc/step-ca
sed -i 's#/etc/step-ca#/home/step#g' /etc/step-ca/config/ca.json /etc/step-ca/config/defaults.json
install -D -m 600 -o 1000 -g 1000 /etc/step-ca/password.txt /etc/step-ca/secrets/password
install -d -m 755 /opt/step-ca && install -d -o 1000 -g 1000 -m 700 /opt/step-ca/secrets
install -m 600 -o 1000 -g 1000 /etc/step-ca/password.txt /opt/step-ca/secrets/ca_password
# rồi tạo /opt/step-ca/docker-compose.yml như Bước 5 (ca.json đã có nên entrypoint bỏ qua bước init) và: docker compose up -d
Tài Liệu Tham Khảo
- step-ca — cài đặt (có mục Docker; gói .deb, kho apt, tarball): https://smallstep.com/docs/step-ca/installation/
- step-ca — chạy trong Docker (hướng dẫn của Smallstep): https://smallstep.com/docs/tutorials/docker-tls-certificate-authority/
- Image chính thức
smallstep/step-ca(biếnDOCKER_STEPCA_INIT_*, secrets, tag): https://hub.docker.com/r/smallstep/step-ca ; entrypoint của image: https://github.com/smallstep/certificates/blob/v0.30.2/docker/entrypoint.sh ; Dockerfile: https://github.com/smallstep/certificates/blob/v0.30.2/docker/Dockerfile - step-ca — chạy như dịch vụ systemd, user
step, password file (phương án thay thế), nạp lại cấu hình bằngHUP: https://smallstep.com/docs/step-ca/certificate-authority-server-production/ - step-ca — provisioner ACME, claims (thời hạn cert): https://smallstep.com/docs/step-ca/provisioners/
- Docker Engine trên Ubuntu (repo apt, suite noble): https://docs.docker.com/engine/install/ubuntu/
- Docker — packet filtering và firewall (cổng publish bỏ qua
ufw, chuỗiDOCKER-USER): https://docs.docker.com/engine/network/packet-filtering-firewalls/ - Bản phát hành step CLI: https://github.com/smallstep/cli/releases ; step-ca: https://github.com/smallstep/certificates/releases
- Advisory CVE-2025-44005 (ACME/SCEP, vá ở v0.29.0): https://github.com/smallstep/certificates/security/advisories/GHSA-h8cp-697h-8c8p
- Proxmox VE — Certificate Management / ACME (
pvenode acme, gia hạn tự động): https://pve.proxmox.com/pve-docs/chapter-sysadmin.html - Ubuntu Server 24.04 LTS: https://releases.ubuntu.com/24.04/