RANCID 3.13 常用 CLI 与运维命令详解

目标：整理 RANCID 3.13 日常运维的完整命令面——采集入口 rancid-run、编排层 control_rancid 与并发器 rancid_par、单设备采集 rancid/rancid-fe、clogin 家族登录命令（含全部命令行选项与匹配调试）、Git 版本库日常操作、cron 与 systemd timer 双调度巡检、日志排障套路与版本库回滚。全部命令与回显于 2026-10-28 在 Ubuntu 22.04.5 LTS + RANCID 3.13-1 环境逐条实测。本次实测无真实网络设备，验证链路使用本地模拟设备（脚本位于 /opt/data/quzuo/tmp/rancid/sim_ios.py，监听 telnet 23 端口回放 Cisco IOS 固定输出），真实设备行为以厂商命令为准。安装与参数释义分别见《RANCID 3.13 Ubuntu 22.04 安装指南》与《RANCID 3.13 配置参数详解》。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64
• 软件版本：RANCID 3.13-1（rancid -V 实测输出 rancid 3.13）
• 命令目录：/usr/lib/rancid/bin/（实测 55 个可执行文件；/usr/bin/rancid-run、/usr/bin/clogin 为符号链接）
• 工作区：/var/lib/rancid/，版本库 /var/lib/rancid/CVS/lab（Git 裸仓库），日志 /var/lib/rancid/logs/（Debian 包默认 LOGDIR，另有符号链接 /var/log/rancid）
• 运行用户：rancid（root 会被打包层保护拒绝执行，见 3.4）
• 演示组：lab；演示设备：router1（模拟 Cisco IOS 2911，telnet 23）；示例账号：root/admin，密码 q1w2e3r4

二、命令体系总览

55 个可执行文件按职责分五类，日常运维只需要记住第一类：

调用关系一条线：rancid-run → control_rancid（每组一个）→ rancid_par（并发）→ rancid-fe（类型分发）→ rancid -t <type>（采集）→ clogin 家族（登录）。理解这条链是排障的基础：日志里任何一层报错，都往上一层找触发方。

两个"日常可以直接敲"的入口：rancid-run（触发采集）与 clogin <设备>（直接进设备看状态）。其余命令多数被上层调用，但了解它们的行为对排障至关重要。

三、rancid-run：采集入口

3.1 命令行选项

手册 rancid-run(1) 摘要：

rancid-run [-V] [-c commit_msg] [-f rancid.conf] [-m mail_rcpt] [-r device_name] [group [group ...]]

3.2 实测：单设备采集与自定义提交信息

sudo -u rancid rancid-run -c "D1 test: single device run" -r router1 lab

生成的日志 /var/lib/rancid/logs/lab.20261028.004935 实测全文：

starting: Wed Oct 28 00:49:35 UTC 2026



Trying to get all of the configs.
All routers successfully completed.

[master 314a64b] D1 test: single device run
 1 file changed, 1 insertion(+)
To /var/lib/rancid/CVS/lab
   3a6458b..314a64b  master -> master

ending: Wed Oct 28 00:49:42 UTC 2026

日志自上而下给出：起止时间、采集结果、git 提交（自定义信息 D1 test: single device run 已生效，提交号 314a64b）与推送结果。单设备全流程 7 秒。

3.3 常用运维命令组合

# 全量采集并观察耗时
time sudo -u rancid rancid-run

# 只采集一个组
sudo -u rancid rancid-run lab

# 采集前临时换配置文件做试验
sudo -u rancid rancid-run -f /tmp/rancid-test.conf lab

3.4 root 运行被拒

以 root 身份执行 control_rancid 会直接退出，实测提示：

Do not run $0 as root!

这是 Debian 打包层附加的保护（配置文件属主与版本库都属 rancid 用户）。统一用 sudo -u rancid 前缀执行，cron/timer 条目也已指定 rancid 用户。

四、control_rancid 与 rancid_par：编排与并发

4.1 调用关系

rancid-run 对 LIST_OF_GROUPS 中每个组 fork 一个 control_rancid 子进程；control_rancid 负责组锁、调用 rancid-cvs 建库（首次）、按 PAR_COUNT 启动 rancid_par、汇总 diff 邮件。手动等价调用（排障时绕过 rancid-run 直接跑一组）：

sudo -u rancid control_rancid lab

注意 control_rancid 不带组名时列出用法并退出；它必须从 rancid.conf 的环境（rancid-run 提供）中拿到 BASEDIR 等变量。

4.2 rancid_par

手册定义 rancid_par 为"parallel command processing（并行命令处理）"：从输入文件逐行读取条目并按并发度执行命令，control_rancid 以它实现多设备同时采集。运维中一般不直接调用，但它解释了日志里"一轮内多台设备同时登录"的现象；调整并发用 rancid.conf 的 PAR_COUNT 参数（默认 5，详见《RANCID 3.13 配置参数详解》第七章）。

五、clogin 家族：登录命令

5.1 家族与统一入口 plogin

clogin 覆盖 Cisco IOS/CatOS/Arista/Extreme/Redback 等；每厂商一个同名脚本（jlogin-Juniper、hlogin-HP、flogin-Foundry、nlogin-Netscreen 等，手册列出 23 个互补脚本）。plogin 是多厂商混合环境的统一入口：它读取组的 router.db 与 rancid.types.base/rancid.types.conf，按设备类型自动分发到正确的登录脚本——不用记"哪台设备用哪个 login"。

5.2 命令行选项全表（手册 clogin(1)）

clogin [-autoenable] [-noenable] [-dhiSV] [-m|M] [-c command] [-E var=x]
       [-e enable-password] [-f cloginrc-file] [-p user-password]
       [-s script-file] [-t timeout] [-u username] [-v vty-password] router [...]

5.3 实测：-m 调试 .cloginrc 匹配

排查"某台设备登录凭据不对"时，先用 -m 看 clogin 实际读到了什么（输出格式：查到变量:文件:行号: 匹配的 glob 与值）：

$ clogin -m router1
router1
password:/var/lib/rancid/.cloginrc:2: router1 q1w2e3r4 q1w2e3r4
user:/var/lib/rancid/.cloginrc:1: router1 admin
method:/var/lib/rancid/.cloginrc:3: router1 telnet

与 .cloginrc 三行配置一一对应。若匹配到了错误的通配行（如 * 兜底抢在具体设备之前），从这里一眼可辨。

5.4 实测：单设备执行命令

sudo -u rancid clogin -c "show version | include IOS" router1

回显（节选，完整过程含 Username/Password 交互、enable 提权、terminal length 0）见《RANCID 3.13 配置参数详解》9.4 节。登录失败的排查顺序：clogin -d router1 看每步 expect 匹配 → clogin -m router1 看凭据解析 → 检查 router.db 设备名能否解析（getent hosts router1）。

六、rancid 与 rancid-fe：单设备采集

6.1 rancid 直接采集一台设备

手册 rancid(1) 摘要：rancid [-dlCV] [-t device_type] (-f filename | hostname)。选项（手册释义）：-C 打印将用于采集该设备的登录命令；-d 显示调试信息（实测调试运行会在工作目录额外保留原始设备输出 <设备>.raw）；-l 显示较少的调试信息；-h 用法；-V 版本；-f 从文件读取（离线重解析，不联网）。

实测（在组目录中执行）：

cd /var/lib/rancid/lab && rancid -t cisco router1; echo "exit=$?"

结果：stdout 为空、退出码 0，产出落在当前目录的 router1.new，内容头四行实测：

!RANCID-CONTENT-TYPE: cisco
!
!Chassis type: CISCO2911/K9
!
!Memory: main 487424K/36864K

两个要点：① <设备>.new/<设备>.raw 是 rancid 的工作文件，写在当前工作目录，对目录无写权限就会失败（见 6.3）；② 排查某台设备的解析效果，用 rancid -t cisco -f 已有配置文件 离线跑，不打扰设备。

6.2 rancid-fe：类型解析前端

rancid-fe 读 /etc/rancid/rancid.types.base（与用户自定义 rancid.types.conf），把 设备;类型 解析成对应采集脚本并 exec。实测验证类型解析（从组目录执行）：

cd /var/lib/rancid/lab && rancid-fe "router1;cisco"
# 等价于 exec: rancid -t cisco router1 → 生成 router1.new

参数必须是一个 设备名;类型 字符串（不是 stdin），类型大小写不敏感；未知类型报 unknown router manufacturer for <设备>: <类型>。

6.3 实测排坑：Permission denied

在非组目录（家目录）执行 rancid-fe 时，若存在其他来源遗留的 <设备>.new 文件，实测报错：

Can't open router1.new for writing: Permission denied

处理：确认当前目录可写且无遗留同名文件（ls <设备>.new <设备>.raw），然后从组目录执行。这也解释了 control_rancid 总是 cd 到组目录运行的设计。

七、版本库日常操作（Git）

7.1 查看变更

cd /var/lib/rancid/lab
git log --oneline          # 全部提交（采集/新增/回滚各一条）
git show <提交号>          # 某次变更的 diff
git diff HEAD~3 -- configs/router1   # 某设备近三次采集的差异

实测提交样例（7 条）：

314a64b D1 test: single device run
5172f91 rollback router1 config to previous revision
3a6458b updates
32bd55d updates
83ce3e7 updates
0551223 new router
d6da75c new

提交人为 RANCiD <rancid>。每次设备进库（new router）、配置变化（updates）、人工回滚各产生一次提交。

7.2 回滚的正确姿势（实测）

RANCID 采集以设备现状为准。实测演示：手工把 configs/router1 回退到上一版本并提交（5172f91，删除了 ip route 192.168.20.0 ... 行）——下一轮 rancid-run 采集后，版本库立刻按设备实际配置重新提交（314a64b），该行以 +ip route 192.168.20.0 255.255.255.0 192.168.10.2 回到库里。

cd /var/lib/rancid/lab
git log --oneline -n 3                       # 找到要回退的版本
git checkout <提交号> -- configs/router1     # 取回旧版本文件
git commit -m "rollback router1 config to previous revision"

因此：手工 git 回退只用于对照分析；要真正回滚设备配置，必须在设备上执行回退（如 configure replace/copy 回旧版），版本库会自动记录这次变更。反之，若把设备配置恢复到旧版，下一轮采集的 diff 邮件就会显示整个反向变更。

7.3 初始化与新增组

sudo -u rancid rancid-cvs          # 为 LIST_OF_GROUPS 全部组初始化版本库
sudo -u rancid rancid-cvs lab2     # 只初始化指定组

RCSSYS=git 时它创建 Git 裸仓库并检出工作树；组目录、configs/ 等骨架一并生成。新增组后记得在 router.db 登记设备（见《RANCID 3.13 配置参数详解》第八章）。

八、定时调度运维

8.1 Debian 包自带的 cron 条目

安装即带的 /etc/cron.d/rancid 实测内容：

# run config differ hourly
1 * * * * rancid /usr/bin/rancid-run
# clean out config differ logs
#50 23 * * * rancid find /var/log/rancid -type f -mtime +2 -exec rm {} \;

每小时第 1 分钟以 rancid 用户采集；第二行是日志清理模板（默认注释，建议按需启用——logs 目录会持续增长）。

8.2 systemd timer（本环境实测启用）

本实验环境另配置了 rancid-run.timer（OnCalendar=hourly，随机延迟 300 秒），巡检命令与实测结果：

systemctl list-timers --no-pager | grep rancid

Wed 2026-10-28 01:00:00 UTC 6min left   rancid-run.timer  rancid-run.service

systemctl is-enabled rancid-run.timer   # enabled
systemctl show rancid-run.timer -p Result   # Result=success
journalctl -u rancid-run.service -n 50      # 最近一次触发日志

cron 与 timer 二选一即可，同时启用会出现重复采集与锁竞争。切换时先停用一方（systemctl disable --now rancid-run.timer 或注释 cron 行），观察一轮日志确认无并发后保留另一方。

九、日志与排障命令

9.1 日志文件命名与内容

每次 rancid-run 在 LOGDIR（默认 $BASEDIR/logs，/var/log/rancid 有符号链接）生成 <组名>.<YYYYMMDD>.<HHMMSS>，实测样例：lab.20261028.004935。标准内容五段式：starting 时间 → 采集进度（Trying to get all of the configs. / All routers successfully completed. 或失败清单）→ git 提交摘要 → ending 时间。采集失败时设备名与错误直接列在进度段，这是排障第一现场。

ls -t /var/lib/rancid/logs/ | head -3     # 最新三次运行
grep -E "failed|Error|TIMEOUT|refused" /var/lib/rancid/logs/lab.<最新>.*

9.2 失败样例关键字速查

9.3 设备级巡检三件套

# 1) 组内设备清单与状态
cat /var/lib/rancid/lab/router.db

# 2) 每台设备最近一次成功采集时间（configs 文件 mtime）
ls -lt /var/lib/rancid/lab/configs/ | head

# 3) 手工单点复测：登录与采集各来一次
sudo -u rancid clogin -c "show clock" router1
cd /var/lib/rancid/lab && sudo -u rancid rancid -t cisco router1

十、常见问题

Q1：rancid-run 跑完日志只有 starting/ending，没有采集任何设备？ router.db 为空或全部设备 state 非 up。确认组目录下 cat router.db，状态列必须是 up；再确认 LIST_OF_GROUPS 含该组名。

Q2：rancid-fe 报 Can't open <设备>.new for writing: Permission denied？ 当前目录不可写或存在遗留同名文件。rancid 把 <设备>.new/<设备>.raw 写在当前工作目录，运维手工测试时先 cd /var/lib/rancid/lab（rancid 属主）再执行，用完删除临时文件。

Q3：git 命令报 detached dubious ownership in repository？ 以 root 身份查看 rancid 用户的版本库触发 git 的属主保护。要么全程 sudo -u rancid git ...（推荐），要么一次性 git config --global --add safe.directory /var/lib/rancid/lab。只读巡检用前者，避免污染 root 的 git 配置。

Q4：clogin -c 与 -x 都执行命令，怎么选？ 单条或少量命令用 -c "show clock; show users"（分号分隔）；固定巡检命令集（如十来条 show）存成文件用 -x /path/cmds.txt。手册提醒：-x 文件中的命令不能需要额外输入（copy 之类交互命令不行）；需要设备退出前保存配置时给 -c 加 -S。

Q5：想给不同厂商的设备做临时巡检，逐个找 login 脚本太麻烦？ 用 plogin：它按 router.db 的类型字段与 rancid.types 定义自动分发到对应 login 脚本，混合厂商环境一条命令通吃（plogin -c "show version" dev1 dev2 ...）。

十一、参考链接

• 系统手册（随包安装）：man 1 rancid-run、man 1 control_rancid、man 1 rancid_par、man 1 rancid、man 1 clogin、man 1 rancid-cvs
• 命令目录：/usr/lib/rancid/bin/（55 个可执行文件，ls 可枚举全部登录脚本与采集器）
• 配置释义：《RANCID 3.13 配置参数详解》（rancid.conf 24 参数、router.db、.cloginrc）
• 安装与初始化：《RANCID 3.13 Ubuntu 22.04 安装指南》
• 定位与选型：《RANCID 介绍与选型指南》
• 官方站点：http://www.shrubbery.net/rancid/ （2026-10-28 查询）