Runbook // Quy trình vận hànhopnsense

OPNsense — Vận hành VPN và HA

DOC PATH runbooks/opnsense/vpn-user-operations

Trang này dùng để cấp và thu hồi tài khoản VPN, quản lý certificate, theo dõi cảnh báo và restore cấu hình. Cấu hình hệ thống ban đầu nằm trong Triển khai OpenVPN HA.

1. Nguyên tắc chung

Username phải theo định dạng name-team (ví dụ: user-system, user-devops).
Mỗi user phải có một IP tunnel tĩnh, riêng biệt không trùng với bất kỳ CSO hay Firewall Alias nào khác.
Mọi thay đổi cấu hình đều phải được thực hiện trên OPNsense01 (nguồn cấu hình chính) và đồng bộ sang OPNsense02 qua cơ chế High Availability.
Không bao giờ sao chép hoặc dùng chung file .ovpn, certificate hoặc private key giữa các user.

2. Cấp tài khoản VPN

2.1. Kiểm tra IP tunnel

Trước khi tạo user, xác nhận IP tunnel dự kiến đáp ứng cả 3 điều kiện:

Kiểm tra	Vị trí xác nhận
IP chưa được gán cho user/CSO khác	`VPN > OpenVPN > Client Specific Overrides`
IP chưa nằm trong Firewall Alias của team khác	`Firewall > Aliases`
IP tuân theo quy ước cấp IP của team	Xem trường Description của từng alias

2.2. Tạo Local User và TOTP

Vào menu: System > Access > Users.
Nhấn Add user và điền thông tin:
- Username: theo định dạng name-team.
- Full name / Description: tên đầy đủ của nhân viên.
- Password: theo chính sách mật khẩu nội bộ.
Gán group: Thêm user vào vpn_users_group.
Tạo TOTP: Tại phần OTP/TOTP của user, tạo seed/secret mới và lưu QR code để user thêm tài khoản vào ứng dụng Authenticator.
Nhấn Save / Apply.

2.3. Tạo client certificate

Vào System > Access > Users, tìm dòng user vừa tạo.
Dùng chức năng Search certificates by username hoặc tạo certificate mới cho user đó.

Thiết lập các thông số bắt buộc:

Thông số	Giá trị
Method	`Create an internal Certificate`
Type	`Client Certificate`
Issuer	`OpenVPN-CA`
Common Name (CN)	Phải trùng chính xác username (ví dụ: `user-system`)
Key type	`RSA-4096`
Digest	`SHA512`
Lifetime	`365` ngày

Nhấn Save và kiểm tra certificate vừa tạo: thuộc đúng user, đúng CA (OpenVPN-CA) và có private key.

2.4. Gán IP bằng CSO

Vào VPN > OpenVPN > Client Specific Overrides.
Chọn một CSO làm mẫu và nhấn Clone, sau đó kiểm tra và cập nhật các trường cho user mới:

Trường Giá trị

Common Name Đặt đúng bằng username (ví dụ: user-system)

IPv4 Tunnel Network IP tunnel đã chọn ở mục 2.1 (ví dụ: <VPN_USER_IP>/30)
Nhấn Save / Apply và kiểm tra không trùng IP với CSO khác.

Trường	Giá trị
Common Name	Đặt đúng bằng username (ví dụ: `user-system`)
IPv4 Tunnel Network	IP tunnel đã chọn ở mục 2.1 (ví dụ: `<VPN_USER_IP>/30`)

Netmask trong ví dụ phải được đối chiếu với topology của OpenVPN instance. Với topology subnet, netmask thường phải khớp với tunnel network của instance; không áp dụng /30 cho mọi cấu hình. Dải IP cấp riêng cũng phải nằm trong tunnel network và tránh trùng với pool cấp động. Xem Client Specific Overrides của OPNsense.

2.5. Cập nhật Firewall Alias

Vào Firewall > Aliases.
Mở Alias tương ứng với team của user (ví dụ: VPN_SYSTEM_DEVOPS).
Thêm IP tunnel của user mới vào danh sách.
Nhấn Save → Apply để runtime alias nhận thay đổi ngay lập tức.

2.6. Đồng bộ HA

Trên OPNsense01 vào: System > High Availability > Status.
Nhấn Synchronize and reconfigure all.
Chờ hoàn tất, sau đó kiểm tra trên OPNsense02 rằng các thành phần sau đã xuất hiện đúng:
- Local User và TOTP.
- Group membership (vpn_users_group).
- CSO và IP tunnel.
- IP trong RBAC Alias tương ứng.
- Client certificate.

2.7. Export và bàn giao profile

Vào VPN > OpenVPN > Client Export và chọn đúng Remote Access Server/Instance đang sử dụng.
Trong danh sách certificate/user, tìm đúng dòng của user cần cấp.
Export dạng File Only / inline .ovpn (phù hợp với OpenVPN Connect).
Kiểm tra file export phải chứa client certificate và private key của đúng user đó.
Bàn giao file qua kênh nội bộ bảo mật. Gửi kèm file hướng dẫn đăng nhập.

3. Thu hồi quyền truy cập

Có hai quy trình tùy theo tình huống:

3.1. Ngừng sử dụng VPN — Quy trình A

Luồng thu hồi:

Khi không có dấu hiệu profile hoặc private key bị lộ:

Disable User
→ Disconnect session
→ Delete CSO
→ Remove IP khỏi RBAC Alias
→ Remove group nếu cần
→ Delete Local User
→ Delete Client Certificate
→ Sync HA

Không bắt buộc revoke trong trường hợp offboarding thông thường.

Áp dụng khi: User không còn nhu cầu sử dụng VPN và không có dấu hiệu file .ovpn, private key hoặc certificate bị lộ. Mục tiêu: Thu hồi quyền truy cập và xóa các cấu hình VPN của user.

Bước 1: Disable tài khoản VPN

Vào System > Access > Users, tìm user cần thu hồi và Disable tài khoản.

Mục đích: Chặn ngay xác thực bằng username, password và TOTP. Giữ lại user cho đến khi kiểm tra xong các cấu hình liên quan.

Bước 2: Ngắt phiên VPN đang hoạt động

Vào VPN > OpenVPN > Connection Status, kiểm tra user có đang kết nối không. Nếu có session đang hoạt động, chọn Disconnect.

Bước 3: Xóa CSO và thu hồi IP tunnel

Vào VPN > OpenVPN > Client Specific Overrides, tìm CSO của user (ví dụ: user-system → <VPN_USER_IP>) và Delete.

IP tunnel sau đó có thể đưa trở lại danh sách IP chưa sử dụng để cấp cho user khác.

Bước 4: Xóa quyền RBAC

Vào Firewall > Aliases, mở Alias tương ứng với team (ví dụ: VPN_SYSTEM_DEVOPS), xóa IP VPN của user, sau đó Save → Apply.

Bước 5: Gỡ user khỏi VPN Group

Vào System > Access > Groups, mở vpn_users_group, gỡ user khỏi group và Save.

Bước 6: Delete Local User

Vào System > Access > Users, tìm user và nhấn Delete.

Sau bước này, username, password, TOTP seed và thông tin thành viên của user trong vpn_users_group được xóa.

Bước 7: Delete Client Certificate

Vào System > Trust > Certificates, tìm client certificate có CN = username (ví dụ: CN = user-system) và Delete.

Bước 8: Đồng bộ HA sang OPNsense02

Trên OPNsense01 vào System > High Availability > Status, nhấn Synchronize and reconfigure all.

Trên OPNsense02, xác nhận đã xóa local user, TOTP, group membership, CSO, IP trong RBAC alias và client certificate của user đó.

3.2. Nghi lộ profile hoặc khóa — Quy trình B

Luồng xử lý:

Khi nghi file .ovpn hoặc private key bị lộ, hoặc thiết bị của user bị xâm nhập:

Disable User
→ Disconnect session
→ Revoke certificate
→ Reason: Key Compromise
→ Test profile cũ phải FAIL
→ Tạo certificate mới
→ Export .ovpn mới

Certificate cũ phải giữ trong OpenVPN-CRL cho tới khi hết hạn.

Áp dụng khi xảy ra một trong các tình huống: laptop hoặc thiết bị của user bị mất, file .ovpn bị gửi nhầm hoặc chia sẻ, nghi ngờ private key bị sao chép, thiết bị của user bị xâm nhập hoặc nhiễm malware.

Lý do dùng quy trình riêng: Profile hoặc private key có thể đã nằm ngoài quyền kiểm soát. Phải revoke certificate để OpenVPN từ chối profile cũ dù chưa xóa user.

Bước 1: Disable Local User ngay lập tức

Vào System > Access > Users, Disable user liên quan. Mục đích: chặn ngay xác thực qua Username + Password + TOTP.

Bước 2: Ngắt VPN session

Vào VPN > OpenVPN > Connection Status. Nếu user đang kết nối, chọn Disconnect và xác nhận không còn session đang hoạt động.

Bước 3: Revoke Client Certificate

Vào System > Trust > Revocation, mở OpenVPN-CRL, tìm dòng certificate có CN = username.

Do nghi ngờ private key bị lộ, chọn lý do revoke là Key Compromise, sau đó Save → Apply.

Bước 4: Kiểm tra file `.ovpn` cũ đã bị vô hiệu hóa

Dùng chính file .ovpn cũ thử kết nối. Kết quả kỳ vọng: Connection FAILED.

Nếu vẫn kết nối được, kiểm tra OpenVPN instance tại VPN > OpenVPN > Instances > OpenVPN-RemoteAccess. Phần Trust phải có đầy đủ:

Cấu hình	Giá trị bắt buộc
Certificate Authority	`OpenVPN-CA`
Certificate Revocation List	`OpenVPN-CRL`
Verify Client Certificate	`require`

Bước 5: Xử lý Local User

Tùy theo nhu cầu sử dụng sau này của user:

Trường hợp 1 — User không còn cần VPN: Thực hiện các Bước 3 → Bước 6 của Quy trình A để dọn CSO, RBAC, group và Local User. Không thực hiện bước xóa client certificate của Quy trình A đối với certificate đang bị CRL tham chiếu. Giữ certificate bị revoke và xử lý theo mục Giữ CRL và dọn dẹp sau hết hạn bên dưới; đồng bộ HA theo Bước 6 của quy trình này.

Trường hợp 2 — User vẫn cần tiếp tục dùng VPN: Giữ username, tạo TOTP seed mới và client certificate mới với CN bằng username. Sau đó export file .ovpn mới và bàn giao cho user.

Bước 6: Đồng bộ HA sang OPNsense02

Trên OPNsense01 vào System > High Availability > Status > Synchronize and reconfigure all.

Kiểm tra trên OPNsense02: trạng thái user (disabled hoặc đã xóa), CRL đã cập nhật certificate bị revoke, CSO / RBAC đã cập nhật (nếu có thay đổi), certificate mới / TOTP mới đã đồng bộ (nếu user tiếp tục sử dụng).

Giữ CRL và dọn dẹp sau hết hạn

Trong tình huống nghi lộ private key, không xóa revocation entry. Giữ certificate cũ ở trạng thái REVOKED trong OpenVPN-CRL để OpenVPN tiếp tục từ chối profile bị lộ cho đến khi certificate hết hạn.

Dọn dẹp sau ngày Not After:

Sau khi certificate cũ đã qua ngày Not After, có thể thực hiện dọn dẹp theo thứ tự bắt buộc:

Vào System > Trust > Revocation > OpenVPN-CRL → Remove revocation entry của certificate đã hết hạn → Save / Apply.
Vào System > Trust > Certificates → Delete certificate cũ.

4. Certificate và cảnh báo

Hệ thống dùng certificate để xác thực OpenVPN server và từng user VPN. Mỗi user có client certificate riêng, kết hợp với username/password và mã TOTP để xác thực khi kết nối.

Các điều kiện xác thực:
Client Certificate hợp lệ + Username/Password hợp lệ + TOTP hợp lệ → Cho phép kết nối VPN.

4.1. Vai trò certificate

Certificate	Vai trò	Nguyên tắc vận hành
OpenVPN-CA	CA ký các certificate của OpenVPN	Không xóa hoặc thay đổi tùy ý. Việc thay CA cần có kế hoạch chuyển đổi riêng cho toàn hệ thống.
OpenVPN-Server	Xác thực danh tính OpenVPN server trong TLS handshake	Theo dõi hạn sử dụng định kỳ; khi thay thế phải kiểm thử lại dịch vụ.
Client Certificate	Certificate riêng của từng user	Common Name (CN) = Username; mỗi user sở hữu file `.ovpn` riêng. Quản lý tại `System > Trust > Certificates`.
OpenVPN-CRL	Danh sách certificate bị revoke (Certificate Revocation List)	Dùng khi nghi file `.ovpn` hoặc private key bị lộ, hoặc thiết bị bị mất.

4.2. Cảnh báo hết hạn

Hệ thống Zabbix (https://hardware-monitor.example.com/) tự động giám sát toàn bộ certificate trên OPNsense qua Trust API của OPNsense01. Chỉ thu thập từ OPNsense01 để tránh cảnh báo trùng giữa hai node HA.

Ngưỡng cảnh báo

Thời gian còn lại	Trạng thái	Mức độ (Severity)	Hành động xử lý
> 3 ngày	`OK`	Normal	Theo dõi bình thường
≤ 3 ngày	`Warning`	⚠️ Warning	Zabbix gửi cảnh báo qua Telegram; người vận hành thay certificate
Đã hết hạn	`Warning`	🚨 Problem	Duy trì cảnh báo cho đến khi certificate được thay mới

5. Gia hạn certificate

Luồng gia hạn:

Khi Zabbix cảnh báo certificate còn ≤ 3 ngày:

Tạo certificate mới
→ CN giữ nguyên Username
→ Issuer = OpenVPN-CA
→ Sync HA
→ Export .ovpn mới
→ User import profile mới
→ Test VPN

Không cần thay:

Username
Password
TOTP
CSO
Static VPN IP
RBAC

Sau khi certificate cũ hết hạn, có thể xóa nếu certificate không còn được CRL tham chiếu.

Áp dụng khi: User vẫn đang hoạt động bình thường nhưng Client Certificate sắp hết hạn (còn ≤ 3 ngày) hoặc đã hết hạn.
Không có dấu hiệu lộ thông tin xác thực hoặc sự cố bảo mật.

5.1. Xác định Certificate cần thay thế

Vào System > Trust > Certificates, tìm dòng certificate có CN = Username của user và kiểm tra trường ngày hết hạn (Valid to).

5.2. Tạo Client Certificate mới

Tại System > Trust > Certificates, nhấn Add (hoặc tạo từ trang user).
Thiết lập thông số:
- Method: Create an internal Certificate
- Issuer: OpenVPN-CA
- Type: Client Certificate
- Common Name (CN): Giữ nguyên đúng Username của user
- Lifetime (days): 365 ngày
Kiểm tra certificate mới có serial number mới và private key mới.

5.3. Đồng bộ HA sang OPNsense02

Vào System > High Availability > Status → nhấn Synchronize and reconfigure all.
Trên OPNsense02, xác nhận certificate mới đã xuất hiện trong danh sách.

5.4. Export profile `.ovpn` mới

Vào VPN > OpenVPN > Client Export, tìm đúng dòng certificate mới vừa tạo của user và export file .ovpn mới (dạng File Only / inline).

5.5. Bàn giao và cập nhật trên thiết bị User

Gửi file .ovpn mới cho user qua kênh nội bộ an toàn.
Hướng dẫn user import profile mới vào OpenVPN Connect (xóa hoặc ghi đè profile cũ, không tái sử dụng profile cũ).

5.6. Kiểm tra kết nối

Yêu cầu user thực hiện kết nối và kiểm tra:

Đăng nhập thành công với Username, Password và TOTP hiện tại.
Trạng thái OpenVPN báo Connected.
Nhận đúng địa chỉ Static VPN IP đã cấp.
Phân giải được tên miền nội bộ và truy cập được các tài nguyên server đã cấp quyền.

5.7. Dọn dẹp Certificate cũ

Sau khi profile mới đã hoạt động ổn định và certificate cũ đã qua ngày hết hạn:
Vào System > Trust > Certificates, nhấn Delete để xóa certificate cũ khỏi danh sách.

6. Backup và restore

6.1. Cơ chế backup

Hệ thống OPNsense hiện tự động backup cấu hình trực tiếp lên Synology NAS qua giao thức SFTP.

Mỗi node OPNsense (OPNsense01 và OPNsense02) sử dụng một thư mục backup độc lập trên NAS.
File backup chứa toàn bộ cấu hình OPNsense tại thời điểm backup, ở định dạng XML (config.xml).

OPNsense01 / OPNsense02
        ↓ (SFTP)
Synology NAS
        ↓
Lưu trữ file cấu hình XML

6.2. Luồng restore

Vào:

System → Configuration → Backups

Thực hiện:

Chọn đúng file XML của node
→ Restore
→ Upload file
→ Restore full configuration nếu cần
→ Apply / Reboot nếu hệ thống yêu cầu

Sau restore kiểm tra:

Interface / IP
CARP
pfsync
XMLRPC
OpenVPN
Firewall / NAT
User / Certificate
FRR / Static Route
Zabbix
SFTP backup

Không dùng file backup của OPNsense01 cho OPNsense02 hoặc ngược lại vì mỗi node có cấu hình riêng.

6.3. Các bước restore

Xác định file backup: Chọn đúng file XML của node cần restore, dựa vào tên file và thời điểm backup.
Truy cập giao diện quản trị: Vào System > Configuration > Backups.
Upload file cấu hình: Tại mục Restore, chọn file XML tương ứng từ máy tính và tải lên.
Chọn phạm vi restore: Chọn Full restore nếu cần restore toàn bộ cấu hình.
Xác nhận và áp dụng: Xác nhận restore và đợi OPNsense khởi động lại / áp dụng cấu hình mới.
Kiểm tra sau khi restore:
- Cấu hình interface và IP: WAN, LAN, PFSYNC, XMLRPC; kiểm tra riêng VPN tunnel subnet. Với hệ thống dùng chung interface, đối chiếu mapping HA/LAN đã ghi trong inventory.
- Trạng thái cụm HA (CARP / pfsync).
- Dịch vụ OpenVPN Server & Client Specific Overrides (CSO).
- Firewall Rules & Aliases (NAT, RBAC).
- Danh sách Local User & Certificate.
- Trạng thái Zabbix Proxy / Agent.
- Kết nối SFTP backup lên Synology NAS.

7. Nguyên tắc vận hành HA

Thay đổi cấu hình dùng chung ưu tiên thực hiện trên OPNsense01.
Sau thay đổi lớn, kiểm tra kết quả đồng bộ XMLRPC sang OPNsense02.
Không đồng bộ cấu hình riêng của từng node.
Không dùng chung .ovpn giữa user.
Nếu nghi profile hoặc private key bị lộ, phải revoke certificate liên quan.
Thay certificate trước khi hết hạn.
Kiểm tra backup SFTP định kỳ.
Kiểm thử failover sau các thay đổi lớn liên quan đến HA/OpenVPN.
Chỉ kiểm thử split-brain trên production khi có yêu cầu rõ ràng và kế hoạch kiểm soát tác động.
Sau thay đổi HA/OpenVPN, kiểm tra lại hoạt động giám sát của Zabbix và cảnh báo qua Telegram.