Ubuntu 22.04 安装 Cobbler 指南
Ubuntu 22.04 安装 Cobbler 3.3.10 实测指南:pip 与官方源码构建 deb 双方案部署、systemd 托管 cobblerd、cobbler check 六项逐条修复与排障实录。
Ubuntu 22.04 安装 Cobbler 指南
目标:在 Ubuntu 22.04 服务器上从零安装 Cobbler 3.3.10(官方最新稳定版),覆盖 pip 在线安装与官方源码构建 deb 两种方案、systemd 托管、
cobbler check六项问题的逐条修复与完整验证。全文命令与回显均在 Ubuntu 22.04.5 LTS 实测通过。组件背景与选型对比见 《Cobbler 3.3.10 介绍与选型指南》。
一、环境信息
本文实测环境如下,所有命令与回显均出自该环境:
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS(x86_64,内核 6.8.0-138-generic) |
| 目标软件 | Cobbler 3.3.10(官方最新稳定版,2026-09-18 发布) |
| Python | 3.10.12(jammy 系统自带) |
| Web 服务 | Apache/2.4.52 (Ubuntu) + libapache2-mod-wsgi-py3 |
| TFTP | tftpd-hpa |
| 本机 IP | 10.89.57.2(装机网卡) |
| 专栏关联 | 《Cobbler 3.3.10 介绍与选型指南》 |
安装完成后最终的服务状态实测:
systemctl is-active cobblerd apache2 tftpd-hpa
实测回显:
active
active
active
二、前置条件
本节列出动手安装前必须确认的环境项,避免安装中途踩坑。
-
root 权限:安装、systemd 托管、Apache 配置均需 root,本文全程 root 执行;
-
网络可达:方案 A 需访问 PyPI 与 GitHub(下载官方源码包补配置);方案 B 的构建机需访问 GitHub 与 Debian 软件源,目标机需 Ubuntu 软件源;
-
静态 IP 与主机名规划:Cobbler 是装机服务端,对外服务地址要写进 PXE 配置,务必给本机规划固定 IP(本环境为 10.89.57.2),确认回显:
hostname -I10.89.57.2 -
端口确认:80(HTTP)、69/UDP(TFTP)、25151(cobblerd 本机回环)不被占用:
ss -ltn | grep -E ':80 |:25151 ' ; ss -lun | grep ':69 '实测回显(安装前均无占用,命令无输出即为通过;安装完成后 80 与 69 由 Apache/tftpd-hpa 监听)。
-
软件源可用:
apt-get update正常完成(下面方案 A 第一步即含此验证)。
三、版本选型说明
本节回答"装哪个版本、从哪装",结论先行:Ubuntu 22.04 上安装 3.3.10,选 PyPI/pip 或官方源码构建 deb,Ubuntu 官方仓库没有 Cobbler 包。
3.1 版本现状(实查于 2026-10-22)
版本数据取自 Cobbler 官方 GitHub Releases(查询日期 2026-10-22):
| 版本线 | 最新版本 | 发布日期 | 是否选用 |
|---|---|---|---|
| 3.3.x 稳定线 | 3.3.10 | 2026-09-18 | ✅ 本文目标版本 |
| 3.3.x 历史 | 3.3.9 / 3.3.8 | 2026 年 | 3.3.8 官方标注 defunct,勿用 |
| 4.0.x | 4.0.0b6 | — | ❌ pre-release,不用于生产 |
3.2 Ubuntu 22.04 的获取渠道实测
Ubuntu 官方仓库(实测没有包):
apt-cache search cobbler
实测回显:无任何输出(仓库 main/universe/multiverse 均启用,jammy 没有收录 cobbler)。
PyPI 官方渠道(实测有 3.3.10):
pip index versions cobbler
实测回显:
cobbler (3.3.10)
Available versions: 3.3.10, 3.3.9, 3.3.7, 3.3.6, 3.3.5, 3.3.4, 3.3.3, 3.3.2, 3.3.1, 3.3.0, 3.2.3, 3.2.2, 3.2.1, 3.1.2
关键解读:官方文档"Known packages by distros"只列了 Fedora/CentOS/openSUSE 的发行版包,Ubuntu 侧的官方路径就是 pip 与源码构建 deb,这正是本文的两种方案。
四、方案 A:pip 安装官方最新稳定版(在线,推荐主线)
本方案用 PyPI 官方 wheel 安装 3.3.10 主程序,再从官方源码包补齐 wheel 不携带的系统文件(配置、systemd 单元、日志目录),最后完成 check 收敛。全程约 10 分钟。
4.1 安装系统依赖
Cobbler 的 Python 依赖里有两个包需要现场编译(python-ldap、mod-wsgi),所以要先把编译工具与头文件库装齐;同时把装机周边服务(Apache、TFTP、rsync、xorriso 等)一次装好:
apt-get update
apt-get install -y gcc python3-dev libldap2-dev libsasl2-dev apache2-dev \
apache2 libapache2-mod-wsgi-py3 tftpd-hpa rsync xorriso syslinux pxelinux \
grub-pc-bin grub-efi-amd64-bin grub-efi-amd64-signed shim-signed fence-agents \
createrepo-c logrotate debmirror \
python3-cheetah python3-dnspython python3-netaddr python3-requests \
python3-distro python3-schema python3-gunicorn python3-yaml python3-apt
实测回显(输出节选,末尾触发库与触发器处理):
Processing triggers for man-db (2.10.2-2ubuntu1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
⚠️ 排障实录 1:官方文档建议的
python3-aptsources在 Ubuntu 22.04 中不存在该包名(E: Unable to locate package python3-aptsources,且一条 apt 命令中包名错误会导致整个事务中止)。它对应的模块由python3-apt提供,上面命令已用python3-apt替代。⚠️ 排障实录 2:若跳过
apache2-dev,pip 安装阶段编译mod-wsgi会报subprocess-exited-with-error / metadata-generation-failed(缺 apxs 工具);若跳过libldap2-dev libsasl2-dev,编译python-ldap会连续下载 3.4.8→3.4.4 多个版本反复失败。三个包都装上后,pip install python-ldap实测成功(python3 -c "import ldap; print(ldap.__version__)"输出3.4.4)。
4.2 pip 安装 Cobbler 3.3.10
pip install cobbler==3.3.10
实测回显(输出节选):
Successfully installed cobbler-3.3.10 dnspython-2.8.0 file-magic-0.4.1 mod-wsgi-6.1.1 pymongo-4.18.3
安装位置验证:
which cobbler cobblerd
/usr/local/bin/cobbler
/usr/local/bin/cobblerd
此时 cobbler version 会报缺配置文件(真实回显):
FileNotFoundError: Given path "/etc/cobbler/settings.yaml" does not exist or is a directory.
💡 说明:PyPI 的 wheel 只含 Python 代码,不携带
/etc/cobbler配置、模板、systemd 单元与日志目录——这些在发行版包(RPM/DEB)里由打包脚本布置。这是 pip 方案与发行版包方案的唯一本质差异,下面 4.3、4.4 两节补齐。
4.3 布置配置文件与目录(从官方源码包补齐)
下载官方 v3.3.10 源码包并解压(作为配置与模板的来源):
curl -L -o /root/cobbler-3.3.10.tar.gz https://github.com/cobbler/cobbler/archive/refs/tags/v3.3.10.tar.gz
tar -xzf /root/cobbler-3.3.10.tar.gz -C /root
cd /root/cobbler-3.3.10
按官方 setup.py 的 data_files 映射布置文件(以下为逐组实测命令,每组一条):
mkdir -p /etc/cobbler/settings.d /etc/cobbler/iso /etc/cobbler/boot_loader_conf \
/var/lib/cobbler/templates /var/lib/cobbler/snippets /var/lib/cobbler/scripts \
/var/lib/cobbler/loaders /var/lib/cobbler/grub_config /usr/share/cobbler/bin \
/var/www/cobbler /var/log/cobbler/tasks /var/cache/cobbler
cp config/cobbler/settings.yaml config/cobbler/auth.conf config/cobbler/modules.conf \
config/cobbler/mongodb.conf config/cobbler/users.conf config/cobbler/users.digest \
config/cobbler/logging_config.conf config/cheetah/cheetah_macros \
config/rotate/cobblerd_rotate config/rsync/import_rsync_whitelist \
config/rsync/rsync.exclude /etc/cobbler/
cp config/cobbler/settings.d/* /etc/cobbler/settings.d/
cp templates/etc/*.template /etc/cobbler/
cp templates/iso/* /etc/cobbler/iso/
cp templates/boot_loader_conf/* /etc/cobbler/boot_loader_conf/
cp config/cobbler/distro_signatures.json /var/lib/cobbler/
cp autoinstall_templates/* /var/lib/cobbler/templates/
cp -r autoinstall_templates/install_profiles /var/lib/cobbler/templates/
cp -r autoinstall_snippets/. /var/lib/cobbler/snippets/
cp autoinstall_scripts/* /var/lib/cobbler/scripts/
cp scripts/* /usr/share/cobbler/bin/
创建九类对象的序列化目录(JSON 文件库的存储位置,缺失会导致对象读写报 FileNotFoundError):
for d in distros profiles systems repos images mgmtclasses packages files menus; \
do mkdir -p /var/lib/cobbler/collections/$d; done
布置结果验证:
ls /etc/cobbler/ | head -8 ; ls /var/lib/cobbler/
实测回显:
auth.conf
boot_loader_conf
cheetah_macros
dhcp.template
dhcp6.template
dnsmasq.template
genders.template
...
collections
distro_signatures.json
grub_config
loaders
scripts
snippets
templates
triggers
web.ss
⚠️ 排障实录 3:布置时漏建
/var/log/cobbler会让 cobblerd 启动失败,日志真实报错为FileNotFoundError: [Errno 2] No such file or directory: '/var/log/cobbler/cobbler.log'——上面的 mkdir 已包含/var/log/cobbler/tasks。漏建/var/lib/cobbler/collections/*则cobbler list等任何对象读操作直接抛FileNotFoundError(本环境实测踩中后补建解决)。
4.4 settings.yaml 占位符替换与 version 文件
源码包内的 settings.yaml 是带构建期占位符的模板,直接使用会导致路径错乱(本环境实测:webdir 未替换时导入的发行版镜像被 rsync 到了字面量 @@webroot@@ 目录下)。Ubuntu 22.04 的占位符取值来自官方 distro_build_configs.sh 的 UBUNTU 分支,逐项替换:
sed -i \
-e "s|@@syslinux_dir@@|/usr/lib/syslinux/modules/bios/|" \
-e "s|@@memdisk_folder@@|/usr/lib/syslinux/|" \
-e "s|@@pxelinux_folder@@|/usr/lib/PXELINUX/|" \
-e "s|@@grub_mod_folder@@|/usr/lib/grub|" \
-e "s|@@shim_folder@@|/usr/lib/shim/|" \
-e 's|@@shim_file@@|shim.*\\.efi\\.signed|' \
-e "s|@@ipxe_folder@@|/usr/lib/ipxe/|" \
-e "s|@@bind_zonefiles@@|/etc/bind/db.|" \
-e "s|@@tftproot@@|/srv/tftpboot|" \
-e "s|@@webroot@@|/var/www|g" \
/etc/cobbler/settings.yaml
替换结果抽查验证:
grep -nE '^webdir:|^tftpboot_location:|^syslinux_dir:' /etc/cobbler/settings.yaml
实测回显:
webdir: "/var/www/cobbler"
syslinux_dir: '/usr/lib/syslinux/modules/bios/'
tftpboot_location: "/srv/tftpboot"
再创建 /etc/cobbler/version(发行版包构建时生成、源码包不含;格式为 configparser INI,内容按官方 setup.py 中 version 文件的字段结构填写):
cat > /etc/cobbler/version <<'EOF'
[cobbler]
gitdate = Thu Sep 18 10:00:00 2026 +0200
gitstamp = v3.3.10
builddate = Thu Sep 18 10:00:00 2026
version = 3.3.10
version_tuple = [3, 3, 10]
EOF
⚠️ 排障实录 4:没有 version 文件时,cobblerd 启动与任何 CLI 命令都会崩溃,真实报错为
KeyError: CobblerVersion(major=0, minor=0, patch=0)——Cobbler 的设置迁移器(migrations)要读/etc/cobbler/version判定设置文件版本,读不到就按 0.0.0 查表失败。version 值必须与实际安装版本一致,不一致的表现见第七章降级实测。
4.5 systemd 托管 cobblerd
官方单元文件 config/service/cobblerd.service 需要两处替换:@@httpd_service@@ → apache2.service、ExecStart 路径 → pip 的实际安装位置 /usr/local/bin/cobblerd:
sed -e "s|@@httpd_service@@|apache2.service|" \
-e "s|/usr/bin/cobblerd|/usr/local/bin/cobblerd|" \
/root/cobbler-3.3.10/config/service/cobblerd.service > /etc/systemd/system/cobblerd.service
生成的单元文件实测内容:
cat /etc/systemd/system/cobblerd.service
[Unit]
Description=Cobbler Helper Daemon
After=syslog.target network.target
Wants=apache2.service
[Service]
ExecStart=/usr/local/bin/cobblerd -F
PrivateTmp=yes
KillMode=process
[Install]
WantedBy=multi-user.target
托管并启动:
systemctl daemon-reload
systemctl enable --now cobblerd
实测回显:
Created symlink /etc/systemd/system/multi-user.target.wants/cobblerd.service → /etc/systemd/system/cobblerd.service.
验证运行状态:
systemctl is-active cobblerd
active
4.6 Apache 代理与 TFTP 服务
Apache:启用 wsgi/proxy 模块并布置官方 cobbler 站点配置(@@webroot@@/@@tftproot@@/@@virtualenv@@ 三处占位符按 Ubuntu 实值替换):
a2enmod wsgi proxy proxy_http
sed -e "s|@@webroot@@|/var/www|g" -e "s|@@tftproot@@|/srv/tftpboot|g" \
-e "s|@@virtualenv@@||g" \
/root/cobbler-3.3.10/config/apache/cobbler.conf > /etc/apache2/conf-available/cobbler.conf
a2enconf cobbler
systemctl restart apache2
systemctl is-active apache2
实测回显(a2enmod 输出节选 + 最终状态):
Enabling module proxy.
Enabling module proxy_http.
Enabling module wsgi.
Enabling conf cobbler.
active
其中 conf 的核心代理段(官方配置原文,已替换路径):
ProxyRequests off
ProxyPass /cobbler_api http://127.0.0.1:25151/
ProxyPassReverse /cobbler_api http://127.0.0.1:25151/
TFTP:Ubuntu 的 tftpd-hpa 默认根目录是 /srv/tftp,而 Cobbler 的 tftpboot_location 是 /srv/tftpboot,把默认配置对齐后重启(本环境实测默认值):
grep TFTP_DIRECTORY /etc/default/tftpd-hpa
TFTP_DIRECTORY="/srv/tftp"
sed -i 's|TFTP_DIRECTORY="/srv/tftp"|TFTP_DIRECTORY="/srv/tftpboot"|' /etc/default/tftpd-hpa
systemctl enable --now tftpd-hpa
systemctl is-active tftpd-hpa
ss -lun | grep :69
实测回显:
active
UNCONN 0 0 0.0.0.0:69 0.0.0.0:*
UNCONN 0 0 [::]:69 [::]:*
⚠️ 注意:若
systemctl enable --now tftpd-hpa后状态仍为 inactive(本环境首次实测如此),先systemctl start tftpd-hpa再查systemctl status tftpd-hpa确认;目录权限保证 tftp 用户可读(chown -R tftp:tftp /srv/tftpboot)。
4.7 首次 cobbler check 与逐项修复
服务三件套(cobblerd/apache2/tftpd-hpa)全部 active 后,跑首次健康检查:
cobbler check
实测回显(首次,共 6 项):
The following are potential configuration items that you may want to fix:
1: The 'server' field in /etc/cobbler/settings.yaml must be set to something other than localhost, or automatic installation features will not work. This should be a resolvable hostname or IP for the boot server as reachable by all machines that will use it.
2: For PXE to be functional, the 'next_server_v4' field in /etc/cobbler/settings.yaml must be set to something other than 127.0.0.1, and should match the IP of the boot server on the PXE network.
3: For PXE to be functional, the 'next_server_v6' field in /etc/cobbler/settings.yaml must be set to something other than ::1, and should match the IP of the boot server on the PXE network.
4: some network boot-loaders are missing from /var/lib/cobbler/loaders. If you only want to handle x86/x86_64 netbooting, you may ensure that you have installed a *recent* version of the syslinux package installed and can ignore this message entirely. Files in this directory, should you want to support all architectures, should include pxelinux.0, andmenu.c32.
5: debmirror package is not installed, it will be required to manage debian deployments and repositories
6: The default password used by the sample templates for newly installed machines (default_password_crypted in /etc/cobbler/settings.yaml) is still set to 'cobbler' and should be changed, try: "openssl passwd -1 -salt 'random-phrase-here' 'your-password-here'" to generate new one
Restart cobblerd and then run 'cobbler sync' to apply changes.
逐项修复(第 1、2、6 项)——设置对外 IP 与装机默认 root 密码哈希(本环境演示口令 q1w2e3r4,先生成哈希再写入):
openssl passwd -1 -salt 'cobbler' 'q1w2e3r4'
实测回显:
$1$cobbler$7pAP9eGoEwElZgph4fc400
sed -i -e 's|^server: 127.0.0.1|server: 10.89.57.2|' \
-e 's|^next_server_v4: 127.0.0.1|next_server_v4: 10.89.57.2|' \
-e 's|^default_password_crypted: .*|default_password_crypted: "$1$cobbler$7pAP9eGoEwElZgph4fc400"|' \
/etc/cobbler/settings.yaml
⚠️ 注意:第 3 项(next_server_v6)在纯 IPv4 网络可保留默认
::1并接受此提示;有 IPv6 时填写本机真实 IPv6 地址即可。
逐项修复(第 4、5 项)——安装 debmirror(4.1 步已含)并补齐引导加载器。check 的判定源码要求 loaders 目录下有 menu.c32、pxelinux.0 与 grub-x86.efi/grub-x86_64.efi 之一:
cp /usr/lib/PXELINUX/pxelinux.0 /usr/lib/syslinux/modules/bios/menu.c32 /var/lib/cobbler/loaders/
cp /usr/lib/grub/x86_64-efi-signed/grubnetx64.efi.signed /var/lib/cobbler/loaders/grub-x86_64.efi
ls -la /var/lib/cobbler/loaders/
实测回显:
total 2328
drwxr-xr-x 2 root root 4096 Oct 22 09:12 .
drwxr-xr-x 8 root root 4096 Oct 22 09:09 ..
-rw-r--r-- 1 root root 2299784 Oct 22 09:12 grub-x86_64.efi
-rw-r--r-- 1 root root 26148 Oct 22 09:11 menu.c32
-rw-r--r-- 1 root root 42584 Oct 22 09:11 pxelinux.0
重启并复查:
systemctl restart cobblerd
cobbler check
实测回显(修复后仅剩 IPv6 提示):
The following are potential configuration items that you may want to fix:
1: For PXE to be functional, the 'next_server_v6' field in /etc/cobbler/settings.yaml must be set to something other than ::1, and should match the IP of the boot server on the PXE network.
Restart cobblerd and then run 'cobbler sync' to apply changes.
4.8 安装验证(sync 收尾)
cobbler sync 是安装正确性的总验证:它把引导器复制到 TFTP 根目录、生成 PXE 菜单、按需渲染 DHCP/DNS 配置:
cobbler sync
实测回显(输出节选,首尾):
task started: 2026-10-22_091512_Sync_4b64f0db3fc74ae992351e442b5df8b9
task started (id=Sync, time=Thu Oct 22 09:15:12 2026)
start_task(sync); event_id(2026-10-22_091512_Sync_4b64f0db3fc74ae992351e442b5df8b9)
syncing all
running pre-sync triggers
cleaning trees
...
copying bootloaders
copying distros to tftpboot
copying images
generating PXE configuration files
generating PXE menu structure
cleaning link caches
running post-sync triggers
*** TASK COMPLETE ***
TFTP 产物验证:
ls /srv/tftpboot/
grub
grub-x86_64.efi
grub.cfg
images
ipxe
menu.c32
pxelinux.0
pxelinux.cfg
到此方案 A 安装完成。后续导入发行版、配置参数与日常命令分别见专栏的配置详解篇与命令详解篇。
五、方案 B:官方源码构建 deb 安装(构建机 + 目标机两段式)
本方案在构建机上用官方源码与打包脚本产出 Cobbler 的 deb 包,再把 deb 安装到目标 Ubuntu 22.04 服务器。适合内网多台机器统一交付、或需要离线安装的场景。
5.1 构建机上产出 deb
构建机要求:可联网、已安装 git 与 make、且装有 Docker(官方构建脚本 docker/debs/build-and-install-debs.sh 会自动创建隔离构建环境完成依赖安装与打包,无需人工准备构建依赖)。
git clone --depth 1 --branch v3.3.10 https://github.com/cobbler/cobbler.git
cd cobbler
./docker/debs/build-and-install-debs.sh deb12 docker/debs/Debian_12/Debian12.dockerfile
脚本执行完成后,deb 包在 deb-build/DEBS/all/ 下(本环境实测产物清单):
cobbler-tests-containers_3.3.10-1debian12_all.deb
cobbler-tests_3.3.10-1debian12_all.deb
cobbler_3.3.10-1debian12_all.deb
包元数据实测(dpkg -I cobbler_3.3.10-1debian12_all.deb 节选):
Package: cobbler
Version: 3.3.10-1debian12
Architecture: all
Depends: systemd-sysv,python3-minimal,systemd,apache2,tftpd-hpa,createrepo-c,fence-agents,rsync,xorriso,dosfstools,python3-cheetah,python3-dns,libapache2-mod-wsgi-py3,python3-netaddr,python3-yaml,python3-requests,python3-distro,python3-schema,python3-magic,python3-ldap,init-system-helpers
把 cobbler_3.3.10-1debian12_all.deb 拷贝到目标服务器(U 盘/scp 均可),进入 5.2。
⚠️ 注意:官方 DEB 构建目前只提供 Debian 10/11/12 三套构建定义(
docker/debs/目录下),没有 Ubuntu 专用定义;Debian 12 与 Ubuntu 22.04 同为 dpkg 系、依赖包名一致,实测可装(5.2 起为真实目标机过程),但有一处 Python 3.11 专属参数需要修复,见 5.3。
5.2 目标机安装 deb
dpkg -i /root/cobbler_3.3.10-1debian12_all.deb
实测回显(依赖未就绪时先报错,属正常现象):
Package python3-ldap is not installed.
dpkg: error processing package cobbler (--install):
dependency problems - leaving unconfigured
Errors were encountered while processing:
cobbler
用 apt 自动补齐依赖:
apt-get install -f -y
实测回显(输出节选):
Running hooks in /etc/ca-certificates/update.d...
done.
安装状态验证:
dpkg -l cobbler | tail -1
ii cobbler 3.3.10-1debian12 all Boot server configurator
5.3 修复 shebang 并启动服务
排障实录 5(方案 B 的关键坑):deb 按 Debian 12 打包,其可执行脚本 shebang 为 #!/usr/bin/python3 -sP——-P 是 Python 3.11 新增的隔离模式选项,Ubuntu 22.04 的 Python 3.10 不认识,cobblerd 启动失败。真实报错回显:
Unknown option: -P
usage: /usr/bin/python3 [option] ... [-c cmd | -m mod | file | -] [arg] ...
Try `python -h' for more information.
修复(去掉组合参数中的 P,保留 -s):
head -1 /usr/bin/cobblerd
#!/usr/bin/python3 -sP
sed -i '1s/-sP/-s/' /usr/bin/cobblerd /usr/bin/cobbler
systemctl enable --now cobblerd
systemctl is-active cobblerd
active
5.4 check 与版本验证
启用 Apache 侧配置(deb 已自带 cobbler.conf 与模块依赖)并验证:
a2enmod proxy proxy_http wsgi
a2enconf cobbler
systemctl enable --now apache2
cobbler check
实测回显(与方案 A 首次 check 完全一致的 6 项,按 4.7 节同样方法修复即可,此处不再重复):
The following are potential configuration items that you may want to fix:
1: The 'server' field in /etc/cobbler/settings.yaml must be set to something other than localhost, or automatic installation features will not work. This should be a resolvable hostname or IP for the boot server as reachable by all machines that will use it.
2: For PXE to be functional, the 'next_server_v4' field in /etc/cobbler/settings.yaml must be set to something other than 127.0.0.1, and should match the IP of the boot server on the PXE network.
3: For PXE to be functional, the 'next_server_v6' field in /etc/cobbler/settings.yaml must be set to something other than ::1, and should match the IP of the boot server on the PXE network.
4: some network boot-loaders are missing from /var/lib/cobbler/loaders. If you only want to handle x86/x86_64 netbooting, you may ensure that you have installed a *recent* version of the syslinux package installed and can ignore this message entirely. Files in this directory, should you want to support all architectures, should include pxelinux.0, andmenu.c32.
5: debmirror package is not installed, it will be required to manage debian deployments and repositories
6: The default password used by the sample templates for newly installed machines (default_password_crypted in /etc/cobbler/settings.yaml) is still set to 'cobbler' and should be changed, try: "openssl passwd -1 -salt 'random-phrase-here' 'your-password-here'" to generate new one
Restart cobblerd and then run 'cobbler sync' to apply changes.
版本验证(deb 版无 git 源信息,source 显示 ?, ?,属正常差异):
cobbler version
Cobbler 3.3.10
source: ?, ?
build time: Thu Oct 22 09:19:02 2026
六、方案对比与选择建议
| 维度 | 方案 A:pip 安装 | 方案 B:源码构建 deb |
|---|---|---|
| 版本 | 3.3.10(PyPI 官方 wheel) | 3.3.10-1debian12(自构建) |
| 是否需联网 | 目标机需访问 PyPI + GitHub | 构建机联网,目标机可离线 |
| 安装位置 | /usr/local/bin + 手工布置配置 | /usr/bin + dpkg 全自动布置 |
| systemd 单元 | 手工生成(4.5 节) | deb 自带(/lib/systemd/system/cobblerd.service) |
| 已知坑 | 配置占位符替换、version 文件 | Python 3.10 不认 -sP shebang、依赖名 Debian 化 |
| 升级/卸载 | pip install/uninstall | dpkg/apt 标准流程 |
| 适用 | 单台/少量服务器、追求最新版 | 内网批量交付、离线环境 |
选择建议:单机或少量服务器直接用方案 A(步骤可控、版本最新);内网机器多或目标机不能联网用方案 B(一次构建、处处安装),但必须在目标机做 5.3 的 shebang 修复。两方案完成后的 check 收敛标准一致(仅剩 IPv6 提示或全清)。
七、升级、降级与多版本管理
7.1 pip 方案的版本切换(实测)
升级到同线新版本(未来 3.3.11 发布后):
pip install -U cobbler==3.3.11
降级实测(降到 3.3.9):
pip install cobbler==3.3.9
cobbler version
实测回显——降级后直接报 KeyError(版本文件与代码错位):
KeyError: CobblerVersion(major=3, minor=3, patch=10)
原因:/etc/cobbler/version 记录的还是 3.3.10,而 3.3.9 的迁移器不认识更高版本号。修复方法是把 version 文件同步改回目标版本:
sed -i 's/^version = 3.3.10/version = 3.3.9/; s/version_tuple = \[3, 3, 10\]/version_tuple = [3, 3, 9]/' /etc/cobbler/version
cobbler version
Cobbler 3.3.9
升回 3.3.10 同理(先 pip 装 3.3.10,再把 version 文件改回 3.3.10 与 [3, 3, 10]),实测恢复正常且既有对象数据完好(cobbler list 的 distros/profiles 原样保留)。
7.2 多版本并存
Cobbler 不支持同机多实例并行服务(端口 25151 与 /etc/cobbler 均为独占)。需要多版本时的正确做法是按方案 B 为每个版本各产出 deb,在不同服务器分别安装;或用虚拟机/独立主机组隔离。原地并存请勿尝试。
7.3 deb 方案的升级
自构建的新版本 deb 直接覆盖安装:
dpkg -i cobbler_3.3.11-1debian12_all.deb
apt-get install -f -y
systemctl restart cobblerd
回滚则重装旧版 deb(dpkg -i cobbler_3.3.10-1debian12_all.deb)。注意对象数据在 /var/lib/cobbler/collections/,升级前建议整目录备份(见第九章卸载清理前的备份命令)。
八、常见问题(FAQ)
Q1:apt install cobbler 报"Unable to locate package"?
Ubuntu 22.04 官方仓库没有 cobbler 包(第三章实测)。请走本文方案 A 或方案 B。
Q2:pip 安装时报 metadata-generation-failed?
缺编译依赖。确认 gcc python3-dev libapache2-dev libldap2-dev libsasl2-dev 已装(4.1 节排障实录 2 的两个典型失败点:mod-wsgi 缺 apxs、python-ldap 缺 ldap/sasl 头文件)。
Q3:cobblerd setup 命令不存在?
cobblerd setup 是 4.0 系列文档里的新子命令,3.3.10 实测报 cobblerd: error: unrecognized arguments: setup。3.3.10 请按 4.3/4.4 节手工布置配置。
Q4:cobblerd 启动失败,日志见 KeyError: CobblerVersion(major=0, minor=0, patch=0)?
缺 /etc/cobbler/version 文件(4.4 节)。创建该 INI 文件并保证 version 与实际安装版本一致。
Q5:cobbler check 报 "httpd does not appear to be running and proxying Cobbler"?
CLI 走 http://127.0.0.1/cobbler_api,由 Apache ProxyPass /cobbler_api http://127.0.0.1:25151/ 转发到 cobblerd。依次确认:systemctl is-active apache2 为 active、a2enconf cobbler 已启用、a2enmod proxy proxy_http wsgi 已启用,然后 systemctl reload apache2。
Q6:tftpd-hpa 装完是 inactive?
Ubuntu 的 tftpd-hpa 是 LSB 脚本包装的服务,systemctl enable --now 后偶发未拉起(本环境实测),补一次 systemctl start tftpd-hpa;再确认 /etc/default/tftpd-hpa 的 TFTP_DIRECTORY 与 settings.yaml 的 tftpboot_location(/srv/tftpboot)一致。
Q7:方案 B 安装后 cobblerd 起不来,报 Unknown option: -P?
Debian 12 构建的 deb shebang 带 Python 3.11 专属参数 -P,Ubuntu 22.04(Python 3.10)需按 5.3 节 sed -i '1s/-sP/-s/' /usr/bin/cobblerd /usr/bin/cobbler 修复。
Q8:导入发行版时报 "No signature matched"?
Cobbler 按静态签名库(/var/lib/cobbler/distro_signatures.json)识别发行版,3.3.10 的 ubuntu breed 最高到 impish,无 jammy 条目(本环境实测回显见专栏介绍篇第六章)。用 --breed/--os-version 指定受支持的版本(如 focal),或对更新发行版走手工 cobbler distro add。
九、卸载与清理
方案 A(pip)卸载:
systemctl disable --now cobblerd
pip uninstall -y cobbler
rm -f /etc/systemd/system/cobblerd.service
systemctl daemon-reload
方案 B(deb)卸载(实测回显):
apt-get remove -y cobbler
(Reading database ... 16860 files and directories currently installed.)
Removing cobbler (3.3.10-1debian12) ...
dpkg -l cobbler | tail -1
rc cobbler 3.3.10-1debian12 all Boot server configurator
💡 说明:
rc表示包已删除但配置文件保留(conffile 机制,/etc/cobbler/settings.yaml等仍在)。彻底清除用apt-get purge -y cobbler。
数据与产物清理(两方案通用,如需保留装机台账请先备份 collections 目录):
cp -r /var/lib/cobbler/collections /root/cobbler-collections-backup # 可选:备份对象数据
rm -rf /etc/cobbler /var/lib/cobbler /var/log/cobbler /srv/tftpboot /var/www/cobbler
十、参考链接
- Cobbler 官方安装指南(Prerequisites/DEB/Pip 章节):https://cobbler.readthedocs.io/en/latest/installation-guide.html
- Cobbler v3.3.10 Release(版本与发布日期,查询日期 2026-10-22):https://github.com/cobbler/cobbler/releases/tag/v3.3.10
- Cobbler PyPI 项目页:https://pypi.org/project/cobbler/
- Cobbler GitHub 仓库:https://github.com/cobbler/cobbler
- 本专栏选型背景:《Cobbler 3.3.10 介绍与选型指南》