FreeBSD CUPS Operations: Build Observable IPP Print Queues

CUPS provides a print service built around queues and the Internet Printing Protocol. On FreeBSD it is installed as third-party software, rather than configured through the base system’s legacy LPD service. That distinction matters during migration: the printer device, queue policy, service startup, and client URI each have an owner and a diagnostic boundary.

The safest operations workflow starts by deciding whether a host is a local print server, a client of another server, or both. Do not expose an administrative interface or enable broad network sharing merely to make a first test pass. Bring up one controlled queue, test it locally, then add network clients with the smallest needed reachability.

Install and identify the service

The FreeBSD CUPS article documents installation through pkg and places configuration under /usr/local/etc/cups. Verify the installed package and service name rather than copying a Linux systemd unit:

pkg info cups
sysrc cupsd_enable
service cupsd status

If CUPS is intended to start at boot, persist the rc setting and start it through the service framework:

sysrc cupsd_enable="YES"
service cupsd start
service cupsd status

Use the package manager to maintain the CUPS installation and record its version. A package upgrade can change filters, driver availability, or supported printer backends. Check package notes and the installed manuals before changing configuration syntax.

Keep the configuration file’s ownership and mode intact when making changes. Back up /usr/local/etc/cups/cupsd.conf and inspect the diff before reload or restart. Avoid substituting a permissive sample configuration found online; CUPS’ own FreeBSD article warns that one troubleshooting sample sacrifices security for easier configuration. This article does not recommend opening the administration interface to an untrusted network.

Discover the transport before creating a queue

For a USB-connected device, collect kernel and device-node evidence:

dmesg | tail -80
ls -l /dev/ulpt* /dev/unlpt* /dev/usb/* 2>/dev/null
pkg info | grep -E 'cups|gutenprint|hplip'

The FreeBSD documentation explains that USB printers can appear under device paths that depend on the attached hardware and its enumeration. A node such as ugenX.Y is not itself necessarily the printer’s CUPS backend. Confirm the actual device with the CUPS backend-discovery tool and the relevant device driver.

For a network printer, record its IPP URI and test network reachability separately from queue creation. A successful TCP connection to a printer does not prove that the URI path, authentication, media capabilities, or filter chain is correct. Prefer the printer’s supported IPP endpoint when available; older AppSocket and LPD transports may work but provide different features.

On a server with a locally attached printer, device permissions can prevent cupsd from opening the device even when the queue is configured correctly. FreeBSD’s article documents devfs rules for printer nodes and a devfs ruleset applied through rc.conf. Device names and paths are hardware-specific, so derive them from the host rather than granting broad access to every device node.

For a network-only CUPS server, do not add a devfs rule unless a local device requires it. Separate local USB access, IPP listener policy, and queue authorization: solving one does not solve the others.

Define a queue and verify its state

Use CUPS’ administration interface or command-line tools to create a queue, but first identify the printer’s actual URI and capabilities. A driverless IPP printer may advertise its own supported formats. Legacy PPD-based drivers can depend on additional packages and may no longer be maintained for all devices. Do not assume that installing CUPS makes every printer model usable.

List known devices and queues after startup:

lpinfo -v
lpstat -r
lpstat -t

lpinfo output describes available backends, not necessarily a verified end-to-end print path. lpstat -r indicates whether the scheduler responds; queue status can still be paused, rejecting jobs, or unable to reach the device.

When using lpadmin, preserve an explicit queue name and URI in configuration management. For a lab queue, use an actual IPP device URI that has already been tested, rather than a placeholder such as ipp://printer.invalid. After adding a queue, inspect the selected model or driver, the queue’s enabled state, and any default-printer assignment. Avoid setting a system-wide default when the machine should only expose named queues.

Test jobs without confusing acceptance and output

Submit a small, known-safe text file and observe its state:

printf 'CUPS acceptance test\n' > /tmp/cups-test.txt
lp -d test_printer /tmp/cups-test.txt
lpstat -o test_printer

Replace test_printer with the real queue. A job accepted by the scheduler is not proof that paper came out. Track the job ID, scheduler state, backend logs, printer display, and physical output. For a network device, confirm that the server can reach the URI and that the printer reports the expected job completion.

Use cancel with an exact job ID when a test needs to be stopped. Avoid repeatedly resubmitting the same job while the queue is stalled; retries can produce duplicate pages once connectivity recovers. Print a test page only when the device and queue are intentionally configured for it.

For clients, test the queue URI from one client before enabling printer discovery across a subnet. The FreeBSD CUPS article documents IPP-style URLs for clients. DNS resolution, firewall access to the intended listener, queue access rules, and client-side CUPS configuration should be checked separately. Discovery traffic is not a substitute for a documented queue endpoint.

Diagnose the layer that failed

If cupsd does not start, inspect service status, the CUPS error log, file permissions, and configuration syntax. If the daemon starts but no device appears, check the backend, kernel messages, USB node, or network URI. If a queue exists but jobs remain pending, inspect queue state, device reachability, filters, and scheduler logs. If a job completes but output is wrong, check the selected driver or media options rather than restarting the host.

For local USB permission failures, compare the CUPS service identity and group membership with the device node owner and the configured devfs ruleset. After changing devfs rules, reload or restart the supported devfs service path and inspect the resulting node mode. Do not change /dev node permissions manually as a persistent fix; device nodes are recreated and the correction will disappear.

For network-client failures, compare a working and failing client’s route, DNS answer, IPP URI, and access policy. A queue can be local-only while the scheduler itself is healthy. Do not respond by binding to every interface and allowing all clients. Use an approved network range, a host firewall, and CUPS access policy suited to the environment.

Capture logs before restart. A restart clears useful transient context and can interrupt unrelated queues. Record the queue name, job ID, device URI, CUPS version, relevant package versions, and exact error text. If the failure follows an upgrade, reproduce on a test host and compare package changes before rolling back.

Migration and acceptance

When migrating from LPD, inventory printcap entries, spool paths, filters, clients, and printer-side behavior before changing the server. Translate one queue at a time and preserve the old endpoint until clients have been tested. The two systems can have different queue names, transport URIs, access rules, and job-state semantics. Avoid enabling both daemons against the same physical device without understanding their device access and spool ownership.

A queue is accepted only when the scheduler is running, the intended clients can reach the approved IPP endpoint, a harmless test job reaches the correct printer exactly once, and the resulting page matches expected content and media. Document the upgrade and rollback path, queue URI, responsible owner, log location, and the device-specific permissions required.

CUPS centralizes job scheduling and protocol handling. It does not guarantee printer firmware health, correct filters, physical paper delivery, or duplicate-free behavior after every transport failure. Measure those boundaries rather than treating a green queue status as a complete service check.

Related:

Sources: