Replace USB boot key on FreeNAS

You don’t really install FreeNAS as you do with some other OS. Instead you have a device (often an USB key) that boots FreeNAS which itself manages your data storage. Indeed why wasting some precious SATA port for a boot device when all you need is a little USB key? Especially when thits boot device is less than 2GB in size.

The problem with USB keys is that they wear out over time. So it inevitably comes a time when it must be replaced. This is what happened to me a few days ago.

The freenas-boot pool switched to a DEGRADED state because checksum error happened too frequently. Fortunately a zpool scrub freenas-boot detected no error, and it seems that zfs was still able to correct those. So instead of reflashing a new USB key and restoring my config backup, I could from FreeNAS itself create a new bootable USB key and replace replace the faulty device in the freenas-boot pool.

Let’s login on FreeNAS and plug in your new USB key. We first find and verify what is the device name for the USB key, in my case it’s da2:

$ gpart part show da2
=>       1  60088319  da2  MBR  (29G)
         1        31       - free -  (16K)
        32  60088288    1  fat32lba  (29G)

You see that MBR table and a FAT32 partition, in my case it can only be the new USB key. We will replace that with GPT partitions. This will contain a boot partition (MBR boot or EFI boot), and a ZFS partition. As root:

# Clean that MBR and create GPT partition table
gpart destroy -F da2
gpart create -s GPT da2

# If you use MBR boot
gpart add -s 64K -t freebsd-boot da2
gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 da2

# If you use EFI boot
gpart add -s 128M -t efi da2
gpart bootcode -p /boot/boot1.efifat -i 1 da2

# Create the ZFS partition
gpart add -t freebsd-zfs da2

Now it’s time to replace the device:

$ zpool replace -f freenas-boot da1p2 da2p2
cannot replace da1p2 with da2p2: device is too small
# OOPS! :(

If you got the message device is too small, that is because you’ve been trying to replace a device with another one that is smaller than the original (in term of ZFS partition size I suppose). ZFS requires that you replace a device with another with a size greater or equal to the old one. This can be a problem especially if you have a ZFS partition along with others in the partition table like here, or if the vendor announces a certain disk size but only within a certain approximation. You could result in a disk announced to be the exact same size ending up to be very slighty shorter than your original disk. And as a result you won’t be able to use it to replace any disk in your ZFS pool/vdev. That’s why some recommend to create ZFS filesystems several percents less than the available disk size.

But since we messed up, instead we will create a pool on the other USB key and use ZFS send/recv to migrate the files.

# Create the pool on the new USB key.
# Note that we have to call it freenas-boot2
# because freenas-boot already exists.
zpool create freenas-boot2 da2p2 

# Create a recursive snapshot of the original pool
# that we will use to restore the backup. 
zfs snapshot -r freenas-boot@restore

# Send the snapshot from the old to the new USB key.
zfs send -R freenas-boot@restore | zfs recv -F freenas-boot2

We also need to save the original setting for bootfs because FreeNAS has its own way of managing the boot pool. We will set this value later on the new pool.

$ zpool get bootfs
NAME          PROPERTY  VALUE                        SOURCE
freenas-boot  bootfs    freenas-boot/ROOT/11.3-U4.1  local

We still have to change that name from freenas-boot2 to freenas-boot. However we cannot do so on the running instance of FreeNAS because it already has a pool named freenas-boot. So, we will import it on another ZFS capable machine and fix its name.

(but if anyone knows how to do this live, I’m interested)

# On some other ZFS capable host (FreeBSD for instance ;) )
# import the pool and change its name back to freenas-boot.
# The -f is required because it comes from another host.
zpool import -f freenas-boot2 freenas-boot

# Configure default boot filesystem.
# Remember the value of bootfs we found before on the original pool.
zpool set bootfs=freenas-boot/ROOT/11.3-U4.1 freenas-boot

# Export the pool again.
zpool export freenas-boot

Finally you can clear the old snapshot:

zfs destroy -R freebsd-boot@restore

USB printer in FreeNAS jail

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

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

Bhyve OpenBSD on FreeNAS

Lately I’ve been playing with bhyve on FreeBSD and FreeNAS in the prospect of spinning up small VMs for a mini compile farm (and just as an excuse to play around). In this post I will share my experience in installing OpenBSD 6.4 as a bhyve UEFI VM on FreeNAS-11.2 through the new GUI.

This post is divided in three parts. First the creation of the VM through FreeNAS new GUI. Then the installation of OpenBSD from boot to finish. Lastly some bits of documentation and related posts that were helpful along the way.

Create the VM

The installation will go through serial instead of VNC. Also, instead of the CDROM ISO we use a disk image for the installation.

In the FreeNAS GUI, selects Virtual Machines > ADD, then proceed with the wizard. Some parameters of the wizard are pretty obvious, so there won’t be an explanation for each one of them. If need be, check the FreeNAS doc on creating VMs.

Guest Operating System, not exactly sure what this does. Guess it’s basically a template for the next steps of the wizard. Since this is a BSD system, select FreeBSD as this is the closest there is.

We don’t need VNC, so make sure that Enable VNC is unchecked. As for Boot Method, you can select UEFI, you don’t need UEFI-CSM.

For the hard disk in Select Disk Type and similarly for the network interface in Adapter Type, select a VirtIO type.

For the Installation Media, leave it blank. This is for an ISO image but OpenBSD’s installXX.iso didn’t work so we are going to use a raw disk image instead.

Go ahead and create the VM. But don’t start it yet. We have to add a raw disk device.

Fetch installXX.fs from OpenBSD download page, and put it somewhere on the FreeNAS host. For the following, I’ll assume this is install64.fs.

Then select Devices > ADD for the VM. Select Type: Raw File and Raw File: the location of install64.fs on the FreeNAS host. Also Mode: VirtIO; Device Order: 1003 (the device order is important, otherwise the OpenBSD install would incorrectly guess the target device); Raw filesize: 1 (which means 1GB).

Now you can start the VM and open the Serial console. You should be greeted by:

>> OpenBSD/amd64 BOOTX64 3.40
boot>

Time to install OpenBSD!

Install OpenBSD

You are on the serial console with the OpenBSD install bootloader waiting for you. On the console boot>, type set tty com0, then boot.

Do not directly start the installation, we first have to create the EFI partition, so select (S)hell instead. At the command prompt, create the EFI partition as described below, then start the install.

## Check that sd0 is the correct target device
# disklabel -p M sd0
...
16 partitions:
#                size           offset  fstype [fsize bsize   cpg]
  c:         15625.0M                0  unused

## Initialise a GPT partition table with the special boot partition on sd0.
# fdisk -iyg -b 960 sd0
Writing MBR at offset 0.
Writing GPT.

## Start the installer
# install

At the partitioning step, select (O)penBSD area. We will setup a single root partition layout. You should know that the OpenBSD bootloader likes its root partition on slice a of the first hard disk, so we create the layout that way.

# Check the current partition
> p M
OpenBSD area: 1024-31999937; size: 15624.5M; free: 15624.5M
#                size           offset  fstype [fsize bsize   cpg]
  c:         15625.0M                0  unused                    
  i:             0.5M               64   MSDOS 

# Start with the root partition.
# Again, the bootloader likes it that way.
> a
...
size: {your-root-partition-size}M
FS type: 4.2BSD
mount point: /

# Now the swap partition
> a
...
FS type: swap

# Check again
> p M
OpenBSD area: 1024-31999937; size: 15624.5M; free: 0.0M
#                size           offset  fstype [fsize bsize   cpg]
  a:         15493.9M             1024  4.2BSD   2048 16384     1 # /
  b:           130.5M         31732576    swap               
  c:         15625.0M                0  unused                 
  i:             0.5M               64   MSDOS

# Quit and save
> q
Write new label?: y

Proceed with the installation and the file sets and once you are done, reboot in your new system. Remove the Raw File device from the VM and on the VM itself, use syspatch to patch the base system. Finally reboot and you are done!

Relevant bits of documentation

Samba denied on FreeNAS

If you recently discovered that some of your authenticated samba shares on your FreeNAS refuse to well authenticate. And maybe you did your own investigation and found that it failed with NT_STATUS_NO_SUCH_USER. Do not worry, you are not alone!

From what I understand, the last update changed the constraints on the user accounts metadata. In particular it seems that the E-Mail field must now point to a real e-mail address (something@domain) and cannot just be an alias to another local user.

Don’t know if that’s intended or not or why it would be. Going to IRC right now to find out.

Long story short, users that don’t match the new constraints are not recognized anymore by samba (and probably other services too), hence the permission denied and NT_STATUS_NO_SUCH_USER. So for those user using a local alias as E-Mail, use a fully qualified E-Mail. That will fix the shares. However it seems that "user"@localhost doesn’t work either. And you will also have to retype their password.

Wrong OS version in pkg

If FreeBSD’s pkg refuses to update because of a wrong OS version, for example because you are in a FreeNAS jail and version mismatch are bound to happen, then you can always try to force the OS version in pkg (which you can find with uname -UK. Either put OSVERSION={{version}} in /usr/local/etc/pkg.conf or start it with pkg -o OSVERSION={{version}} where {{version}} is the target version, for example 1101001.

NAS (pt. 1): Parts and build

In a previous post, I explained how a disk failure prompted me to build that NAS I’ve dreamed of for years. That happened months ago, but in the meantime we’ve been reviewing mainboards, CPU specs, reading other configurations over and over again. We finally settled on a setup of our own.

We did so with a set of constraints. First anything with less than 4 HDD was out of the question. You need at least 3 HDD for RAID5, 4 for RAID6, with RAID1 (mirroring) and only 2 HDD you would waste half of your total disk space, and RAID0 (no redundancy) would be completely insane, disk failures do happen, believe me! Since we also want to upgrade our setup, we looked for mainboards with at least 6 SATA.

Second, it would run FreeNAS, anything else doesn’t come close. We avoided some component that are known to cause trouble in FreeBSD, mostly some NIC. Although as far as I can remember I didn’t have any problem for a while.

Finally I’ve been a long time advocate of ECC memory for NAS. However ECC memory is expensive and finding cheap and reliable mainboard/CPU that support ECC is difficult. So we relaxed that constraint. But I’d be happy to know about any good alternative.

Parts

Our base setup is 12TB HDD / 16GB RAM upgradable to 24TB HDD / 32GB RAM. Total cost was 688€ and 310€ without any HDD. We were lucky enough to receive HDD from different batches even though we bought all of them from the same vendor. Similar HDD would increase the risk of multiple disk failing at the same time (which is a very bad thing for a RAID5 setup).

  • CPU: Intel G3900
  • MB: Gigabyte GA-B150M-DS3P
  • RAM: 2x8GB Crucial DDR4
  • HDD: 3xWD Red 4TB
  • PSU: Corsair VS350
  • Case: CoolerMaster Elite 343
  • USB: SanDisk Cruzer Fit SDCZ33-016G-B35

Now if we could change only one thing, that would be the CM Elite 343 case. While it is possible to mount 6 HDD, their positioning is not optimal and arranging the cables properly was difficult.

Build

The build was relatively straight forward. As I said we had some problem with the CM Elite 343 case. Another problem was the SYS_FAN cable from the case which was too short to reach the MB. We also had some problem with one of the two mainboards which constantly rebooted. We had to reset the CMOS to fix it. But now everything works flawlessly.

I already booted FreeNAS 11, everything seems to be working properly. The idle consumption is 28W, peaks at 60W on boot, but we’ll see about that when the system will be fully installed. The setup is amazingly silent, although the front system fan is not connected for now.

In the next episode I will install and configure FreeNAS on Gandalf (it already has a name).  Until then I’m going to fold the gazillion amazon boxes spread all over my apartment.