FreeIPA 单节点搭建实战：服务端安装与客户端纳管

1. FreeIPA到底解决的是哪一类麻烦事

如果你接手过一台以上的 Linux 服务器，大概率经历过这种场面：每台机器上都有各自的/etc/passwd，加个运维同事要在五台机器上分别useradd，改个密码要挨个passwd，谁离职了还得挨个删账号，删漏一台就是安全隐患。机器少的时候还能忍，一旦上了十几台、几十台，纯手工维护账号就开始变成灾难。FreeIPA 就是冲着这个问题来的——它把这堆分散的账号、认证、授权、策略集中到一个地方统一管理，让"一个账号通行整个内网"这件事真正落地。

我最初接触 FreeIPA 是在一个内部测试环境里，当时手上大概二十来台机器，混着物理机和虚拟机，同事之间共享账号靠的是口头传递密码，sudo 权限靠的是直接往/etc/sudoers里加行。这种状态在审计面前基本是不及格的。后来换成 FreeIPA 之后，账号、认证、主机准入、sudo 规则全都收到一个控制台上，改一次全局生效。这篇先讲单节点的完整搭建过程，把服务端跑起来、把一个客户端纳管进来，这是所有后续操作的地基，地基没打稳，后面做副本、做策略全是空谈。

1.1 先搞清楚 FreeIPA 不是一个软件，而是一整套组件的打包

这是很多人第一次接触 FreeIPA 时最大的误解。你yum install freeipa-server装下来的不是"一个程序"，而是把五个原本各自独立的服务捏在了一起，用一个统一的命令行和 Web 界面来管。理解这个拼图，后面的报错你才知道该去翻哪个日志。

• 389 Directory Server：承担 LDAP 的角色，存用户、组、主机、策略这些结构化数据。它才是真正的"数据库"。
• Kerberos KDC：负责认证，签发票据。你登录时那套"先拿 TGT、再换服务票据"的流程全靠它。
• Dogtag Certificate System：内置 CA，负责签发主机证书、用户证书。Kerberos 和 LDAP 之间的 TLS 通信都依赖它。
• BIND 与自定义插件：DNS 服务，而且做了 IPA 专属的扩展，能自动维护服务发现用的 SRV 记录。
• SSSD：这个装在客户端侧，负责在客户端本地做缓存、对接 Kerberos 和 LDAP，让系统能用上域账号。

这五个组件耦合得非常紧，好处是你装一个命令就把整套跑起来了，坏处是任何一个组件出问题都可能让整个服务瘫掉。比如时间不同步会先搞挂 Kerberos，Kerberos 挂了认证全废，但你表面上看到的现象可能只是"登录不上"。

1.2 Kerberos 的票据机制决定了它对时间有多敏感

Kerberos 认证有个硬性前提：客户端和服务端的时间差不能超过默认的 5 分钟（可调，但强烈不建议调大）。原因是票据里带了时间戳和有效期，服务端要靠时间戳判断票据是否被重放攻击。如果两边时间对不齐，你会看到一个非常经典的报错：

krb5_get_init_creds: Clock skew too great

这个报错翻译过来就是"时钟偏差过大"。很多新手把它当成配置错误，反复改 krb5.conf，其实根子在于 chrony 或 systemd-timesyncd 没配好。所以我在搭建流程里永远把时间同步放在第一步，而不是最后一步。这一步做扎实，后面能省掉至少一半的玄学报错。

1.3 什么场景该上 FreeIPA，什么场景上是杀鸡用牛刀

不是所有环境都值得折腾 FreeIPA。我的判断标准很朴素：

对于纯 Linux 内网，或者以 Linux 为主、少量 Windows 的环境，FreeIPA 的性价比非常高。如果企业里已经有既成的 AD 域，那通常的玩法是让 FreeIPA 和 AD 建立信任关系，两边账号互通，但这个属于进阶话题，得等单节点服务端稳稳跑起来之后再考虑。

2. 动手前的规划：域名、主机名和网络这三样定错了就白搭

FreeIPA 搭建最坑的地方在于，它的域名和主机名在安装那一刻就被写死进了证书、Kerberos 领域和 LDAP 后缀里，装完之后想改基本等于重装。所以我每次动手前都会先花十分钟把这几样东西定死，写在纸上再敲命令。很多"装到一半失败""客户端加不进来"的问题，根子都在规划阶段就埋下了。

2.1 域名和主机名的命名规则不是随便起的

先说域名。FreeIPA 会用它来做两件事：一是 Kerberos 的 realm（领域），二是 LDAP 的 base DN。举例来说，如果你把域名定为example.com：

• Kerberos realm 就是EXAMPLE.COM（大写）
• LDAP base DN 就是dc=example,dc=com
• 服务端主机名最好是ipa.example.com

这里有个非常关键的坑：不要用已经被公网正在使用的真实域名。因为 FreeIPA 会接管这个域名的 DNS 解析，如果你用的是example.com这种真实存在的域，你的 DNS 转发会把内网解析污染，甚至导致这台机器访问不了外网。我一般用一个明确的内部子域，比如ipa.lab.local或者intra.example.internal，一眼就能看出是内网专用。

主机名必须是FQDN（全限定域名），也就是带完整域名的形式，不能是ipa这种短主机名。而且这个 FQDN 必须能被正确解析到本机 IP。Kerberos 的工作原理决定了它对主机名的解析结果极度依赖——它会拿主机名去反查 IP，拿 IP 去反查主机名，任何一环对不上都会报"Server not found in Kerberos database"。

我的习惯是先在/etc/hosts里写死一条，确保本机自己解析自己永远是对的：

# /etc/hosts 关键行示例 192.168.10.10 ipa.example.com ipa

注意顺序：FQDN 在前，短名在后。这个顺序会影响一些程序拿到的规范主机名，弄反了偶尔会遇到诡异问题。

2.2 时间同步是所有认证服务的地基

前面提过 Kerberos 对时间敏感，这里把具体做法说清楚。现代发行版基本都用 chrony 了，配置文件在/etc/chrony.conf。如果你的环境里已经有一台内网 NTP 服务器，让它同步到那台即可：

# 指定内网时间源，iburst 让首次同步更快 server ntp.internal.local iburst # 允许本机作为时间源对外提供服务（可选，服务端需要） allow 192.168.10.0/24 # 本机时间偏差太大时，头几次同步直接步进调整而不是慢慢校准 makestep 1.0 3

配好之后重启服务并立即校时：

systemctl enable --now chronyd chronyc makestep chronyc sources -v # 看到 asterisk 标记的源即为当前使用的时间源

这里提醒一句，服务端和所有客户端必须指向同一套时间源。我见过最离谱的一次排错，是服务端同步到内网 NTP，客户端却还在同步公网池，两边差了将近一分钟，结果客户端kinit一直失败，查了半天才发现是时间问题。

2.3 操作系统和资源选型

FreeIPA 官方主要支持 RHEL 系，所以 Rocky Linux、AlmaLinux、CentOS Stream、Oracle Linux 都能直接dnf装上。Debian/Ubuntu 系也有包，但版本通常滞后，踩坑概率高一些。我自己的首选是Rocky Linux 9 或 AlmaLinux 9，包新、社区活跃、文档全。

资源方面，单节点服务端给到2 核 4G 内存、20G 磁盘是比较舒服的配置。最低 2 核 2G 也能跑，但一旦用户数量上去、又开了 DNS 和 CA，内存会比较吃紧。磁盘主要是 389 Directory Server 的数据库和日志，加上 CA 的证书库，20G 起步、留出增长空间比较稳妥。

提示：主机名（FQDN）在安装前必须已经配好并且能自解析，这一步没做完不要往下走。安装脚本会校验，校验不过会直接退回。

3. 单节点服务端安装：从系统初始化到 ipa-server-install 跑通

规划定好之后，就可以正式动手了。整个安装过程可以拆成四步：系统层初始化、装包、跑安装脚本、验证。每一步我都会说明"为什么这么做"，因为照抄命令很容易，但出了错能不能自己定位，取决于你知不知道这些命令背后在干什么。

3.1 系统层初始化：防火墙、SELinux 和主机名

FreeIPA 需要用到一堆端口，最核心的几个必须放行：

用 firewalld 直接放行，最省事的做法是启用freeipa-4这个预定义服务：

# 设置主机名（永久生效） hostnamectl set-hostname ipa.example.com # 放行 FreeIPA 需要的服务 firewall-cmd --permanent --add-service=freeipa-4 firewall-cmd --permanent --add-service=dns firewall-cmd --reload firewall-cmd --list-all

关于 SELinux，我的建议是保持 enforcing 不要关。FreeIPA 官方提供了完整的 SELinux 策略，正常安装是兼容的。很多人一遇到报错就setenforce 0，结果把真正的根因掩盖了，等上线之后 SELinux 一开又炸。如果确实怀疑是 SELinux 拦的，用ausearch -m avc -ts recent看审计日志，能精确定位到是哪条规则的问题。

# 查看近期 SELinux 拒绝记录，比盲目关闭强得多 ausearch -m avc -ts recent

3.2 安装包与安装脚本参数逐项拆解

装包很简单：

dnf install -y freeipa-server freeipa-server-dns bind-dyndb-ldap

freeipa-server-dns和bind-dyndb-ldap是启用内置 DNS 时才需要，如果你环境里已经有成熟 DNS 且不打算让 IPA 接管，可以不装。

接下来是重头戏ipa-server-install。这个脚本的参数看着多，其实核心就那么几个，我逐个解释：

ipa-server-install \ --realm=EXAMPLE.COM \ --domain=example.com \ --hostname=ipa.example.com \ --setup-dns \ --forwarder=223.5.5.5 \ --forwarder=119.29.29.29 \ --no-ntp \ --ds-password='你的目录管理密码' \ --admin-password='你的admin密码' \ --unattended

• --realm：Kerberos 领域名，习惯用域名大写。
• --domain：DNS 域名，决定 LDAP base DN。
• --hostname：本机 FQDN，必须和hostnamectl设的一致。
• --setup-dns：启用内置 DNS 并自动创建服务发现用的 SRV 记录。如果不启用，后续客户端接入会麻烦很多，得手动维护 SRV 记录。
• --forwarder：DNS 转发地址。IPA 的 DNS 只管自己的域，其他域名查询转发给上游。这里我填了两个公共 DNS 作为示例，实际请换成你环境里可用的上游解析。
• --no-ntp：不让 IPA 去配置 NTP。因为我们前面已经用 chrony 配好了，让它再配一遍容易冲突。如果你环境里没有单独的时间服务，去掉这个参数让 IPA 自己管也可以。
• --ds-password：Directory Server 的目录管理密码（内部用）。
• --admin-password：admin 这个管理账号的密码，是你日常操作要用的那个。
• --unattended：无人值守模式，所有参数从命令行取，不再交互问答。

密码策略方面，默认要求至少 8 位、包含大小写和数字，太简单的密码会被直接拒掉。

3.3 安装过程中你可能遇到的交互和日志

如果你不加--unattended，脚本会一步步问你，包括是否配置 DNS、转发地址填什么、密码设什么。新手第一次装我反而建议先不加 unattended，完整走一遍交互流程，每个问题都看清楚它在问什么，对理解整个体系有帮助。第二次之后再上 unattended 自动化。

安装过程大概会持续几分钟，屏幕上会滚动一堆步骤，比如配置 Directory Server、配置 Kerberos KDC、配置 CA、配置 DNS、重启各服务。任何一步失败，它会明确告诉你卡在哪，日志主要在/var/log/ipaserver-install.log。出问题第一时间去看这个日志的尾部，比在网上瞎搜快得多。

安装成功的标志是最后输出一段The ipa-server-install command was successful，并且给出一堆后续提示。

3.4 安装后验证：三步确认服务端真的活了

装完之后别急着往下走，先做三件验证，确认地基是稳的。

第一，看整体服务状态：

ipactl status

正常的话，Directory、KDC、Kadmin、httpd、named（如果开了 DNS）、pki-tomcatd 这些服务应该全是RUNNING。有任何一个STOPPED，都说明有问题。

第二，拿 admin 去申请一张 Kerberos 票据，验证 KDC 工作正常：

kinit admin klist

输入 admin 密码后，klist应该能看到一张krbtgt/EXAMPLE.COM@EXAMPLE.COM的票据。这一步能过，说明 Kerberos 认证链路是通的，也是后面客户端能加进来的前提。

第三，用 ipa 命令行工具查一下：

ipa user-find admin ipa config-show

能正常返回说明 LDAP 和 API 都活了。另外可以打开浏览器访问https://ipa.example.com/ipa/ui，用 admin 登录 Web 界面看看，图形化管理在批量操作时比命令行直观。

提示：首次kinit admin成功后，票据默认有效期 24 小时，之后需要重新 kinit。这点在跑自动化脚本时要注意，票据过期会导致脚本中途失败。

4. 把一台客户端纳管进来：ipa-client-install 的完整链路

服务端自己跑起来只是第一步，真正体现价值的是把其他机器纳管进来，让域账号能在这些机器上登录。这个过程叫"enroll（登记）"，核心命令是ipa-client-install。我在这一步踩过的坑比服务端安装还多，所以单独拎出来讲。

4.1 客户端接入前的准备

客户端也有几个前置条件，和服务端类似但更简单：主机名要配成 FQDN、时间要和服务端对齐、能解析到服务端的域名。如果服务端开了内置 DNS，把客户端的 DNS 指向服务端即可：

# 客户端 /etc/resolv.conf 或网络配置里指定 nameserver 192.168.10.10

预检一下解析和连通性：

getent hosts ipa.example.com ping -c 2 ipa.example.com

如果解析不到，说明 DNS 链路没通，这时候不要去跑 enroll，先把 DNS 弄明白。客户端纳管失败十有八九是域名解析或时间同步的问题。

4.2 一条命令完成纳管

准备就绪后，一条命令搞定：

ipa-client-install \ --domain=example.com \ --server=ipa.example.com \ --mkhomedir \ --principal=admin \ --password='你的admin密码' \ --unattended

这里的参数值得说说：

• --mkhomedir：强烈建议加上。不加的话，域用户首次登录时家目录不会自动创建，登录会失败或者进到一个没有家目录的别扭状态。
• --principal/--password：用 admin 账号执行登记操作。生产环境更推荐用一次性注册密码，比直接用 admin 密码安全，但入门阶段用 admin 更直观。
• --server：指定服务端。如果 DNS 里 SRV 记录配好了，其实可以省略，让客户端自动发现。

执行过程它会自动化一堆事：配置/etc/krb5.conf、配置 SSSD、配置/etc/sssd/sssd.conf、把主机加入 IPA、申请主机证书、配置 NSS/PAM 走 SSSD。跑完会提示Client configuration complete。

4.3 SSSD 在客户端到底做了什么

很多人纳管完不知道 SSSD 是什么，只知道"账号能登录了"。理解 SSSD 的角色，对排错特别重要。SSSD 是客户端和 IPA 服务端之间的中间层，它干的事主要有三件：

• 身份解析：当系统要查一个用户（比如id zhangsan），NSS 会去问 SSSD，SSSD 从 IPA 的 LDAP 里取数据，缓存到本地。
• 认证代理：用户登录时，PAM 会通过 SSSD 去 Kerberos 拿票据，验证密码。
• 离线缓存：把用户和凭据缓存到本地，即使服务端暂时不可达，已经登录过的用户也能用缓存继续登录（可配有效期）。

所以客户端侧的配置文件主要是两个：/etc/krb5.conf（Kerberos 客户端配置）和/etc/sssd/sssd.conf（SSSD 配置）。排查客户端问题时，先systemctl status sssd，再看/var/log/sssd/下的日志。

4.4 验证登录并让 sudo 策略生效

纳管完成后，先在服务端创建一个测试用户：

kinit admin ipa user-add zhangsan --first=San --last=Zhang --password

这里的--password会提示你交互式输入初始密码。创建完之后，回到客户端验证：

id zhangsan su - zhangsan

如果id能查出用户信息、su能成功登录并且自动进了家目录，那客户端纳管就算彻底跑通了。

sudo 规则是 FreeIPA 的一大亮点：你在服务端定义"哪些用户能在哪些主机上以什么身份执行什么命令"，客户端通过 SSSD 拉到本地生效，完全不用手改/etc/sudoers。入门阶段可以先建一条最简单的规则，让测试用户能全权限 sudo，验证链路通了再精细化。这块内容展开会很长，留到后续文章细讲。

5. 搭建阶段最容易翻车的几个地方

上面给的是理想路径，但实际操作中几乎不可能一次全过。这一节我把多年踩过的坑整理出来，每个都给出"现象、根因、定位办法、解法"，方便你按图索骥。

5.1 主机名解析不一致，安装脚本中途退出

现象：ipa-server-install跑到一半报错，提示主机名无法解析或和预期不符。

根因：多半是/etc/hosts里主机名和 IP 对不上，或者 hostname 设成了短名。脚本会做正反解析校验，任何一环不一致就退出。

定位：跑hostname -f看是不是 FQDN，再getent hosts $(hostname -f)看解析结果。

解法：把/etc/hosts里那条 FQDN 记录改成正确的，hostnamectl set-hostname重设主机名，然后重新跑安装脚本。

5.2 内置 DNS 和现有环境冲突

现象：启用--setup-dns后，这台机器上不了外网，或者内网其他域名的解析全乱了。

根因：IPA 的 BIND 接管了 DNS，如果--forwarder没配好，非本域的查询没有出口，自然解析不了。或者你用的域名和真实公网域名撞了。

定位：在服务端上dig @localhost www.some-public-site.com看能不能出结果，再检查--forwarder的地址是否真的可用。

解法：用可用的上游解析地址，并且坚持用内部专用域名而非真实公网域名。如果环境里本来就有成熟 DNS，宁可不用 IPA 内置 DNS，单独让现有 DNS 去维护 SRV 记录。

5.3 端口没放行导致的"服务活着但客户端连不上"

现象：服务端ipactl status一切正常，但客户端 enroll 失败，或者 enroll 成功却登录不了。

根因：防火墙只放行了部分端口，客户端访问某个必需端口被拦。最常见的是 88/udp 或 464 被漏掉。

定位：客户端上直接测端口连通性，比如nc -vz ipa.example.com 88，逐个端口确认。

解法：确认firewall-cmd --list-all里freeipa-4服务已放行。如果中间有网络设备，也要检查 ACL 是否放行了这些端口。

5.4 证书相关的报错

现象：安装到最后 CA 配置阶段失败，日志里有Certificate operation failed之类的字样。

根因：常见原因是服务端主机名和证书里的名字对不上，或者之前装过一次没清理干净，残留的证书和配置冲突。

定位：看/var/log/ipaserver-install.log里 CA 相关那段，同时ls /etc/pki/pki-tomcat/看有没有残留。

解法：如果是残留问题，彻底清理后重装（见下一节）。如果是主机名问题，回头检查 FQDN 配置。

5.5 重复安装前的彻底清理

现象：装失败了想重装，结果一遍遍失败，报各种"already exists"。

根因：ipa-server-install装到一半失败，会留下部分配置和证书，不会自动清理，直接重跑必然撞车。

解法：用官方提供的卸载脚本彻底清理，然后才能重装：

ipa-server-install --uninstall -U

如果卸载脚本也跑不起来，就得手工清：停掉相关服务、删掉/etc/dirsrv、/etc/pki/pki-tomcat、/var/lib/dirsrv、/var/lib/pki下的相关目录、清掉/etc/krb5.conf和/var/kerberos/krb5kdc。手工清理务必小心，删错会影响系统其他服务。

提示：清理前先确认这台机器没有跑其他依赖 LDAP 或 Kerberos 的服务，避免误伤。

6. 单节点起来之后：日常操作与下一步扩展方向

服务端加客户端跑通，你把 FreeIPA 的最小可用单元搭好了。接下来是把它用起来，以及规划怎么从这个单点走向一个更稳、更完整的体系。这一节我把最常用的日常操作和后续扩展方向理一理，让你心理有张地图。

6.1 用户、组、主机准入和 sudo 规则的日常操作

日常管理所有的命令都以ipa开头，先kinit admin拿到票据再操作。几个高频命令：

HBAC（Host Based Access Control）值得单独说一句：它控制"哪类用户能从哪台主机登录"，是 FreeIPA 相比裸 LDAP 的一大优势。默认有一条allow_all规则放行所有人，生产环境上线前一定要把它禁掉，改成白名单式，否则等于没有准入控制。

6.2 备份与恢复：别等出事才想起

单节点的最大风险就是"单点"。这台服务端一挂，整个内网认证全停。所以哪怕暂时不做副本，备份也必须安排上。FreeIPA 自带备份工具：

# 备份全部（数据 + CA + 配置） ipa-backup # 备份时压缩并静默 ipa-backup --gzip --online # 恢复 ipa-restore /var/lib/ipa/backup/ipa-full-xxxx

备份出来的东西在/var/lib/ipa/backup/下，一定要定期复制到别的地方，放在同一台机器上等于没备份。恢复操作比较重，会重启所有服务，建议在测试环境先演练一遍，别等真出事才第一次用。

6.3 后续可以扩展的几个方向

单节点跑稳之后，有几个自然的演进方向，每一个都够单独写一篇：

• 加副本（replica）：再起一台机器做副本，实现认证服务的高可用，主挂了副本顶上。这是从"能跑"到"敢上生产"的关键一步。
• 与企业现有目录服务建立信任：如果公司已经有 Windows 域环境，可以让 FreeIPA 和它建立信任关系，两边账号互通，避免维护两套账号。这个配置比较讲究，需要单独规划。
• 自动化接入：把ipa-client-install封装成脚本或配置管理模块，新机器上线自动纳管，省去手工操作。
• 集成证书认证：利用内置 CA 签发用户证书，实现基于证书的登录（智能卡之类），安全等级更高。
• 审计与日志集中：把 IPA 的认证日志、操作日志集中收集，满足合规审计要求。

我个人在实际操作中的体会是：别急着追求高可用和大而全，先把单节点加两三个客户端彻底跑顺、把日常的建用户建组操作练熟，再去碰副本和信任。很多人一上来就想一步到位搞双节点加信任，结果基础没打牢，出了问题连锁反应，排查起来手忙脚乱。把这一篇的服务端安装和客户端纳管踏踏实实做完、验证过，你就有了一个可以正常运转的身份管理中枢，剩下的都是在这个地基上往上盖楼的事。下一篇我会把副本部署和日常批量管理的实操细节展开讲，那才是真正让它扛起生产流量的阶段。