ocserv 1.1.3 配置参数详解

目标：把 ocserv 1.1.3 的 /etc/ocserv/ocserv.conf 讲透——参数怎么查看与校验、热加载与重启的生效边界、认证/监听/证书/地址路由/会话超时/封禁/隔离九大类的逐项语义与默认值，并给出修改-验证闭环与生产配置模板。全部验证与回显取自 Ubuntu 22.04 + ocserv 1.1.3-1 服务器实测（2026-10-26）。

一、环境信息

• 操作系统：Ubuntu 22.04（jammy），x86_64。
• ocserv 版本：1.1.3-1（Ubuntu 22.04 仓库版；安装过程见《Ubuntu 22.04 安装 ocserv 1.1.3 指南》）。
• 配置文件：/etc/ocserv/ocserv.conf（发行版自带带注释版，安装后即为权威参数清单）。
• 服务端口：8132/TCP+UDP；VPN 地址池：172.31.100.0/24；推送路由：10.89.66.0/24。
• 演示账号：admin / q1w2e3r4（本地密码文件认证）。
• 客户端：OpenConnect v8.20-1（验证参数下发的观测窗口）。

二、前置条件

1. ocserv 已按安装指南装好并 systemctl is-active ocserv 为 active。
2. 具备 root（或 sudo）权限编辑 /etc/ocserv/ocserv.conf。
3. occtl 可用（use-occtl = true，发行版默认已开）：

occtl show status | head -5
Note: the printed statistics are not real-time; session time
as well as RX and TX data are updated on user disconnect

General info:
	Status: online

三、参数查看与修改方式

改参数前先弄清三件事：配置怎么校验、怎么生效、怎么观测。

校验：ocserv -t 解析配置并输出告警，不启动服务。配置正常时无输出、返回码 0（实测）：

ocserv -t -c /etc/ocserv/ocserv.conf >/dev/null 2>&1; echo "rc=$?"
rc=0

写错参数名不会导致失败，只会告警并跳过（实测：追加未知项后）：

warning: skipping unknown option 'foo-bar-option'

⚠️ 注意：值类型错误同样只告警不报错——实测把 max-clients = 128 改成 max-clients = abc 后，ocserv -t 无任何报错、rc=0，该选项按未设置处理。因此每次改动必须用「客户端重连观测 + occtl 查询」双重确认，不能只依赖 ocserv -t。

生效方式：systemctl reload ocserv（SIGHUP 热加载）与 systemctl restart ocserv（重启）的边界是本篇第一道实测。配置文件中 ### All configuration options below this line are reloaded on a SIGHUP. 标记线以下可热加载；标记线以上（auth、端口、证书路径等）只认重启，证书四项（server-cert/server-key/ca-cert/dh-params）例外——文件内容变化时 reload 自动重载。

实测端口参数：先把 8132 改为 8133 并 reload，监听不变；改回 8132 再 reload，监听仍是 8133，证明端口不热加载：

sed -i "s/^tcp-port = 8132/tcp-port = 8133/; s/^udp-port = 8132/udp-port = 8133/" /etc/ocserv/ocserv.conf
grep -n "^tcp-port\|^udp-port" /etc/ocserv/ocserv.conf
84:tcp-port = 8133
85:udp-port = 8133
systemctl reload ocserv
ss -ltnp | grep -c 8132
0
systemctl restart ocserv
ss -ltnup | grep ocserv-main | head -2
tcp LISTEN 0 128 0.0.0.0:8133 0.0.0.0:* users:(("ocserv-main",pid=4204,fd=15))

reload 成功时有明确日志（实测）：

ocserv[4050]: main: reloading configuration
ocserv[4066]: sec-mod: reloading configuration

观测：参数是否真的下发到客户端，用客户端重连输出里的 X-CSTP-* 响应头最直接；服务端用 occtl show user <用户名> 逐会话核对。观测命令：

journalctl -u ocserv --no-pager | tail -20             # 观察重载/认证日志
occtl show users                                       # 在线会话总览
occtl show user admin                                  # 单用户会话明细

四、参数总览

1.1.3 配置文件（含注释）约 660 行，按语义分九类。总览如下（★ 为本篇做了修改-验证闭环的参数）：

💡 技术拓展：auth 这类「多选一/可叠加」的认证后端是 VPN 服务器的核心分叉点，1.1.3 支持的全量后端对比——

后端	配置写法	特点	适用
plain	plain[passwd=/etc/ocserv/ocpasswd]	本地密码文件，ocpasswd 管理，可叠加 otp 一次性口令	小团队、无外部身份设施
pam	pam[gid-min=1000]	复用系统 PAM（本地用户/LDAP 经 PAM）	与系统账号体系一致
radius	radius[config=...,groupconfig=true]	对接 FreeRADIUS 等，可回传组与计费	企业已有 RADIUS
certificate	certificate	客户端证书认证，用户名取自证书 DN 的 OID	高安全、免密
gssapi	gssapi[keytab=...,require-local-user-map=true]	Kerberos 票据认证	FreeIPA/AD 环境
oidc（1.2+ 扩展）	—	OpenID Connect 对接（1.1.3 时代以 radius/certificate 组合过渡）	现代 SSO

本文实测环境采用 plain（可复现性最好），并把 certificate 作为加固路径在《ocserv 1.1.3 安全加固指南》实测切换。

五、核心参数分类详解

5.1 认证与账号：auth

auth 决定「谁能登录」。写法为带子选项的字符串，可写多行叠加（叠加=全部通过才放行）。本环境生效值：

auth = "plain[passwd=/etc/ocserv/ocpasswd]"

密码文件每行一条，格式 用户名:组名列表:哈希，由 ocpasswd 生成（实测文件内容）：

admin:*:$5$n6zo9hgYmCEbwPC4$peVBbkh7acoRC53pxAgLNr6A6nQNAiexqUbAfGVw9tB

中间的 * 为组占位（无组）。认证失败的表现与服务端日志（实测，错误口令场景）：

worker[admin]: 10.89.65.20 failed cookie authentication attempt

修改-验证闭环：auth 位于不可热加载段，改后必须 restart。实测把 plain 换成 certificate 再换回（完整实验见《ocserv 1.1.3 安全加固指南》），每次 restart 后用 journalctl -u ocserv --no-pager -o cat 确认主认证方法已切换：

note: vhost:default: setting 'plain' as primary authentication method

要点：enable-auth 是「替代性认证」（任一通过即可），与叠加式 auth 语义不同；acct 是计费后端（radius/pam），仅一个。

5.2 监听与端口：tcp-port / udp-port

ocserv 在同一端口号上同时监听 TCP（控制通道）与 UDP（DTLS 数据通道）：

tcp-port = 8132
udp-port = 8132

默认 443。与 HTTPS 服务共用 443 的合法性来自协议设计（认证通道即标准 HTTPS）；本环境因 443 另有他用改为 8132。双监听核对（实测）：

ss -ltnup | grep ocserv-main
udp   UNCONN 0      0            0.0.0.0:8132       0.0.0.0:*    users:(("ocserv-main",pid=3272,fd=7))
tcp   LISTEN 0      1024         0.0.0.0:8132       0.0.0.0:*    users:(("ocserv-main",pid=3272,fd=3))

修改-验证闭环：见三章——改端口必须 restart（reload 不生效实测：conf 回改 8132 后 reload，ss -ltnp | grep -c 8132 仍为 0）。listen-host 可把监听限制到指定 IP；listen-clear-file 提供明文 HTTP 套接字入口（给前置反向代理用，与证书认证互斥）。

5.3 证书与 TLS：server-cert / server-key / ca-cert / tls-priorities

server-cert = /etc/ocserv/certs/server-cert.pem
server-key = /etc/ocserv/certs/server-key.pem
ca-cert = /etc/ocserv/certs/ca-cert.pem
tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-RSA:-VERS-SSL3.0:-ARCFOUR-128"
cert-user-oid = 0.9.2342.19200300.100.1.1

• server-cert/server-key：服务器证书与私钥；证书文件可放排序证书链，且支持内容变化自动重载（不停机换证书，官方注释明示；换私钥则可能造成重载窗口期握手失败）。
• ca-cert：校验客户端证书的 CA（certificate 模式必配，plain 模式也保留该文件位置）。
• tls-priorities：GnuTLS 优先级串。默认串禁用了 SSL3.0 与 ARCFOUR-128；收紧写法（禁 TLS1.0/1.1）与握手级实测（gnutls-cli 强制旧版本握手被拒）见《ocserv 1.1.3 安全加固指南》。
• cert-user-oid：certificate 模式下从客户端证书 DN 中取用户名的 OID，0.9.2342.19200300.100.1.1 即 UID；实测证书认证时用户名 admin 即取自客户端证书的 uid 字段。

修改-验证闭环（观测客户端实际协商）：客户端重连输出直接给出 ciphersuite 与版本（实测，收紧前后均为 TLS1.3 协商）：

Connected to HTTPS on 10.89.65.10 with ciphersuite (TLS1.3)-(ECDHE-SECP256R1)-(RSA-PSS-RSAE-SHA256)-(AES-256-GCM)

💡 技术拓展：tls-priorities 用 GnuTLS 优先级串表达「允许什么」，常用片段对比——

片段	含义	取舍
NORMAL	GnuTLS 默认全集（含 TLS1.0/1.1）	兼容最好，安全最弱
%SERVER_PRECEDENCE	以服务器顺序为准协商	服务端收紧的前提
%COMPAT	关闭部分严格 TLS 行为以兼容老客户端	与 AnyConnect 老客户端共存
:-VERS-TLS1.0:-VERS-TLS1.1	显式禁用旧版本 TLS	现代基线，老客户端会被拒
:-RSA	禁用静态 RSA 密钥交换	强制前向安全

本文实测采用 NORMAL:%SERVER_PRECEDENCE:%COMPAT:-RSA:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1（兼顾兼容与收紧，逐次握手实测见加固篇）。

5.4 客户端地址与路由：ipv4-network / dns / route

ipv4-network = 172.31.100.0
ipv4-netmask = 255.255.255.0
dns = 8.8.8.8
dns = 1.1.1.1
route = 10.89.66.0/24
default-domain = vpn.corp.internal
predictable-ips = true
device = vpns

• ipv4-network+ipv4-netmask：VPN 地址池，客户端从这里拿 IP（实测 admin 分到 172.31.100.165）。写法也支持 CIDR 形式（官方注释：ipv4-network = 192.168.1.0/24）。
• dns：多行多个；设了 route = default（全隧道）时默认连 DNS 一起隧道（tunnel-all-dns）。
• route：split-include 路由，多行多条，客户端只把命中这些网段的流量送进隧道；no-route 是其反向排除。
• predictable-ips = true：同用户尽量复用同一 VPN IP，便于审计对账。
• device = vpns：服务端 tun 设备名前缀（在线会话对应 vpns0、vpns1…，occtl show users 可见）。

修改-验证闭环（实测，改完 ocserv -t 通过后 reload，客户端重连）：

sed -i "s/^keepalive = 300/keepalive = 120/; s/^dpd = 60/dpd = 30/; s/^idle-timeout = 1200/idle-timeout = 1800/" /etc/ocserv/ocserv.conf
sed -i "s/^dns = 8.8.8.8/dns = 9.9.9.9/; /^dns = 1.1.1.1/d" /etc/ocserv/ocserv.conf
sed -i "s|^route = 10.89.66.0/24|route = 10.89.66.0/24\nroute = 10.89.65.0/24|" /etc/ocserv/ocserv.conf
ocserv -t -c /etc/ocserv/ocserv.conf >/dev/null 2>&1; echo "rc=$?"
rc=0
systemctl reload ocserv

客户端重连后逐项见到新值（实测回显，节选）：

X-CSTP-DNS: 9.9.9.9
X-CSTP-DPD: 30
X-CSTP-Keepalive: 120
X-CSTP-Idle-Timeout: 1800
X-CSTP-Split-Include: 10.89.66.0/24
X-CSTP-Split-Include: 10.89.65.0/24
Configured as 172.31.100.165, with SSL + LZ4 connected and DTLS + LZ4 connected

验证结论：dns/dpd/keepalive/idle-timeout/route 全部位于热加载段，reload 即可生效，客户端重连即拿到新值，与端口参数形成对照。

5.5 客户端限制与会话超时：max-clients / max-same-clients / cookie

max-clients = 128
max-same-clients = 1
keepalive = 120
dpd = 30
idle-timeout = 1800
mobile-idle-timeout = 1800
auth-timeout = 240
cookie-timeout = 300
rekey-time = 172800
rekey-method = ssl

• max-clients：全服务器并发上限；max-same-clients：同一账号并发上限（默认 2，加固建议 1）。
• keepalive/dpd/mobile-dpd：保活与死链检测秒数（DPD 过短会误杀弱网用户，过长则 NAT 表项老化掉线）。
• idle-timeout/mobile-idle-timeout：无流量自动断开阈值（移动端单独一档，按请求头 X-AnyConnect-Identifier-Platform 识别）。
• cookie-timeout：认证成功后的会话 cookie 有效期；实测认证响应头里 Set-Cookie: webvpncontext=...; Max-Age=300 与该值一一对应（300 秒）。
• rekey-time/rekey-method：密钥重协商周期（默认 48 小时）与方式（ssl=通道内重握手；new-tunnel=重建隧道，仅兼容问题客户端用）。

修改-验证闭环（实测 max-same-clients = 1 后 reload，同账号第二个连接被拒）：

sed -i 's/^max-same-clients = 2/max-same-clients = 1/' /etc/ocserv/ocserv.conf
grep -n 'max-same-clients' /etc/ocserv/ocserv.conf
181:max-same-clients = 1
occtl reload
Server scheduled to reload

客户端第二路连接直接被服务端拒绝（实测回显）：

Got inappropriate HTTP CONNECT response: HTTP/1.1 401 Cookie is not acceptable
Creating SSL connection failed
Cookie was rejected by server; exiting.

⚠️ 注意：max-same-clients 的拒绝针对「同账号多路会话」——漫游重连（cookie 复用）在旧会话已断开后不受影响；把该值压到 1 前先确认没有多人共用账号的既成事实。

5.6 内建封禁体系：max-ban-score / ban-reset-time

ocserv 对来源 IP 记「分」：错误口令尝试 +10 分、KKDCP POST +1、单纯连接 +1，累计超过 max-ban-score 即封禁 min-reauth-time 秒。相关参数：

max-ban-score = 80
ban-reset-time = 300
min-reauth-time = 300
#ban-points-wrong-password = 10
#ban-points-connection = 1
#ban-points-kkdcp = 1

实测：连续错误口令后服务端记账并封禁（节选）：

main: added 10 points (total 10) for IP '10.89.65.20' to ban list
main: added 10 points (total 20) for IP '10.89.65.20' to ban list

occtl show ip ban points
            IP          score
   10.89.65.20             80
occtl show ip bans
            IP          score                        expires
   10.89.65.20             80               2026-10-26 01:44 ( 5m:00s)

封禁期间客户端连接失败（实测 Failed to connect to host ...），解封即时恢复：

occtl unban ip 10.89.65.20
IP '10.89.65.20' was unbanned

max-ban-score 的取值权衡（本环境从默认 400 调到 80 后又实测与 fail2ban 并用）属于防爆破策略设计，完整对比与推荐组合见《ocserv 1.1.3 安全加固指南》。

5.7 进程与隔离：run-as-user / isolate-workers / use-occtl

run-as-user = nobody
run-as-group = daemon
isolate-workers = false
socket-file = /run/ocserv.socket
use-occtl = true
pid-file = /run/ocserv.pid

• run-as-user/run-as-group：worker 进程降权身份（main/sec-mod 仍以 root 监听特权端口与维护设备）。
• isolate-workers：为每个 worker 启用 seccomp 系统调用过滤与命名空间隔离。官方注释给出的代价口径是传输吞吐约 2% 开销（Linux 3.17.8 实测口径），并提示个别 libc 组合下 worker 可能随机失败。安全敏感场景建议开启并回归验证（与加固篇的服务降权一节呼应）。
• use-occtl：开启 occtl 控制套接字（本篇全部 occtl 命令的前提）。
• chroot-dir：worker 的 chroot 目录（发行版默认注释关闭）。

修改-验证闭环：重启后核对进程身份与套接字（实测）：

ss -lx | grep occtl
/var/run/occtl.socket
journalctl -u ocserv --no-pager -o cat | grep 'sec-mod initialized'
sec-mod: sec-mod initialized (socket: /run/ocserv.socket.b2386950.0)

5.8 每用户/组配置：config-per-user / config-per-group

开启后，/etc/ocserv/config-per-user/<用户名>、/etc/ocserv/config-per-group/<组名> 中的指令覆盖全局值。可覆盖键的全集以配置文件注释为准：dns、nbns、ipv4-network、ipv4-netmask、rx/tx-data-per-sec、iroute、route、no-route、explicit-ipv4、explicit-ipv6、net-priority、deny-roaming、no-udp、keepalive、dpd、mobile-dpd、max-same-clients、tunnel-all-dns、restrict-user-to-routes、user-profile、cgroup、stats-report-time、mtu、idle-timeout、mobile-idle-timeout、restrict-user-to-ports、split-dns、session-timeout。

修改-验证闭环（实测）：开启并给 admin 建用户配置：

mkdir -p /etc/ocserv/config-per-user
sed -i 's|^#config-per-user = /etc/ocserv/config-per-user/|config-per-user = /etc/ocserv/config-per-user/|' /etc/ocserv/ocserv.conf
cat /etc/ocserv/config-per-user/admin
route = 10.10.0.0/16
idle-timeout = 3600
max-same-clients = 2
ocserv -t -c /etc/ocserv/ocserv.conf >/dev/null 2>&1; echo rc=$?
rc=0
systemctl reload ocserv

admin 重连后路由被用户配置覆盖（实测回显）：

X-CSTP-Split-Include: 10.10.0.0/16

⚠️ 注意：本次实测中用户文件里的 idle-timeout = 3600 未体现在该重连会话上（客户端仍收到全局值），说明覆盖矩阵并非所有键都随 reload 即时下发。生产使用每用户配置时，逐键验证为目标键建立「改-重连-看 X-CSTP 头」的闭环，不要假设注释清单全部即时生效。

5.9 兼容与杂项：compression / dtls-legacy / try-mtu-discovery

compression = true
no-compress-limit = 256
cisco-client-compat = true
dtls-legacy = true
try-mtu-discovery = true

• compression：协商 LZS/LZ4 压缩。实测客户端输出 with SSL + LZ4 connected and DTLS + LZ4 connected 即该参数生效的观测点；no-compress-limit 以下的小包不压缩（保 VoIP 时延）。
• cisco-client-compat/dtls-legacy：面向老 Cisco AnyConnect 与 openconnect<7.08 的兼容开关（1.1.3 发行版默认配置已置 true）；新一代 openconnect 用 DTLS-PSK 协商（dtls-psk，默认开）。
• try-mtu-discovery：路径 MTU 探测（依赖 DPD）。实测链路 X-CSTP-Base-MTU: 1500 / X-CSTP-MTU: 1472；若有黑洞网络可显式 mtu = 1420 下调。
• restrict-user-to-routes/restrict-user-to-ports：把客户端限制在授权路由/端口内（调 ocserv-fw 脚本下发 iptables），属于转发面加固，与加固篇网络隔离一节呼应。

六、生产配置模板

适用场景：2 核 4GB 内存的云主机、200 人以内远程接入、本地密码文件认证 + 后续切证书、split 路由到一个内网段。以下模板每项均为 1.1.3 合法键，注释给出取值理由：

# === 不可热加载段（改动需 systemctl restart ocserv）===
auth = "plain[passwd=/etc/ocserv/ocpasswd]"      # 加固阶段切换 certificate，见安全加固指南
tcp-port = 443                                   # 与 HTTPS 共用 443 的场景可保持默认
udp-port = 443
run-as-user = nobody                             # worker 降权
run-as-group = daemon
socket-file = /run/ocserv.socket
server-cert = /etc/ocserv/certs/server-cert.pem  # 证书内容变化可 reload 重载
server-key = /etc/ocserv/certs/server-key.pem
ca-cert = /etc/ocserv/certs/ca-cert.pem

### All configuration options below this line are reloaded on a SIGHUP.
# === 以下为热加载段 ===
isolate-workers = true                           # worker seccomp 隔离，约 2% 吞吐开销（官方口径）
max-clients = 128                                # 4GB 内存建议 ≤256
max-same-clients = 1                             # 同账号单会话
keepalive = 300
dpd = 60                                         # 弱网用户多时可升到 90
mobile-dpd = 300
try-mtu-discovery = true
compression = true                               # 观测点：客户端 'SSL + LZ4 connected'
no-compress-limit = 256
tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-RSA:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1"
auth-timeout = 240
idle-timeout = 1200
mobile-idle-timeout = 1800
min-reauth-time = 300
max-ban-score = 80                               # 内建防爆破计分阈值（默认 400 偏宽）
ban-reset-time = 300
cookie-timeout = 300
rekey-time = 172800
rekey-method = ssl
use-occtl = true
pid-file = /run/ocserv.pid
device = vpns
predictable-ips = true
default-domain = vpn.corp.internal
ipv4-network = 172.31.100.0                      # 地址池避开办公网段与常见家用段
ipv4-netmask = 255.255.255.0
dns = 223.5.5.5                                  # 按企业内网 DNS 调整
route = 10.89.66.0/24                            # 仅推送确实需要的内网段

💡 技术拓展：route 的推送策略本质是「全隧道 vs 分离隧道」取舍——

策略	配置形态	客户端体验	安全性
全隧道	route = default（或注释掉全部 route）	全部流量走 VPN，内网 DNS 全局生效	流量全可审计，服务器带宽压力大
分离隧道	仅写需要的 route = 行	只有内网段走 VPN	私密，但客户端本地流量不经审计
分离+排除	route + no-route 行	大网段进、敏感段出	灵活，规则需逐条验证

本模板采用分离隧道（route = 10.89.66.0/24），理由：远程接入只为访问内网资源，全隧道会无谓消耗服务器带宽。

七、常见问题（FAQ）

Q1：改了参数 reload 没生效？ 先看参数在配置文件的哪一段：标记线以上（auth、端口、证书路径等）必须 restart；以下 reload 即可，但客户端要重连才会拿到新值（在线会话不会被刷新）。实测对照见三章端口实验与 5.4 节超时实验。

Q2：ocserv -t 通过但参数没起作用？ ocserv -t 对未知键只告警（warning: skipping unknown option）、对类型错误静默跳过（实测 max-clients = abc 无报错）。以 journalctl 启动告警 + 客户端 X-CSTP-* 头 + occtl show user 三处交叉确认。

Q3：客户端连上但拿不到期望路由？ 检查顺序：全局 route 行是否被 per-user/per-group 文件覆盖（覆盖生效，实测 5.8）；客户端重连是否用了旧 cookie（断开重连而非漫游续接）；no-route 是否排除了目标段。观测口：X-CSTP-Split-Include 逐行核对。

Q4：max-same-clients = 1 误伤了正常漫游？ 该限制按「同账号活跃会话数」计数，设备端异常断线后旧会话未释放时会顶掉新连接（实测表现为 401 Cookie is not acceptable）。处置：等 cookie-timeout（默认 300 秒）旧 cookie 过期，或管理员 occtl disconnect user <用户名> 清会话后重连。

Q5：同一端口上 TCP 通、UDP（DTLS）不通？ 多数是中间链路只放行了 TCP。观测点：客户端输出 DTLS disabled（实测出现过）表示数据通道回退 TCP；放行同号 UDP 后重连应见 DTLS + LZ4 connected。UDP 长期不可用时可在服务端保持 switch-to-tcp-timeout，让回退更平滑。

八、参考链接

• 上游手册页（参数全集权威来源，1.1.3 对应 ocserv(8)）：安装后本地 man ocserv；在线版 https://ocserv.gitlab.io/www/documentation.html
• 官方仓库（配置示例与样例配置）：https://gitlab.com/openconnect/ocserv
• GnuTLS 优先级串语法：https://www.gnutls.org/manual/html_node/Priority-Strings.html
• 本专栏系列：
  • 《ocserv 1.1.3 介绍与选型指南》
  • 《Ubuntu 22.04 安装 ocserv 1.1.3 指南》
  • 《ocserv 1.1.3 安全加固指南》