Running a printer in a FreeNAS jail may be interesting for home users, especially if you have one of those GDI printers that only provide a x86/amd64 driver for Linux/FreeBSD, and more especially if you happen to have a FreeNAS box in your living room with some free USB ports.

While exploring the subject, I’ve come across several solutions to use FreeNAS as a printer server. Some explain how you could install the printer inside (a very old version of) FreeNAS itself, which you should seriously not do. Not only all your changes would be overwritten by updates, but it offers limited flexibility and very little guarantee that anything will work or keep working in the future. Even if FreeNAS is FreeBSD at its core, it’s not supposed to be used as a full-fledged OS, if you want that, you should use a VM or a jail. Other solutions explain how to install the printer inside a jail but generally expose all the devices inside the jail just to access the printer. I’ve even heard of someone giving up half way to the solution presented here only to deploy a Windows VM in FreeNAS just to get the printer running.

Part 1: USB inside the jail

The main challenge will be to have the USB printer to appear inside the jail. That is for the device file to appear inside the jail /dev directory. By default, the content of this directory is pretty minimalist.

On FreeBSD (and FreeNAS), the creation of device files in /dev is handled by devfs. Each devfs mount has an associated ruleset number specifying how devices must be created on this mount-point.

FreeNAS uses iocage to manage its jails. You can get the ruleset associated to the jail devfs mount with the following command:

$ iocage get devfs_ruleset {myjail}
5

By default, this is ruleset number 5. You can list the rule in this ruleset with the command devfs rule -s 5 show, see how it matches devices that you find under your jails.

We will create a custom ruleset for our jail that also include the USB device of the printer. The script will even detect the USB port automatically. But first let’s check if we see the printer and its name:

$ usbconfig
...
ugen0.3: <Kyocera FS-1041> at usbus0, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA)
...

We will create a new ruleset number 1000 that includes ruleset number 5 and unhides the necessary device for the jail. Also USB devices need to be owned by the group cups and permission 660. Normally, the cups port/package adds a file in /usr/local/etc/devd to change the group owner and permission when a new USB device is plugged in. However devd doesn’t work in jails, so we will also have to change these using devfs.

On a normal FreeBSD system, we could setup this ruleset in /etc/devfs.rules, however this file would be rewritten in FreeNAS on each reboot/update. Instead we create a script that will be started on each boot. We can also use this script to detect the USB port on which the printer is connected. In my case I store this script in my home directory on its own dataset (so it won’t be overwritten on reboot), but you can use any of your datasets. For this example the script will be in ~myuser/myjail-devfs-ruleset.sh.

Let’s edit that with nano:

#!/bin/sh
# Custom ruleset for jails

export PATH="/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin"

RULESET=1000
CUPS_GID=193
PRINTER_NAME="Kyocera FS-1041"

# Find the printer device.
UGEN_DEV=$(usbconfig | grep "$PRINTER_NAME" | cut -d':' -f 1)
USB_DEV=$(readlink /dev/$UGEN_DEV)

if [ -z "$UGEN_DEV" -o -z "$USB_DEV" ]
then
  echo "error: cannot find printer '$PRINTER_NAME'"
  echo "error: please check with usbconfig"
  exit 1
fi

echo "Found $PRINTER_NAME on $UGEN_DEV"

# Clean the ruleset
devfs rule -s $RULESET delset

# Include jails default ruleset and unhide USB device.
devfs rule -s $RULESET add include 5
devfs rule -s $RULESET add path usb unhide
devfs rule -s $RULESET add path $USB_DEV mode 660 group $CUPS_GID unhide
devfs rule -s $RULESET add path $UGEN_DEV mode 660 group $CUPS_GID unhide
devfs rule -s $RULESET add path usbctl mode 644 unhide

In this script you should edit PRINTER_NAME with the name of the printer found with usbconfig. You should also edit CUPS_GID with the gid of the cups group inside your jail (generally this is 193) and edit the RULESET number if needed.

Now adjust the permission and execute this script. We will also check that the rules are applied correctly:

$ chmod a+rx ~myuser/myjail-devfs-ruleset.sh
$ sh ~myuser/myjail-devfs-ruleset.sh
Found Kyocera FS-1041 on ugen0.3
$ devfs rule -s 1000 show
100 include 5
200 path usb unhide
300 path usb/0.3.0 unhide group 193 mode 660
400 path ugen0.3 unhide group 193 mode 660
500 path usbctl unhide mode 644

As you can see, the ruleset has been created correctly. We will now change the devfs ruleset used for the jail. In FreeNAS you can either do that in the GUI in Jails > myjail > EDIT > Jail Properties > devfs_ruleset or use the command line. Note that the jail has to be stopped before you can do the modifications. Let’s use the command line in our case:

$ iocage stop myjail
* Stopping myjail
  + Executing prestop OK
  + Stopping services OK
  + Tearing down VNET OK
  + Removing devfs_ruleset: 5 OK
  + Removing jail process OK
  + Executing poststop OK
$ iocage set devfs_ruleset=1000 myjail
$ iocage start myjail
* Starting myjail
  + Started OK
  + Using devfs_ruleset: 1000
  + Configuring VNET OK
  + Using IP options: vnet
  + Starting services OK
  + Executing poststart OK

Login into your jail and check that /dev/ugen0.3 and /dev/usb/0.3.0 are accessible and owned by cups. Now we will make this configuration persistent across reboot. Iocage jails have a exec_prestart property executed before applying the devfs ruleset. However if iocage detects that the devfs ruleset does not exist, it will fall back to a default ruleset. In our case, this means that iocage will always revert to this instead of using our ruleset. Instead we could execute the script as an init task in FreeNAS GUI. However it seems that when a jail is onfigured with Auto-Start, it is started before the Pre-Init tasks. Therefore we configure devfs and then start the jail manually. Create another file (for example in ~myuser/start-jails.sh):

#!/bin/sh
# Manually start jails.

sh ~myuser/myjail-devfs-ruleset.sh
/usr/local/bin/iocage start myjail

Go into Tasks > Init/Shutdown Scripts and ADD one with those info:

Type: Script
Script: ~myuser/start-jails.sh
When: Post Init
Enabled: Yes
Timeout: 10

Another problem is that iocage removes the configured devfs ruleset when the jail is stopped. So if you restart after that, the configured ruleset would not exist and iocage would switch to a default empty one that would expose all your devices in the jail. To fix that, we configure a property to also execute our script when the jail stops:

$ iocage set exec_poststop=$(ls ~myuser/myjail-devfs-ruleset.sh) myjail
exec_poststop: /usr/bin/true -> ~myuser/myjail-devfs-ruleset.sh

Finally go into the FreeNAS GUI and disable Auto-Start (Jails > myjail > EDIT > Auto-start: off).

Note that none of these shenanigans would be necessary if iocage did not fall back on another ruleset if the one specifed in the devfs_ruleset property did not exist. But unfortunately, it doesn’t. If you have a nice idea on how we can get around this problem, please feel free to comment below!

You are done with this part. The jail is now ready with the USB device for the printer (and no more than that) accessible in its dev directory.

Part 2: Install the printer on CUPS

Since this is a post about running a printer in a jail, there must be a step where we install CUPS and the printer itself within the jail. For anyone that has already installed printers on *BSD or Linux, this should be pretty straightforward. I will not go into the details and assume that the printer is compatible with the default CUPS filters.

Let’s install cups. I do so via ports to remove some of the defaults options. Otherwise cups and cups-filters would depend on wayland avahi and a lot other stuff. If you are fine with that though, you can just pkg install cups cups-filters. Via the ports, it’s a bit more involved:

$ cd /usr/ports/print/cups
$ make install clean
(remove AVAHI and DBUS)
...

# Install some dependencies as packages
# so you don't have to compile them from sources.
# Some would say you should not do that.
# But I don't.
$ pkg install ghostscript9-agpl-base qpdf
...

# Install cups-filters.
$ cd /usr/ports/print/cups-filters
$ make install clean
(remove COLORD, AVAHI, LDAP)
(select PSGHOSTSCRIPT as default PDF-to-PS renderer 
 since POPPLER would depends on wayland too)

# Lock the ports to avoid updates by pkg.
pkg lock cups cups-filters

Add cupsd_enable="YES" in /etc/rc.conf to start cups on boot. Start it with service cupsd start. By default, cups is only accessible on https://localhost:631, we will use a ssh tunnel to access it and configure the printer:

ssh -NL 10631:localhost:631 {myjail-ip-or-hostname}

Use your web browser and go to https://localhost:10631 and you should see CUPS. If you don’t have a root password on your jail (and only use sudo), it might be a good idea to setup one with passwd, even if only temporary while you install the printer.

If you have a GDI printer that needs a special binary filter that only works on Linux, you should load the linux and linux64 modules in FreeNAS and install linux-c7 in the jail:

###############################################
# Only if you need a Linux only binary filter #
###############################################

# Add to ~myuser/myjail-devfs-ruleset.sh
kldload linux
kldload linux64

# In the jail:
pkg install linux-c7

Go into Administration > Add Printer, it will ask for credentials, enter root and your root user password (don’t worry you only need to do this to install the printer). Hopefully you should see your printer in local printer.

Select it and continue. Configure name, description and location. Enable the Share checkbox, since you probably want to share this printer on your network. Continue, and select the appropriate printer model then Add printer. Set the default options.

You will be redirected to https://localhost:631 but this won’t work through the ssh tunnel (with local port 10631) so do not worry if the browser says that the site is not reachable. Just retype the URL and go to the printers https://localhost:10631/printers, select it, then Maintenance > Print Test Page.
If the CUPS Printer Test Page comes out of the printer at this point, congratulation! You’ve successfully configured a USB printer with CUPS inside a FreeNAS jail!

If on the contrary nothing comes out, remain calm, /var/log/cups/error_log might be of some use.

Part 3: Share CUPS with your network

We still have to make cups available on the network. To do so, edit /usr/local/etc/cups/cupsd.conf. You can find an example of this configuration in this CUPSD configuration example. In this example, we let everyone on the local network browse the CUPS server and create print-job. The job owner can cancel its own job and all other administrative tasks and printer manipulation are restricted to localhost. For those later operations, you should connect to cups using the ssh tunnel method presented above.

On each client (assuming that it has cups installed), you can configure /etc/cups/client.conf (Linux) or /usr/local/etc/cups/client.conf (FreeBSD) with the hostname of your jail:

ServerName {hostname-or-IP-of-CUPS-jail}

The printer should now be available. Check that lpstat works without error. If you have a problem, again have a look at /var/log/cups/error_log in the jail, it should give you a good start for debugging.

Part 4: Profitsssss

Great profitssssss

[1] Is it possible to access a USB printer from inside a jail?
[2] Enable sound inside jail
[3] Absolute FreeBSD, 3rd Edition: The Complete Guide to FreeBSD
[4] Exposing Device Files to FreeBSD Jails
[5] Ruleset exists but iocage does not find it #952
[6] USB (Z-Wave) device no longer shows up in iocage jail on FreeNAS 11.2
[7] USB device inside a linux jail (devfs)

UPDATE:

• It seems that with TrueNAS 12 the DevFS ruleset 5 does not exist anymore. As far as I remember these rules did hide everything then unhide the minimum necessary for a working jail. Now when creating the jail DevFS ruleset, you have to add the following rules:
  • hide
  • include 2
  • include 3