簡介CUPS 2.3.3 源碼包面向類 Unix 系統(tǒng)的開發(fā)者、系統(tǒng)管理員與打印服務(wù)學(xué)習(xí)者適合在本地部署、定制或研究開源打印系統(tǒng)涵蓋打印作業(yè)管理、過濾器驅(qū)動、網(wǎng)頁管理界面、加密傳輸與跨平臺兼容等核心能力。壓縮包共 1294 個文件、約 7.76MB以 C 與 C 源碼、頭文件、網(wǎng)頁文檔、測試腳本、模板和構(gòu)建文件為主并含配置腳本、手冊、打印描述示例、國際化文件及多種后端與過濾器資源目錄覆蓋服務(wù)端、庫、工具鏈、策略和文檔等模塊。已有 928 人學(xué)習(xí)下載。完整源碼結(jié)構(gòu)便于讀者在本地編譯定制也可據(jù)此理解網(wǎng)絡(luò)打印協(xié)議支持研究自定義過濾器與后端擴(kuò)展方式或排查打印隊(duì)列、驅(qū)動適配與配置管理問題對中高級運(yùn)維與開發(fā)人員查漏補(bǔ)缺、二次開發(fā)均有參考價值。1. 從發(fā)行版包換成 cups-2.3.3-source.tar.gz一次「全都對就是打不出來」在一臺要接三臺網(wǎng)絡(luò)打印機(jī)的機(jī)器上我遇到過很別扭的情況發(fā)行版?zhèn)}庫里裝的打印服務(wù)能把隊(duì)列建起來管理頁面也能打開可一提交任務(wù)就卡在Filter failed日志翻半天只有一行看不出所以然的話。后來我把 cups-2.3.3-source.tar.gz 解開自己編問題沒有立刻消失但至少每一步都在自己手里依賴裝沒裝、運(yùn)行目錄權(quán)限對不對、過濾器在哪個目錄、服務(wù)單元是誰寫的全都能翻到。源碼裝 CUPS 最難的地方在于「編譯成功」和「打印成功」是兩件事——configure和make install一路綠燈只證明調(diào)度器能起來不證明你的紙能出來。2. 編譯前清點(diǎn)工具鏈、依賴庫與 lp 用戶組的分配動手之前先花十分鐘確認(rèn)環(huán)境比編譯完再回頭補(bǔ)依賴省事得多。CUPS 2.3.3 屬于 2.3 分支的收尾版本代碼不算新對編譯器要求不高但它對「系統(tǒng)里有沒有 lp 用戶」「/run 下有沒有對應(yīng)目錄」這類事情的假設(shè)很強(qiáng)缺一樣就在運(yùn)行時報怪錯。2.1 編譯器與構(gòu)建工具的最低要求CUPS 2.3.3 的代碼大量使用 C99 特性gcc 4.8 以上、clang 3.4 以上都能編。make 需要 3.8 以上主要是為了讓并行構(gòu)建和install目標(biāo)行為正常。另外記得裝pkg-configconfigure 探測依賴庫時靠它拿編譯參數(shù)缺了不會直接報錯但會靜默判定「某個庫不存在」最后你編出來的東西少一塊功能。# 三行確認(rèn)構(gòu)建工具是否能滿足 2.3.3 的最低要求 gcc --version | head -n1 # 期望 4.8 以上 make --version | head -n1 # 期望 3.8 以上 pkg-config --version # 期望 0.20 以上如果機(jī)器上同時裝了多個 gcc別讓 configure 抓到老的那個。我一般顯式指定CC/usr/bin/gcc并在后面看config.log里實(shí)際用的是不是同一個。另外源碼包里是帶了configure的發(fā)布包不需要再跑autoreconf或autoconf。很多人習(xí)慣性先autoreconf -fi結(jié)果因?yàn)楸緳C(jī) autoconf 版本太新生成的腳本跟源碼里的 m4 宏對不上直接在第一關(guān)失敗。提示編譯時不要往CFLAGS里加-Werror。CUPS 2.3.3 的代碼在新版編譯器下會產(chǎn)生不少新告警-Werror會把告警變成錯誤編到一半中斷。2.2 依賴庫清單必裝、可選、能砍掉CUPS 的依賴分三層調(diào)度器自己需要的、過濾器需要的、外部功能需要的。先把這張表過一遍再決定裝什么能少裝一半東西。依賴對應(yīng)功能不裝的后果能否關(guān)掉zlib壓縮、PPD 與 IPP 數(shù)據(jù)處理configure 直接報錯退出不能libpng / libjpeg圖像相關(guān)的內(nèi)建轉(zhuǎn)換configure 輸出里這兩項(xiàng)顯示 no圖像類任務(wù)受影響能但建議裝openssl 開發(fā)頭文件連接加密、摘要計算探測不到就退回明文基本打印不受影響能avahi / libavahi-client網(wǎng)段內(nèi)自動發(fā)現(xiàn)打印機(jī)廣播發(fā)現(xiàn)功能不可用手動加隊(duì)列不受影響能加--with-dnssdnolibusbUSB 直連打印機(jī)USB 后端不可用網(wǎng)絡(luò)打印機(jī)不受影響能cups-filtersPDF/PS 轉(zhuǎn)設(shè)備格式的過濾器隊(duì)列能建一打就Filter failed不能但它是獨(dú)立包表格里最后一行是最容易忽略的從很早的版本開始CUPS 就把大部分過濾器拆到了獨(dú)立項(xiàng)目里源碼包裝完之后/usr/lib/cups/filter下只有寥寥幾個文件。你如果只用高端網(wǎng)絡(luò)打印機(jī)自帶的 IPP 處理能力問題不大一旦要驅(qū)動一臺只懂 PCL 的老設(shè)備就必須另裝過濾器包否則調(diào)度器會把任務(wù)接下來然后在中途找不到轉(zhuǎn)換程序報一句非常籠統(tǒng)的錯誤。圖像庫里libpng和libjpeg這兩個不用糾結(jié)裝就完了。有些最小化系統(tǒng)只有運(yùn)行時庫沒有開發(fā)頭文件pkg-config --exists libpng返回 falseconfigure 就把這一項(xiàng)判成 no。裝的時候記得帶-devel或-dev后綴的包名。至于 avahi如果你的機(jī)器在機(jī)房里、打印機(jī) IP 固定、隊(duì)列全部手工建那就直接關(guān)掉。它帶來的是一整條依賴鏈編譯時間翻倍還容易在啟動時因?yàn)槭刈o(hù)進(jìn)程沒起而卡一下。我一般的寫法是--with-dnssdno。2.3 用戶組與安裝前綴的提前規(guī)劃CUPS 運(yùn)行時要有兩個身份一個非特權(quán)用戶跑過濾器默認(rèn)lp一個管理組決定誰能通過本地套接字做管理操作默認(rèn)lpadmin。這兩個東西不搞好后面lpadmin建隊(duì)列會莫名其妙地提示認(rèn)證失敗。# 確認(rèn) lp 用戶和 lpadmin 組是否存在缺了就補(bǔ) getent passwd lp || useradd -r -s /sbin/nologin -d /var/spool/lpd lp getent group lpadmin || groupadd -r lpadmin # 把日常運(yùn)維賬號加進(jìn) lpadmin避免每次都用 root 做管理操作 usermod -aG lpadmin opsusermod之后要重新登錄才生效別在這個 shell 里接著測會以為加組失敗。管理組的作用是配置文件里寫SYSTEM的地方實(shí)際展開就是這個組。Web 管理頁要求輸入賬號密碼時走的也是這套邏輯。安裝前綴也要提前定。我固定用--prefix/usr、--sysconfdir/etc、--localstatedir/var。為什么不裝/usr/local因?yàn)?CUPS 的部分組件有自己寫死的默認(rèn)路徑查找邏輯裝到/usr/local后 man 頁、服務(wù)單元、以及某些按/usr/lib/cups硬編碼的第三方腳本會對不上出問題時排查成本遠(yuǎn)大于省下的那點(diǎn)隔離收益。如果你的系統(tǒng)是 64 位且?guī)炷夸浄至?lib 和 lib64還要額外加--libdir/usr/lib64否則后端和過濾器會落到/usr/lib/cups而某些按 lib64 找東西的組件找不到它們表現(xiàn)就是「隊(duì)列正常打印無聲失敗」。3. configure 到 make installCUPS 2.3.3 的參數(shù)逐條拆這一章是整個安裝過程里最需要看清楚的一段。參數(shù)寫錯幾個編譯照樣成功問題留到運(yùn)行時才暴露那時候你就得靠日志猜了。3.1 解包與源碼樹自檢# 先看包內(nèi)結(jié)構(gòu)確認(rèn)是一級目錄還是裸文件 tar -tzf cups-2.3.3-source.tar.gz | head -n 5 # 解開并進(jìn)入源碼目錄 tar -xzf cups-2.3.3-source.tar.gz cd cups-2.3.3 # 發(fā)布包一定帶這兩個文件缺一個就說明拿到的不是發(fā)布包 ls -l configure INSTALLconfigure文件存在且可執(zhí)行說明這是打包好的發(fā)布版本直接跑就行。如果只有configure.ac和configure.in那是開發(fā)樹得先autoconf編譯門檻和踩坑概率都會上一個臺階能換發(fā)布包就換。解包之后順手看一眼CHANGES.txt里 2.3.3 這一節(jié)的修復(fù)條目能提前知道這個版本改過哪些路徑相關(guān)的行為。長期維護(hù)的機(jī)器這一步值得做。3.2 configure 參數(shù)取舍這是我在這類環(huán)境里用得最多的一套組合./configure \ --prefix/usr \ --sysconfdir/etc \ --localstatedir/var \ --libdir/usr/lib64 \ --with-rundir/run/cups \ --with-system-groupslpadmin \ --with-printcap/etc/printcap \ --with-dnssdno \ --enable-shared \ --disable-static \ CFLAGS-O2 -g CXXFLAGS-O2 -g每個參數(shù)的理由--prefix/usr二進(jìn)制落在/usr/sbin和系統(tǒng)里已有的工具路徑一致PATH 不用改。--sysconfdir/etc配置文件最終進(jìn)/etc/cups這是 CUPS 自己也在找的位置。--localstatedir/varspool 在/var/spool/cups日志在/var/log/cups緩存進(jìn)/var/cache/cups。--libdir/usr/lib64決定后端、過濾器、通知器的安裝位置。64 位系統(tǒng)上不寫這個容易和按 lib64 找文件的組件錯位。--with-rundir/run/cupsPID 文件、本地域套接字都在這里。用/run而不是/var/run是因?yàn)楝F(xiàn)在多數(shù)系統(tǒng)/var/run只是軟鏈寫死舊路徑在某些場景下會失效。--with-system-groupslpadmin決定SYSTEM展開成哪個組直接影響誰能管理隊(duì)列。--with-printcap/etc/printcap有些老腳本和老工具還在讀這個文件留著能省事。--with-dnssdno關(guān)掉網(wǎng)段廣播發(fā)現(xiàn)砍掉 avahi 依賴鏈。--enable-shared --disable-static只編動態(tài)庫省體積也省編譯時間。靜態(tài)庫在這類場景里沒有使用價值。CFLAGS-O2 -g保留調(diào)試符號是為了將來真出問題時能用調(diào)試器看棧。生產(chǎn)機(jī)器上多幾十兆磁盤換一個可排查的現(xiàn)場我覺得劃算。跑完 configure別急著 make把輸出末尾那段構(gòu)建配置摘要存下來# 把 configure 的關(guān)鍵探測結(jié)果留下來將來對比版本差異時非常有用 ./configure ... 21 | tee /tmp/cups-configure.log grep -iE png|jpeg|openssl|avahi|dnssd|pam|usb /tmp/cups-configure.log摘要里如果某項(xiàng)顯示 no 而你以為裝了回去翻config.log搜索checking for對應(yīng)的那一行能看到具體的編譯或鏈接失敗原因。這一步是后面所有排查的基礎(chǔ)我習(xí)慣把這個日志留在機(jī)器上命名里帶日期。3.3 make 并發(fā)與安裝后的目錄核驗(yàn)# 并行編譯日志留一份編譯告警不要忽略 make -j$(nproc) 21 | tee /tmp/cups-build.log # 安裝注意這一步會往 /etc、/usr、/var 下寫文件 make installmake -j的并發(fā)數(shù)按 CPU 核數(shù)給就行CUPS 的構(gòu)建腳本沒有并行依賴問題但把日志 tee 出來很重要。CUPS 編譯過程中的告警里有一類是「某個可選組件未找到跳過」這類信息不會讓編譯失敗但直接決定你裝完以后功能是否完整。安裝完成后按下面的清單核驗(yàn)一遍# 主程序是否就位、版本是否是 2.3.3 ls -l /usr/sbin/cupsd /usr/sbin/cupsd -v # 三個關(guān)鍵目錄是否都有內(nèi)容 ls /usr/lib64/cups/backend ls /usr/lib64/cups/filter ls /usr/lib64/cups/notifier # 配置目錄下應(yīng)該是 cupsd.conf、cups-files.conf 和對應(yīng)的 .default ls -l /etc/cups # 檢查 cupsd 鏈接了哪些外部庫確認(rèn)沒有意外的缺庫 ldd /usr/sbin/cupsd | grep -i not found關(guān)于/etc/cups有一點(diǎn)要提前知道m(xù)ake install遇到已存在的配置文件時不會直接覆蓋新的那份會以.default結(jié)尾留下來。如果你是從舊版本升級或之前裝過發(fā)行版包c(diǎn)upsd.conf很可能還是舊內(nèi)容。第一次裝可以不管但只要機(jī)器上原本就有配置就得手動對比一次否則你會以為參數(shù)生效了實(shí)際跑的還是一年前的配置。/usr/lib64/cups/filter目錄里如果只有三四個文件不要慌這是正常的剩下的大量過濾器在獨(dú)立的過濾器包里。這一點(diǎn)在第五章的排錯里會詳細(xì)說。4. 配置與接管cupsd.conf、自寫 systemd 單元與第一個打印隊(duì)列編譯安裝和「服務(wù)能自動拉起」之間還差好幾步。源碼包不會替你裝服務(wù)單元也不會替你建運(yùn)行目錄更不會替你寫好配置文件里那些必須顯式聲明的授權(quán)段落。這一章做完才算把這套東西接管過來。4.1 運(yùn)行目錄與權(quán)限cupsd 啟動前必須存在的三處cupsd 啟動時會檢查幾個目錄缺了會自己建但權(quán)限不對時它會拒絕服務(wù)報出來的話通常很含糊只說某個目錄不安全。手工先建好能少走一段彎路。# 運(yùn)行目錄放 PID 和本地套接字屬主 root屬組 lp0755 install -d -m 0755 -o root -g lp /run/cups # spool 目錄放待打印任務(wù)權(quán)限必須收緊到 0710 install -d -m 0710 -o root -g lp /var/spool/cups # 日志與緩存目錄 install -d -m 0755 -o root -g lp /var/log/cups install -d -m 0755 -o root -g lp /var/cache/cups/var/spool/cups的0710不是隨手寫的。打印任務(wù)里可能包含敏感文檔這個目錄如果對其他用戶可讀cupsd 啟動時會打印一條警告某些編譯選項(xiàng)下直接拒絕啟動。0755是常見誤填一定要改。/run目錄還有個額外問題它基于內(nèi)存文件系統(tǒng)重啟就清空。所以要么用 systemd 的RuntimeDirectory要么寫一條tmpfiles.d規(guī)則。我傾向后者因?yàn)檎{(diào)試時手動起停更可控# /etc/tmpfiles.d/cups.conf d /run/cups 0755 root lp -這條規(guī)則的意思是目錄不存在就創(chuàng)建權(quán)限 0755屬主 root屬組 lp。tmpfiles在開機(jī)早期運(yùn)行比服務(wù)啟動早順序上剛好。4.2 cupsd.conf 最小可用配置配置文件分兩個cupsd.conf放服務(wù)行為cups-files.conf放路徑和身份。這兩者分開是有原因的從 1.6 之后User、Group、SystemGroup、ServerBin這類涉及文件系統(tǒng)訪問的指令全部搬到了cups-files.conf寫回cupsd.conf不會生效某些版本還會直接報「未知指令」。這是很典型的一個坑。先看cups-files.conf里要確認(rèn)的幾行# /etc/cups/cups-files.conf # 過濾器運(yùn)行身份必須是一個真實(shí)存在的非特權(quán)用戶 User lp Group lp # 管理組對應(yīng) SYSTEM 的展開結(jié)果 SystemGroup lpadmin # 本地域套接字位置lpadmin 通過它做認(rèn)證 DomainSocket /run/cups/cups.sock再看cupsd.conf的最小可用版本# /etc/cups/cupsd.conf # 日志級別排查期用 debug2穩(wěn)定后改回 warn LogLevel warn MaxLogSize 0 # 只監(jiān)聽本機(jī)和內(nèi)網(wǎng)本地套接字必開 Listen localhost:631 Listen /run/cups/cups.sock # 允許 Web 管理頁 WebInterface Yes # 默認(rèn)認(rèn)證方式 DefaultAuthType Basic Location / Order allow,deny Allow localhost Allow 192.168.10.0/24 /Location Location /admin Order allow,deny Allow localhost Allow 192.168.10.0/24 /Location Location /admin/conf AuthType Default Require user SYSTEM Order allow,deny Allow localhost /Location幾個要點(diǎn)Listen localhost:631和Listen /run/cups/cups.sock這兩行是并列關(guān)系前者給 Web 頁面和遠(yuǎn)程 IPP 用后者給本機(jī)的lpadmin、lpstat等命令用。少寫第二行命令行工具會去連默認(rèn)套接字然后失敗報的錯是「無法連接到服務(wù)器」很容易被誤判成服務(wù)沒起。192.168.10.0/24換成你自己網(wǎng)段。這個網(wǎng)段只是示例實(shí)際要比你這臺機(jī)器能訪問的打印機(jī)的網(wǎng)段匹配。Location /admin/conf里加了Require user SYSTEM意思是只有管理組的人能改配置其他授權(quán)網(wǎng)段的人只能看隊(duì)列和提交任務(wù)。這個分層的意義在于Web 界面誰都能打開但改配置需要身份。配置寫完先做語法檢查別急著啟動# 只檢查配置語法不真正啟動服務(wù) /usr/sbin/cupsd -t # 想看更細(xì)的解析過程加 -c 指定配置文件再配合 -t /usr/sbin/cupsd -t -c /etc/cups/cupsd.conf-t的返回值是 0 才繼續(xù)非 0 就去/var/log/cups/error_log看最后幾行通常會明確指出行號。4.3 自寫 systemd 單元讓服務(wù)開機(jī)自起源碼安裝不會給你裝服務(wù)單元。自己寫一份放在/etc/systemd/system下比改源碼樹里的模板更清楚來龍去脈。# /etc/systemd/system/cups.service [Unit] DescriptionCUPS Scheduler Afternetwork.target Wantsnetwork.target [Service] Typesimple # -f 表示前臺運(yùn)行交給 systemd 托管進(jìn)程 ExecStart/usr/sbin/cupsd -f # 讓 systemd 管理 /run/cups重啟后自動重建 RuntimeDirectorycups RuntimeDirectoryMode0755 Restarton-failure RestartSec5s LimitNOFILE65536 [Install] WantedBymulti-user.targetTypesimple配-f是最省心的組合cupsd 在前臺跑標(biāo)準(zhǔn)輸出和錯誤都進(jìn) journalsystemctl status能直接看到。不要用Typeforking那樣進(jìn)程一退出父進(jìn)程日志歸屬就亂了排查時體驗(yàn)很差。RuntimeDirectorycups會讓 systemd 在啟動前建好/run/cups并在停止后清理和前面寫的 tmpfiles 規(guī)則功能重疊但不沖突。兩處都留著是為了在手動cupsd -f調(diào)試時目錄也在。啟用并啟動systemctl daemon-reload systemctl enable --now cups # 三件事一起看服務(wù)狀態(tài)、端口監(jiān)聽、啟動日志 systemctl status cups --no-pager ss -ltnp | grep 631 journalctl -u cups -n 30 --no-pager如果 631 端口沒起來而服務(wù)顯示 active多半是配置文件里的Listen段落寫錯或者端口被上一次沒退干凈的進(jìn)程占著。ss -ltnp的輸出里能看到占用者的 PID直接處理。4.4 用 lpadmin 建第一個隊(duì)列服務(wù)起來之后先看看這臺機(jī)器能識別到哪些設(shè)備# 列出所有可用的后端和設(shè)備 URI lpinfo -v輸出里通常會有network ipp、network socket、direct usb這幾類。網(wǎng)絡(luò)打印機(jī)優(yōu)先用 IPP直接寫設(shè)備的 IPP 地址# 建一個走 IPP Everywhere 的隊(duì)列由服務(wù)端自動協(xié)商能力 lpadmin -p office-a \ -E \ -v ipp://192.168.10.20/ipp/print \ -m everywhere \ -D Office A \ -L 3F \ -o printer-is-sharedfalse # 設(shè)為默認(rèn)隊(duì)列 lpadmin -d office-a參數(shù)拆開說-p是隊(duì)列名只能用字母數(shù)字和連字符-E表示建完立刻啟用并接受任務(wù)漏了它隊(duì)列是禁用狀態(tài)lpstat -t里會顯示disabled-v是設(shè)備 URI-m everywhere讓調(diào)度器跟設(shè)備協(xié)商生成 PPD不需要你預(yù)先準(zhǔn)備驅(qū)動文件-D和-L是描述和位置人多的時候很有用-o printer-is-sharedfalse表示不通過廣播共享出去。如果設(shè)備比較老、只認(rèn) 9100 端口的原始數(shù)據(jù)流可以用 raw 隊(duì)列跳過格式轉(zhuǎn)換# 老設(shè)備兜底方案不打任何過濾直接把字節(jié)流送過去 lpadmin -p legacy-1 -E -v socket://192.168.10.31:9100 -m rawraw 隊(duì)列的好處是不依賴過濾器壞處是格式轉(zhuǎn)換全交給客戶端。兩種方式按設(shè)備情況選不要為了統(tǒng)一全用 raw那樣 PDF 直接被推給打印機(jī)出來一堆亂碼。5. 排查清單cupsd 起不來和打不出紙的五個現(xiàn)場這一章是我自己攢的問題記錄。CUPS 的日志寫得不算差但很多錯誤信息是「結(jié)果」不是「原因」得順著往下摸。下面五條按現(xiàn)象、原因、解決的順序?qū)懹龅綄?yīng)癥狀可以直接對照。5.1 服務(wù)起不來的三個現(xiàn)場現(xiàn)象一systemctl start cups失敗日志只有一行Unable to open Listen socket - Address already in use。原因上一次的 cupsd 沒退干凈或者系統(tǒng)里還有另一個打印服務(wù)單元在搶 631 端口。RPM 或 deb 包安裝的版本和自己編的版本共存時特別容易出現(xiàn)兩個單元名字不同但都監(jiān)聽同一端口。解決ss -ltnp | grep 631找到占用的 PID先確認(rèn)是不是打印相關(guān)進(jìn)程是就kill掉再systemctl disable掉不用的那個單元。別直接pkill cupsd完事端口釋放有延遲隔一兩秒再啟動?，F(xiàn)象二服務(wù)啟動后立刻退出journalctl里只有cupsd: Child exited with status 1沒有任何具體原因。原因cupsd 在守護(hù)化之前把真正的錯誤寫到了標(biāo)準(zhǔn)錯誤但被 systemd 吞掉了或者配置里的LogLevel設(shè)得太高關(guān)鍵信息被過濾。另一個常見原因是cups-files.conf里User指定的用戶不存在cupsd 在降權(quán)那一步失敗后靜默退出。解決手動前臺跑一遍直接看輸出# 前臺運(yùn)行標(biāo)準(zhǔn)錯誤直接打到終端最能暴露真實(shí)原因 /usr/sbin/cupsd -f -c /etc/cups/cupsd.conf順手確認(rèn)一下getent passwd lp有輸出。這個「守護(hù)進(jìn)程起不來就前臺跑一遍」的習(xí)慣幫我省過太多次瞎猜?，F(xiàn)象三服務(wù)起來了631 端口也在聽但lpstat -t報Unable to connect to server。原因本地域套接字沒建出來或者建在別的位置。cups-files.conf里的DomainSocket和cupsd.conf里的Listen沒對齊時就會這樣客戶端按編譯時的默認(rèn)路徑找套接字服務(wù)端在另一個路徑上監(jiān)聽。解決ls -l /run/cups/cups.sock看文件在不在。不在的話檢查兩處路徑是否一致改完重啟。順手看一眼semanage或強(qiáng)制訪問控制的審計日志某些默認(rèn)開啟強(qiáng)制訪問控制的系統(tǒng)上套接字會被策略擋住表現(xiàn)同樣是「本文還有配套的精品資源點(diǎn)擊獲取