企业官网建设流程全解析

Wazuh 4.x 到 5.x 如何迁移代理分组与 shared 共享配置？

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh

把 Wazuh manager 从 4.x 升级到 5.0 时，代理分组（agent groups）不能直接沿用：5.0 把 manager 安装路径从/var/ossec/改为/var/wazuh-manager/，并且分组归属不再由 manager 推断，而是由 agent 在注册（enrollment）握手时自行声明。官方没有自动迁移工具，分组配置必须手动从 4.x manager 备份、再恢复到 5.x manager，之后让每个 agent 重新注册才能回到原分组。本文给出这条完整的迁移路径：备份shared/下的分组目录 → 恢复到 5.x → 配置 agent 的分组与注册密码 → 重新注册并验证分组归属，以及注册被拒、agent 落入default分组时的处理办法。

适用前提：你拥有 manager 主机的 root 或终端权限；迁移方式是先在 4.x 上备份分组配置，然后（通常在原主机上）移除 4.x 并全新安装 5.0。

迁移前需要理解的机制变化

理解以下两点，才能知道为什么迁移必须"先恢复分组、再连 agent"：

• 4.x 的分组推断已被移除。早期版本中，manager 可以通过比对 agent 的merged.mg校验和来推断其分组（remoted.guess_agent_group内部选项）。该机制在 Wazuh 5.0 中已被移除。
• 5.0 的分组由注册握手决定。agent 注册时把ossec.conf中<enrollment><groups>配置的分组发给 manager 的注册服务（wazuh-manager-authd），后者校验分组存在后把归属写入global.db。如果声明的分组在 manager 上不存在，注册会被拒绝，agent 无法连接；如果没有配置分组，agent 会落入default分组。
• 归属保存在global.db中，跨 agent 与 manager 重启保留；之后每次 keepalive，manager 从global.db查出分组并编译、下发对应的共享配置。

分组配置的存放位置从/var/ossec/etc/shared/变为/var/wazuh-manager/etc/shared/（相对路径etc/shared/不变，绝对路径变了）。

准备条件

1. root 或终端访问 manager 主机的权限。
2. 停掉所有 agent，并在分组目录恢复完成、每个 agent 的分组配置就绪之前保持停止状态。否则迁移中途重连的 agent 要么落入default分组（未声明分组时），要么注册被拒（声明了尚不存在的分组时）：

# On each agent systemctl stop wazuh-agent

大规模部署可用 Ansible、SSH 循环、MDM、GPO 等编排工具批量执行。

3. 建议在每个 agent 的ossec.conf中预先配置其分组（<enrollment><groups>），注册时随握手发出。文档标注这是推荐做法而非阻塞项——没配置的 agent 之后可以手动分配分组。

步骤 1：在 4.x manager 上备份分组配置

在4.x manager上归档shared/下的分组目录，排除运行时生成的merged.mg：

cd /var/ossec/etc tar -cvzf /tmp/wazuh_groups_backup.tar.gz --exclude='*/merged.mg' shared/*/

shared/*/通配符只匹配分组目录，shared/中的非分组文件（如ar.conf、agent-template.conf）不会被包含。归档里只有各分组定制的agent.conf和你放在分组目录里的其他文件。

如果只迁移部分分组，把shared/*/换成具体目录名（<group-name-1>、<group-name-2>替换为你要迁移的实际分组名）：

cd /var/ossec/etc tar -cvzf /tmp/wazuh_groups_backup.tar.gz --exclude='*/merged.mg' \ shared/<group-name-1>/ shared/<group-name-2>/

务必把这个归档放到能撑过重装的位置（例如主机外部或外部存储），因为接下来移除 4.x 会清掉本机文件。

步骤 2：在 5.x manager 上恢复分组配置

必须在任何 agent 连接 5.0 manager之前完成本步。注册时 manager 会校验声明的分组：agent 带着一个尚不存在的<groups>值注册时，注册会被拒绝、agent 无法连接。（未写<groups>标签的 agent 可以连接，但会落入default。）

安装好 Wazuh 5.0 后，把归档拷回 manager 主机，解压并修正属主：

tar -xvzf /tmp/wazuh_groups_backup.tar.gz -C /var/wazuh-manager/etc/ chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/etc/shared/

验证分组目录已恢复：

ls /var/wazuh-manager/etc/shared/

此时 dashboard 的Agents management -> Groups页面即可看到恢复的分组：

配置有效性检查：恢复的agent.conf必须是 Wazuh 5.0 合法的。4.x 配置中已废弃的选项或已改名的标签会导致共享配置编译失败。继续之前，请对照 Wazuh 5.0 参考文档逐个分组的agent.conf检查，删除或更新不兼容的配置项。

步骤 3：在每个 agent 上确认分组已写入 ossec.conf

在每一个应属于非默认分组的agent上，确认/var/ossec/etc/ossec.conf中已设置分组：

<enrollment> <enabled>yes</enabled> <groups>group-name</groups> </enrollment>

（group-name替换为该 agent 在 4.x 上所属的实际分组名。）

这里有一个容易踩的坑：agent 在 4.x dashboard 上显示某个分组，不代表该分组写在了它的ossec.conf里——有些部署方式下归属只存在于 manager 侧。请以 agent 的ossec.conf为准，不要依赖 dashboard。

如果某台 agent 启动时没有配置分组，它会进入default分组，需要在 agent 重连后手动分配分组（见排查章节）。

步骤 4：配置注册密码，清除旧 key 并启动 agent

从 Wazuh 5.0 起，注册服务要求密码：安装包将 authd 的use_password配置为yes，agent 不提供密码时注册请求会被拒绝。详见 use_password 配置说明。

在启动每台 agent 之前，先从 manager 取出注册密码：

# On the manager sudo cat /var/wazuh-manager/etc/authd.pass

再写到每台 agent 上（<password>替换为上一步读到的实际密码；agent 守护进程以wazuh用户运行，文件必须对该用户可读，所以属主和权限要按下面设置）：

# On each agent echo "<password>" | sudo tee /var/ossec/etc/authd.pass sudo chown root:wazuh /var/ossec/etc/authd.pass sudo chmod 640 /var/ossec/etc/authd.pass

然后清除旧 manager 下发的客户端密钥并启动 agent——分组只在注册握手时发送，还留着旧 key 的 agent 必须重新注册，所以先删掉client.keys（该文件是旧 manager 下发的客户端密钥，删除后 agent 将以全新注册方式重新入组）：

# On each agent rm -f /var/ossec/etc/client.keys systemctl start wazuh-agent

注册时 agent 把配置的分组发给 manager，manager 把归属写入global.db；在下一次 keepalive，manager 编译并下发该分组的共享配置。

如果 agent 声明了 manager 上不存在的分组，注册会被拒绝，agent 日志中会出现：

wazuh-agentd: ERROR: Invalid group: <group>. Unable to add agent (from manager)

处理方式见下一节。

验证分组归属

dashboard 方式：打开Agents management -> Summary，查看各 agent 的分组列：

API 方式：API 需要认证 token，先用你的 API 凭证（默认用户wazuh）向 manager 申请，之后的调用复用；token 会过期，失效时重新申请（<manager-ip>、<user>、<password>替换为实际值）：

TOKEN=$(curl -u <user>:<password> -k -X POST \ "https://<manager-ip>:55000/security/user/authenticate?raw=true")

查询指定 agent 的分组：

curl -k -X GET "https://<manager-ip>:55000/agents?agents_list=<agent-id>&select=group" \ -H "Authorization: Bearer $TOKEN"

以下是迁移文档给出的示例响应（文档示例输出，实际以你的环境为准），其中 001 注册时带分组、002 未配置分组而落入default：

{ "data": { "affected_items": [ {"id": "001", "name": "web-server-01", "group": ["linux-servers"]}, {"id": "002", "name": "web-server-02", "group": ["default"]} ], "total_affected_items": 2, "total_failed_items": 0, "failed_items": [] }, "message": "All selected agents information was returned", "error": 0 }

排查：注册被拒 "Invalid group" 与手动分配分组

场景 A：agent 声明的分组在 manager 上不存在

日志现象为上文提到的ERROR: Invalid group: <group>. Unable to add agent (from manager)，注册被拒、agent 无法连接。三种解决路径任选其一：

方案 1：先恢复分组，再重启 agent。确认该分组的目录已按步骤 2恢复到 manager，然后重启 agent 让它重新注册。

方案 2：手动创建该分组，让 agent 先连上，分组配置稍后再补。dashboard 路径：Agents management -> Groups -> Add new group，填入缺失的分组名并保存；或调用 API（<group-name>替换为实际分组名）：

curl -k -X POST "https://<manager-ip>:55000/groups" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"group_id": "<group-name>"}'

然后重启 agent 重新注册。配置补齐方式：要么按步骤 2 完成该分组的迁移，要么在 dashboardAgents management -> Groups的 Actions 列点铅笔图标（Edit group configuration）手工编辑后保存。

方案 3：从 agent 配置中去掉分组。删除 agentossec.conf里的<groups>标签，让它先进入default分组，再按下面的手动分配流程把它划回正确分组。

场景 B：agent 注册时未配置分组，落入了 default

如果 agent 的ossec.conf里没有分组（注册时未发送），它会在default分组。agent 重连后手动分配即可。

dashboard 路径：Agents management -> Summary，在 Actions 列点...图标，选择Edit groups，在弹窗中输入或从下拉列表选择分组名，保存：

API 方式（<agent-id>、<group-name>替换为实际值）：

# Assign a single agent to a group curl -k -X PUT "https://<manager-ip>:55000/agents/<agent-id>/group/<group-name>" \ -H "Authorization: Bearer $TOKEN"

批量分配可以按分组列出 agent 后循环调用（以下 agent id001 002 003为文档示例值，替换为实际的 agent id 列表）：

for agent_id in 001 002 003; do curl -k -X PUT "https://<manager-ip>:55000/agents/${agent_id}/group/<group-name>" \ -H "Authorization: Bearer $TOKEN" done

手动分配分组后，重启各 agent 或等待下一个 keepalive 周期，manager 才会把更新后的merged.mg推下去。

一个需要注意的细节：分组分配是追加语义，手动分配的 agent 会保留原有的default归属。如果希望它只属于目标分组，可在同一个 Edit groups 弹窗中清除default后保存，或调用 API 移除（以下为文档示例，002与default按实际替换）：

curl -k -X DELETE "https://<manager-ip>:55000/agents/002/group/default" \ -H "Authorization: Bearer $TOKEN"

迁移完成与限制

当所有 agent 都出现在各自的原始分组、API 查询结果与 4.x 时期一致时，迁移完成。两点限制需要记住：5.0 没有任何自动的分组迁移或推断工具，之后新增、调整分组都依赖"manager 上存在分组目录 + agent 注册声明或手动分配"这条路径；恢复的agent.conf若仍含 4.x 废弃选项，共享配置会在编译时失败，需要在 agent 连上前按 5.0 参考文档修正。完整的分步示例与更多截图参见 代理分组迁移指南，manager 主配置（ossec.conf、internal_options.conf等）的迁移另见 Manager configuration migration。

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh