TrueNAS Print Server: Running CUPS as an App

TrueNAS has no built-in print server: neither the 25.10 Services screen nor the official apps catalog offers CUPS or any print service. To share a printer from TrueNAS, you deploy CUPS yourself as a custom Docker app through Install via YAML, or run it in a VM. If the printer already speaks IPP or AirPrint, you may need neither.

The steps below use the custom Docker app interface documented for TrueNAS 25.10 and keep the printer configuration separate from the appliance’s file-sharing service.

The main decisions are printer compatibility, persistent storage, device access and network discovery. The container image determines which drivers and discovery services are available; the Compose outline below is a configuration example, not a verified image recommendation.

First, check whether you need one at all

A print server solves a problem many networks no longer have. Before building anything, work out which situation applies.

IPP Everywhere is designed for driverless network printing between compatible printers and clients. Adding CUPS in that case introduces a queue that can jam, a container that can fail an update, and a dependency on the NAS being up in order to print.

The two cases where it genuinely pays off are a USB-only printer that several machines need, and an older network printer you want to reach from phones and tablets that expect AirPrint.

Ways to run a print server on TrueNAS, compared

The VM’s edge is USB identity: its device screen can pick the printer by Vendor ID and Product ID, while a Compose mapping names a bus/device node that can change. This guide uses the lighter container route.

What about a FreeNAS or TrueNAS CORE print server?

On FreeNAS and its successor TrueNAS CORE, a print server usually meant running CUPS inside a FreeBSD jail, because CORE’s services list has no print service either. That route is closed: 13.3-U1.2, released 29 April 2025, was CORE’s final release, and iXsystems lists plugins, jails and VMs on 13.3 as untested and unsupported.

iXsystems renamed TrueNAS SCALE to TrueNAS Community Edition with 25.04 in April 2025, and the 13.3 notes name 25.10 as the migration path. Jails do not carry across: record each queue’s device URI with lpstat -v before retiring the jail, then rebuild it as the custom app below.

What the deployment actually consists of

CUPS runs as a single container. Its administration interface listens on port 631. It needs three things to be useful, and each is a decision on the TrueNAS side:

1. Persistent configuration. CUPS writes its printer definitions and settings under /etc/cups, and its spool under /var/spool/cups. Mount the image’s documented paths on persistent storage; data left only in the container’s writable layer can disappear when it is replaced.
2. Access to the printer. For a network printer, ordinary outbound networking. For a USB printer, the container needs the USB device passed through from the host.
3. Discoverability. Automatic discovery needs a DNS-SD advertisement and a working multicast path. Publishing the CUPS web port does not provide either.

Getting all three right is the whole project. Each maps onto a specific option in the TrueNAS app installer.

Deploying it via Compose

The guided Custom App form covers image, ports, storage and a fixed set of options. Anything involving device passthrough needs the YAML route, because the form exposes GPU allocation but not arbitrary host devices.

From Apps, open Discover, then the three-dot menu, then Install via YAML. That opens the Add Custom App screen, where the app takes a lowercase alphanumeric name and the Compose content goes into the Custom Config field, beginning at a top-level key such as name:, services: or include:.

The documentation is explicit that this route requires working knowledge of Docker Compose and YAML, and that TrueNAS applies only basic YAML syntax validation without checking the configuration parameters before running it. A file that parses cleanly but names a device that does not exist will save successfully and then fail at container start. Write it in a real editor first and check indentation before pasting.

The shape of a CUPS service is small:

services:
  cups:
    image: <cups image>
    network_mode: host
    volumes:
      - /mnt/tank/apps/cups/etc:/etc/cups
      - /mnt/tank/apps/cups/spool:/var/spool/cups
    devices:
      - /dev/bus/usb/001/004:/dev/bus/usb/001/004
    restart: unless-stopped

Substitute your own pool, dataset paths and actual USB node; omit devices for a network printer. Pick an image whose documentation you have read, including its driver, discovery and authentication requirements. Some images initialise their configuration differently, so an empty mount over /etc/cups is not a universal installation recipe.

Choosing a CUPS image

anujdatar/cups has been installed on TrueNAS through the YAML editor with port 631 and /dev/bus/usb mapped; its README maps /etc/cups to a host folder and defaults the admin login to admin/password. The olbat/cupsd README lists Debian driver packages including printer-driver-all and a print/print login. Neither documents AirPrint advertisement, and olbat’s example mounts the host’s /var/run/dbus, the shortcut warned against below. Change any default login before the app goes live.

Storage: persist configuration and define a restore path

TrueNAS offers Host Path mounts against existing storage and ixVolume storage created on the apps pool. Both are persistent. An ixVolume does not inherently lose its configuration on an ordinary app update. Host Path is useful when you want to choose and identify the dataset yourself.

For this example, create named configuration and spool directories before deploying. Confirm the image’s user can write to them and that mounting an empty directory does not hide required defaults. The HBA and boot guide’s deployment handoff explains the distinction between a system configuration export and app-data recovery.

Include the configuration dataset in a snapshot schedule and an independent backup such as a replication task. Check the restore procedure for the chosen image: the printer definitions, driver packages and image version all matter when recreating the service.

Tmpfs is another storage option, but its contents are temporary. A RAM-backed spool trades persistent queued jobs for memory use and loses those jobs when the container stops. Choose that behaviour deliberately.

AirPrint and Avahi under host networking

A queue that works by IP but never appears in a client picker has a discovery problem. Docker host networking shares the host’s network namespace. It removes the container bridge boundary, but does not start a discovery daemon or enable printer sharing.

CUPS must share the queue and publish suitable DNS-SD service information. On Linux, Avahi commonly supplies the mDNS/DNS-SD service; an image needs working integration with it and any D-Bus service that integration requires. The Avahi documentation separates publishing a service from browsing for it. Having a CUPS process running proves neither is working.

Follow the image’s documented discovery arrangement. Running a second Avahi daemon on the host network can introduce conflicts with a responder already using the same interfaces. Do not mount the host’s D-Bus socket merely to make an error disappear; use an arrangement explicitly supported by the image.

In CUPS, enable sharing for the intended queue as described in OpenPrinting’s sharing guide. Server-wide, cupsctl --share-printers shares with the local network; avoid --remote-any, which extends sharing to any network that can reach the server. Driver support, the queue’s advertised capabilities and client compatibility determine whether an older printer works through AirPrint. Host mode alone cannot turn an unsupported USB printer into an AirPrint device.

Check three layers separately:

1. Open the CUPS interface by the NAS address and port 631 to establish basic reachability.
2. Confirm the queue accepts a job through its IPP address.
3. Check discovery from a client on the same subnet, including multicast filtering and wireless client isolation.

For the host-network arrangement, allow the required IPP and mDNS traffic only on the intended LAN. CUPS uses TCP 631; mDNS uses UDP 5353. Discovery across VLANs needs a separate network design. Avoid enabling unrestricted access from every subnet as a substitute.

Host mode also disables useful port remapping: a second service already listening on TCP 631 can conflict. A bridge arrangement can serve a manually configured IPP address, but automatic LAN discovery needs an additional supported mechanism.

USB printer passthrough to a TrueNAS container

A USB printer needs both a host device node and permission for the container to use it. The Compose devices setting maps a host path into the container. In the example, /dev/bus/usb/001/004 is illustrative: inspect the connected printer and replace both sides with its actual node.

Use this sequence to separate discovery from access:

1. Connect and power on the printer, then identify its USB bus/device entry on the NAS.
2. Confirm the image contains a USB printing backend and the driver or Printer Application required by that model.
3. Add the device mapping and open the app shell. CUPS’s lpinfo -v lists available backends and detected printer URIs.
4. Use the reported printer URI when adding the queue. If the device exists but access fails, check the container user and device permissions.
5. After a printer reconnect or power cycle, repeat the check before assuming the original mapping still works.

USB device numbers can change on re-enumeration. A mapping captured when the container was created may therefore require updating the path and recreating the app. Mapping the whole USB bus directory is broader access and is not, by itself, a guarantee of working hotplug: runtime device permissions and discovery still matter.

Docker documents device cgroup rules separately from device mappings. Follow the image’s hotplug instructions if it supplies them; otherwise treat reconnects as an explicit maintenance step. Avoid privileged mode as a general printer fix.

If the printer appears inside the container but jobs remain queued, distinguish a backend problem from a format problem. The CUPS error log can show whether it failed to open the device or failed while running a filter. A successful device mapping does not prove that a compatible driver is installed.

Driverless IPP Everywhere: when a driver is unnecessary

IPP Everywhere defines driverless printing based on IPP and discoverable printer capabilities. For a compatible network printer, CUPS can query those capabilities instead of relying on a model-specific PPD.

The CUPS administration guide documents selecting the everywhere model for a reachable IPP printer, says it is used for nearly all modern network printers sold since about 2009, and gives the example lpadmin -p printername -E -v ipp://11.22.33.44/ipp/print -m everywhere. Use the IPP URI reported by discovery or the printer’s documentation. Guessing a path from another model can leave a queue pointing at the wrong endpoint.

That selection does not provide a missing USB driver. An older USB-only device may still need a model-specific backend, filters or a compatible Printer Application. Check support for the exact model and the container architecture before choosing an image.

Prefer direct client-to-printer IPP when it already meets the need. A CUPS relay is useful when it supplies a shared queue or compatibility layer the printer lacks, and its availability then becomes part of the printing path.

What about sharing the printer over SMB?

Not on TrueNAS, even though Samba itself supports printer sharing. The smb.conf reference documents a [printers] section and the print-related parameters that go with it, and a Samba server configured that way advertises print queues to Windows clients the same way it advertises file shares.

That is not a route to take on TrueNAS. The appliance generates its Samba configuration from its own middleware, and the share types offered in the interface are file shares. A hand-edited smb.conf on an appliance whose configuration is machine-generated is not a persistence path you can rely on across updates, and the SMB share configuration TrueNAS does support is aimed squarely at datasets rather than devices.

If Windows clients need to reach the queue, CUPS handles that itself over IPP. Windows has included the Microsoft IPP Class Driver since Windows 10 21H2, and on Windows 11 its driver ranking prefers that class driver over vendor drivers from July 1, 2026. That keeps the print configuration inside the container where it is backed up with the rest of the app data.

A job was sent but nothing printed

When a client reports success and no paper appears, work from the queue outward in the app’s shell:

1. lpstat -t shows scheduler status, each printer’s device, whether it is enabled and accepting jobs, and the job list.
2. A disabled printer stopped itself: the cupsd.conf default ErrorPolicy is stop-printer, so one failure halts the queue. Fix the cause, then run cupsenable on it.
3. lpstat -W completed -o lists finished jobs. A job CUPS marked completed points at the driver or the printer, not TrueNAS.
4. Run cupsctl --debug-logging, print a test with lp -d printername file, and read the [Job NNN] lines in the error log, since the default LogLevel of warn hides most detail. Undo it with cupsctl --no-debug-logging.

The log defaults to /var/log/cups/error_log, but cups-files.conf also accepts stderr, which for a scheduler running in the foreground sends entries to the container’s log output instead.

Troubleshooting queue and discovery failures

Most failures at this stage are CUPS configuration questions, answered in the CUPS documentation rather than the TrueNAS docs.

Keep it on the LAN

CUPS is an administrative web interface with the ability to execute filters on submitted jobs. There is no reason for it to be reachable from outside the network, and the reflexive move of adding a reverse proxy entry for every app should not extend to this one.

Bind it to the LAN, leave it out of any port forwarding, and reach it over the VPN if remote access is genuinely needed. The same reasoning applies to any custom app deployed through the YAML route, which is a deployment path with deliberately less validation than the catalogue apps get.

Where this fits

A print server is a small app with an outsized number of edge cases. The general mechanics behind it, including what changed when the app backend moved off Kubernetes, are covered in moving apps to Docker. For a provisional allowance for several services together, the TrueNAS RAM and ARC Calculator takes app count as an input and explains its assumptions.

FAQ

Can TrueNAS share a USB printer through CUPS?

Yes, when the custom app has device access and the image has a compatible backend and driver. Map the printer’s actual /dev/bus/usb node under Compose devices, confirm it with lpinfo -v in the container, and recheck after reconnecting the printer, because the number can change.

Does host networking automatically enable AirPrint?

No. Host networking only removes the container’s network boundary. The queue must also be shared in CUPS and advertised through DNS-SD by a working Avahi arrangement, and that multicast advertisement must reach clients on UDP 5353. Wireless client isolation or a VLAN boundary hides the printer anyway.

Does IPP Everywhere work with every USB printer?

No. IPP Everywhere describes driverless printing to printers that report their own capabilities over IPP, and the CUPS everywhere driver is used for nearly all modern network printers sold since about 2009. A legacy USB-only printer can still need a model-specific driver, filter or Printer Application inside the container.

Does ixVolume lose CUPS settings during updates?

No. An ixVolume is persistent storage on the apps pool and survives an ordinary app update. If printer definitions disappear, check the mount path against the image’s configuration directory, how it initialises an empty mount, and file ownership. Persistence is not a backup, so snapshot and replicate the dataset too.