Ubuntu FreeRADIUS EAP-TLS 双向认证配置与排错

简介面向在 Ubuntu 上搭建 802.1X EAP-TLS 双向认证测试环境的网络实验人员与运维学习者这份文档围绕 FreeRADIUS 的部署、证书生成与终端接入验证展开适合需要复现企业级无线认证流程的初中级读者。压缩包共 1 个 docx 文件约 472KB以图文步骤形式记录环境准备、FreeRADIUS 与 OpenSSL 安装、users 和 client.conf 配置、certs 证书生成、EAP 模块参数调整、路由器 RADIUS 对接及 freeradius -X 启动排错等关键环节。内容还涉及 client.p12 证书导入终端后的 EAP-TLS 连接测试可帮助读者理解服务端证书、客户端证书与 CA 根证书之间的对应关系并掌握端口占用、证书权限等常见问题的处理思路。目前已有 2926 人学习适合作为无线认证实验的参考手册。1. 认证一直转圈EAP-TLS 联调最常见的开场白手机连上那个测试 SSID转两圈自己掉回原来的网络电脑上的客户端弹一句「身份验证失败」连个原因都不给。搭 802.1X 的 EAP-TLS 双向认证环境十次里有八次是从这种「没头没尾的失败」开始的。服务端是 Ubuntu 上的 freeradius客户端要装个人证书中间还夹着一台把认证请求转发出去的无线设备任何一环出问题外部表现都是同一句「连不上」。这篇排错笔记按故障场景往前走配置文件路径对不上、证书生成失败、eap 模块参数没生效、freeradius -X起不来、客户端 p12 导入报错每一段都给出能直接抄的命令和该盯的日志行。手上正卡在转圈或者启动报错的可以按顺序往下对。2. 装完发现路径对不上freeradius 版本、目录与两个必改文件装 freeradius 本身只有两条命令真正耗时间的是装完之后你以为在调 A实际跑的是 B。Ubuntu 软件源里的 freeradius 主版本不同配置目录/etc/freeradius/3.0/和/etc/freeradius/4.0/是两个世界后者连配置语法都换了一套。照着旧文档一路cd /etc/freeradius/3.0路径不存在的时候人往往会以为是安装没成功转头重装一遍问题一点没变。所以动手改配置之前先把版本、目录、端口三件事确认掉。2.1 先把安装和服务状态确认掉别在错误的服务上调试在 Ubuntu 上用 apt 装是最省事的顺手把 openssl 和 vim 一起装上后面生成证书、改配置都要用。-y是为了让命令能一口气跑完不至于卡在交互确认上。sudo su # 切到 root后面所有操作都在 root 下做 apt update # 刷新软件源索引 apt-get install -y freeradius openssl vim # freeradius 主程序 证书工具 编辑器装完不要急着改文件先用三条命令摸清现状。版本决定了配置目录端口决定了后面-X启动会不会撞车服务状态决定了你调试的到底是不是同一个进程。freeradius -v # 看主版本号3.x 和 4.x 配置不通用 ls /etc/freeradius/ # 确认实际目录名常见是 3.0 systemctl status freeradius --no-pager # 看服务是否已被自动拉起 ss -lunp | grep -E 1812|1813 # 1812 认证、1813 计费被占会直接启动失败输出里如果freeradius -v显示的是 3.0.x那么配置根目录就是/etc/freeradius/3.0users、clients.conf都躺在这个目录下如果显示 4.x目录和模块名都会变网上抄来的片段大概率跑不通这时候要么按 4.x 的写法重写要么在隔离环境里装 3.0 对齐文档。还有一个容易被忽略的点apt 装完 freeradius 之后systemd 通常已经把服务拉起来了1812 端口处于监听状态。而此时你前台再敲freeradius -X会得到一个「端口被占用」的报错。这个报错和配置错误长得完全不一样但很多人第一次遇到会以为是装坏了。正确的姿势是调试期间先systemctl stop freeradius让前台进程独占端口改一次配置看一次日志。2.2 users 文件认证能不能过往往卡在这一行账号EAP-TLS 是双向证书认证很多人会疑惑都用证书了为什么还要配账号密码原因在于外层 EAP 会话仍然需要一个身份条目来做授权匹配客户端在连接时填的那个「身份」最终要能在服务端的用户文件里找到对应项否则请求在进入 TLS 握手之前就被拒了。这也是为什么有些环境证书全对、就是连不上日志里却看不到任何 TLS 相关内容。改之前先备份这是血泪经验配置改乱了随时能回到原点。cd /etc/freeradius/3.0 cp users users.bak # 改坏了好回滚 tail -5 users # 看文件末尾长什么样确认追加位置在文件末尾追加一行即可。用户名和密码都可以自定义但用户名建议和客户端连接时填的身份保持一致方便对日志。Testing Cleartext-Password : password这一行里有三个细节会反复坑人。:是赋值操作符写成或者:都会让解析行为发生变化引号必须用半角英文引号从聊天工具或文档里复制过来的全角引号在编辑器里看着几乎一样freeradius 解析时直接报未知关键字用户名区分大小写Testing和testing是两个不同的条目。另外这一行不要塞中文注释在引号里面注释放在行首用#。改完不需要重启直接用前台模式启动就能验证freeradius -X # 前台调试模式配置改动即时加载看到Ready to process requests说明配置语法没问题。此时如果客户端发起的连接仍然被拒回到-X的输出里搜Testing或者搜No User-Password之类的关键字能立刻判断是账号没匹配上还是请求根本没到这一步。2.3 clients.conf被忽略的 Access-Request 基本都是这里没配对服务端要认客户端。无线设备把认证请求转发给 freeradius 时源地址必须落在clients.conf声明的范围内共享密钥也要对得上否则请求会被直接丢弃日志里只留一行「unknown client」。这一段的配置错误率极高因为大家习惯抄一个固定 IP而实际环境里设备的地址经常是动态的。client client1 { ipaddr 192.168.1.0/24 # 认这个网段比写死单个 IP 抗地址漂移 secret testing123 # 共享密钥无线设备上必须填一模一样的 require_message_authenticator no # 老设备不支持该字段设 no 兼容性更好 shortname client1 # 日志里显示这个名字方便区分多台设备 nastype other }ipaddr支持单个地址、CIDR 网段和主机名测试环境里强烈建议写成网段原因很实在虚拟机网络改成桥接之后设备从 DHCP 拿到的地址经常变写死一个 IP第二天开机就失效了。secret是明文共享密钥服务端和无线设备两边必须完全一致多一个空格都算不一致。require_message_authenticator no是给旧协议设备留的后路开启校验会让部分设备在第一个报文就被拒。改完之后验证一下有没有写错块grep -n ^client clients.conf # 确认 client 块数量和名字 freeradius -XC # 只做配置检查不启动服务-C是配置检查模式输出Configuration appears to be OK就说明语法过关。这一步能拦住大部分括号不配对、参数名拼错的问题比启动后再看一堆日志高效得多。3. 证书这关过不去make 生成失败、私钥密码不匹配与 client.p12 导入报错EAP-TLS 的核心是证书链服务端要有一份能被自己信任的 CA客户端要有一份由同一个 CA 签发的个人证书。freeradius 的certs目录自带 Makefile一条make就能把整条链生成出来看着很省事实际翻车点集中在三个地方make 没真正执行、私钥密码和 eap 配置对不上、生成的 p12 导入终端之后用不了。这一章把这三段拆开讲。3.1 certs 目录下 make 的产物清单与它真正依赖的东西先确认依赖齐了。Makefile 内部调用的是 openssl 命令行openssl 没装或者版本太老make会在第一步就退出。cd /etc/freeradius/3.0/certs ls -l Makefile # 确认 Makefile 在没有就说明包装得不完整 make # 生成 CA、服务端证书、DH 参数、客户端证书执行成功之后目录里会多出一批文件各自的分工要清楚后面配 eap 的时候才不会填错。文件作用后续用在哪ca.pem/ca.key自签发根证书与根私钥ca_file指向它客户端也靠它验证服务端server.pem/server.key服务端证书与私钥certificate_file/private_key_filedhDiffie-Hellman 参数dh_file没有它 TLS 握手起不来client.p12客户端个人证书含证书与私钥导出到终端安装client.pem/client.key同上的 PEM 形式需要单独分发证书和私钥时用make最常见的「假失败」是第二次执行时什么都不做。Makefile 按时间戳判断依赖文件已存在且比目标新就直接跳过终端上只打印一句make: Nothing to be done for all。看着像成功其实你删掉的某个文件并没有被重新生成。遇到这种情况先ls -l看文件时间戳需要重来就把生成物删掉再 make别在残缺的证书集上继续调。另一个隐蔽问题是 openssl 版本。新版本 openssl 默认拒绝生成 1024 位的密钥和过短的 DH 参数make会在半途报错退出但前面几步生成的 ca.pem 已经落盘了目录看着「有东西」实际证书链是断的。判断方法是逐个文件验证而不是看目录非空就以为成了。openssl x509 -in ca.pem -noout -subject -dates # 看根证书主体和有效期 openssl x509 -in server.pem -noout -subject -dates # 看服务端证书是否由该 CA 签发 openssl dhparam -in dh -text -noout | head -3 # 确认 DH 参数文件可解析三条命令都正常输出才说明证书这一关过了。有效期也要扫一眼测试环境里系统时间被改乱过的情况并不少见证书还没到期却提示无效多半是机器时间不对。3.2 私钥密码 whatever 对不上时的两类报错生成证书时私钥是带密码的默认密码在 Makefile 里写死为whatevereap 配置里的private_key_password必须和它完全一致。这两处只要有一处不同服务启动时就会直接失败报错信息长这样rlm_eap_tls: Failed initializing SSL context rlm_eap_tls: Unable to load private key file /etc/freeradius/3.0/certs/server.key第二行是关键它明确指向私钥加载失败。但「加载失败」有两个完全不同的原因密码错或者权限不够。先用 openssl 单独试一次把密码因素排除掉。openssl rsa -in server.key -passin pass:whatever -noout # 输出 RSA key ok 说明密码对报 bad decrypt 说明密码不是 whatever密码确认无误之后再验证证书和私钥是不是一对。这一步经常被跳过但如果中途重新生成过证书而私钥没换两者就会对不上握手阶段表现为莫名其妙的失败。openssl x509 -noout -modulus -in server.pem | openssl md5 openssl rsa -noout -modulus -in server.key -passin pass:whatever | openssl md5两行输出的 md5 值必须一模一样不一致就说明证书与私钥不匹配只能重新生成一套。权限问题更常见。freeradius 服务以专用低权限用户运行root 用 600 权限生成的私钥它读不到。文档里常见的做法是先chmod 777再chmod o-w实际效果是 770others 位彻底没有权限如果文件属主还是 root服务进程依然读不了。我一般直接改属主比反复调权限位稳妥cd /etc/freeradius/3.0/certs chown freerad:freerad ca.pem dh server.key server.pem chmod 640 ca.pem dh server.key server.pemchown把属主换成服务运行用户640保证属主可读写、同组可读、其他人无权限。改完再启动如果报错从「Unable to load private key」变成别的说明权限这关已经过了。3.3 client.p12 导入设备失败密码、证书链与设备时间client.p12是打包好的个人证书里面同时包含客户端证书、私钥和 CA 链导入时需要输入密码默认同样是whatever。在往终端导入之前先在服务器上验证一遍文件本身没坏openssl pkcs12 -in client.p12 -info -noout -passin pass:whatever # 正常会打印 MAC verified OK 以及证书主体信息这一步报Mac verify error只有两种可能密码不对或者文件在传输过程中被截断。用 U 盘、聊天工具、邮件附件传 p12 都可能出现二进制损坏传完必须校验一次。导不进终端的情况绝大多数不是文件坏了而是三件事没对上。一是密码在导入时被要求输入两次第二次输错直接失败和证书无关。二是设备要求必须同时信任 CA有些系统在连接界面会问「CA 证书」选哪个选「不验证」能过选错或者留空则握手失败——测试环境里如果拿不到 CA就在设备上先装一份ca.pem。三是设备系统时间偏离太多证书不在有效期内表现是「证书无效」而不是「密码错误」看提示措辞能区分。还有一点client.p12里的客户端证书主体名最好和users里配的身份、以及 eap 侧期望的名字保持一致。名字对不上时服务端日志里能看到完整证书链却仍然返回拒绝排查起来非常费劲一开始就对齐能省掉后面几个小时。4. eap 改完没生效default_eap_type 与 tls-config 五个参数的对应关系配置改完、服务也重启了客户端还是失败最容易怀疑的是证书。但相当一部分情况是配置压根没被加载——改的文件不是生效的那份或者参数写在了错误的层级。freeradius 的模块机制是软链接加包含层级错一层参数就静默失效既不报错也不生效属于典型的黑匣子。4.1 mods-enabled 是软链改错文件等于没改进目录先看文件类型这一步能省掉大量无用功。cd /etc/freeradius/3.0 ls -l mods-enabled/eap # 正常输出类似eap - ../mods-available/eapmods-enabled下的文件是指向mods-available的符号链接改mods-enabled/eap实际改的是mods-available/eap两种写法等价。真正的问题在反方向只在mods-available里改了配置但mods-enabled下没有对应的软链模块根本没被启用改多少都不生效。确认模块是否启用用一条命令ls mods-enabled/ | grep -E eap|fileseap和files两个模块必须在列。files负责读users文件eap负责 TLS 握手少任何一个认证流程都走不完整。如果发现缺失用ln -s ../mods-available/eap mods-enabled/eap补上软链再重启。改配置建议先备份再动手eap 文件里花括号嵌套三层删错一个括号整段配置就失效cp mods-available/eap mods-available/eap.bak4.2 tls-common 里五个必查参数eap 模块的配置是一个大块真正决定 TLS 能不能握手的是tls-config tls-common里面的几个路径和密码。下面这份是测试环境里能跑通的最小集合参数值按实际路径调整。eap { default_eap_type tls # 默认认证方式改成 TLS不写会走 MD5 timer_expire 60 # 单次 EAP 会话超时调试时可适当放大 ignore_unknown_eap_types no tls-config tls-common { private_key_password whatever # 必须与生成证书时的密码一致 private_key_file ${certdir}/server.key # 服务端私钥 certificate_file ${certdir}/server.pem # 服务端证书 ca_file ${cadir}/ca.pem # 根证书用于验证客户端 dh_file ${certdir}/dh # DH 参数缺失会导致握手失败 random_file /dev/urandom fragment_size 1024 # 老设备分片能力弱调小更稳 include_length yes # 部分终端要求 TLS 记录带长度字段 check_crl no # 测试环境没有吊销列表关掉避免误判 tls_min_version 1.2 # 太老的终端可临时降到 1.0 } }${certdir}和${cadir}是 freeradius 的预定义变量默认都指向/etc/freeradius/3.0/certs用变量而不是写绝对路径换机器的时候少改几处。private_key_password是整段配置里最容易出错的一项和 3.2 节的私钥密码是同一个值两处必须同步。fragment_size和include_length属于兼容性参数默认值对现代终端没问题但一些嵌入式设备和老系统在握手时会因为分片过大或缺少长度字段直接中断日志里看不出明确原因。测试环境连不上又找不到其他线索时把fragment_size降到 1024、include_length打开往往就通了。tls_min_version同理把它临时降到1.0可以快速判断问题是不是出在协议版本协商上验证完再调回去。4.3 改完先跑配置检查再起服务改完直接-X启动是很多人的习惯一旦配置有语法错误输出会刷满屏幕真正的错误行被淹在后面。更高效的做法是先做静态检查freeradius -XC # 期望输出Configuration appears to be OK-C只解析配置、初始化模块不监听端口几秒钟就能给出结论。这一步过了再进前台调试模式freeradius -X启动过程中重点看两行。一行是Instantiating module eap说明 eap 模块被加载了另一行是最后的Ready to process requests说明服务可以接请求了。如果中间出现rlm_eap_tls开头的报错直接回到 3.2 节按私钥密码和权限排查如果出现Error: Failed parsing configuration之类的提示就是括号或参数名写错用-XC的输出定位到具体行号。5. 避坑启动与联调阶段最容易翻车的五个点这一段是纯粹的踩坑记录按「现象 → 原因 → 解决」写。五个问题覆盖了从服务启动到客户端接入的完整链路遇到对应现象可以直接对号入座。5.1 服务端侧三个权限、端口、配置文件格式现象一改了权限还是报私钥读不了。启动日志里反复出现Unable to load private key file按文档执行了chmod 777再chmod o-w也没用。原因在于777去掉 others 写权限之后是770而 freeradius 以专用用户运行既不是属主也不在属主组里others 位没有权限它照样读不到。解决办法是改属主而不是继续调权限位chown freerad:freerad ca.pem dh server.key server.pem chmod 640 ca.pem dh server.key server.pem。改完用sudo -u freerad cat server.key验证一下服务用户确实能读到再去启动。现象二freeradius -X报端口被占用。输出里出现Failed binding to auth address * port 1812 bound to server default或者Address already in use。原因是 apt 安装后 systemd 已经把服务拉起来前台进程抢不到端口。重启机器确实能让端口释放但没必要先确认占用者再停掉即可ss -lunp | grep 1812 # 看是哪个进程占着 systemctl stop freeradius # 停掉后台实例 systemctl disable freeradius # 测试期间禁止开机自启避免下次又撞调试结束后如果要长期跑记得systemctl enable --now freeradius恢复回来否则重启机器后服务不在客户端又连不上。现象三users 文件加了账号日志里却报未知关键字。典型输出是WARNING: Unknown keyword或者账号明明存在却匹配不上。原因是那一行里混进了全角引号、全角冒号或者不可见的中文空格从网页、聊天窗口复制配置时特别容易带进来编辑器里肉眼几乎分辨不出。解决办法是把那一行删掉用英文输入法重新敲一遍引号、冒号、等号全部半角再用cat -A users | tail -3看一眼行尾如果出现M-oM-M-^I之类的乱码字符说明还有隐藏符号。5.2 客户端侧两个IP 漂移与证书导入现象四证书全对日志里只有一行 unknown client。输出类似Ignoring request to auth address * port 1812 from unknown client后面没有任何 EAP 相关内容。原因不是证书是clients.conf里的ipaddr和实际请求源地址不匹配。虚拟机改成桥接模式之后设备从 DHCP 重新拿地址昨天配的192.168.1.1今天变成了192.168.1.37请求自然被丢弃。解决办法是把ipaddr改成网段192.168.1.0/24或者给无线设备配静态地址改完必须重启服务或者重新-X配置不会热加载。现象五client.p12 导入成功连接时仍提示证书无效。设备上显示「无法验证服务器」或者「证书已过期」。原因通常是三选一导入时把 CA 证书和个人证书搞混了设备上没有可信根设备系统时间被改乱证书落在有效期之外导入时密码输错但系统允许跳过导致私钥实际没进去。解决办法是先openssl x509 -in ca.pem -noout -dates确认有效期再在设备上重新导入一次ca.pem作为信任根最后核对设备时间。三项都排除之后还失败就把服务端-X日志里eap_tls那几行贴出来看日志会明确告诉你卡在证书验证的哪一步。6. 快速定位从一行 Access-Request 到根因的三步走环境跑起来之后真正的效率差距体现在出问题时能不能三分钟内定位。我的习惯是分三步看日志每一步只回答一个问题答不上来就不往下走避免在一堆输出里乱翻。第一步确认请求到底有没有进来。在-X的输出里搜Received Access-Request有这一行说明网络通、共享密钥对、客户端配置也基本正确排查重心可以直接转到 eap 和证书没有这一行问题一定在链路或clients.conf上去查设备地址、密钥、防火墙别浪费时间看证书。第二步确认请求进到了哪个模块。紧跟在Received Access-Request后面的几行会显示expand:和模块名看到files说明在匹配 users 文件看到eap说明进入了 TLS 握手。如果请求在files之后直接Access-Reject就是账号没匹配上如果在eap之后反复出现Access-Challenge循环是握手没完成重点查证书链和私钥。第三步看 TLS 阶段的报错原文。eap_tls相关的错误信息其实相当直白只是藏得深。日志关键字大致含义下一步动作Ready to process requests服务正常启动去客户端发起连接Ignoring request ... from unknown client源地址没匹配上 clients 块核对ipaddr改网段No User-Password/ 找不到用户users 文件没匹配到身份检查用户名大小写和引号SSL_accept failedTLS 握手失败查私钥密码、证书配对、权限eap_tls: ERROR证书链验证不通过确认客户端装的是同一个 CA 签发的证书Failed binding to ... 1812端口被占用停掉后台服务实例再启动除了服务端日志客户端侧的验证也别忽略。Linux 环境下可以直接用命令行发起一次 EAP-TLS 认证把过程日志打到前台比在图形界面里看「连接失败」有用得多wpa_supplicant -i wlan0 -c /etc/wpa_supplicant/test.conf -dd 21 | tee /tmp/eap.log # test.conf 里配置 ssid、key_mgmtWPA-EAP、eapTLS、ca_cert、client_cert、private_key-dd打开详细日志能看到客户端视角的证书校验过程和 TLS 版本协商结果。服务端说握手失败、客户端说证书不被信任两边一对根因基本就锁定了。从那以后我每次搭这类环境都强制走一遍固定顺序freeradius -v看版本、ss -lunp看端口、-XC过配置、-X起服务、再让客户端连。这个习惯救过我很多次尤其是在换机器、换系统版本之后前两步就能挡掉一半的「玄学问题」。希望帮到你。本文还有配套的精品资源点击获取