Saturday, February 27, 2016

Installing FreeNAS 9.3 Over the Network

As users of new Skylake (LGA1151) systems are discovering, Intel has completely removed EHCI support from the new architecture. XHCI (USB 3.0) is supposed to be completely backwards compatible to USB 2.0, but the lack of EHCI support has some less than pleasant effects on trying to boot from USB using any OS that is expecting USB 2.0 support. Specifically, this means that GRUB 2 cannot currently boot an OS on XHCI-only systems, which makes installing FreeNAS a bit of a pain.

The symptom of this problem is that on XHCI systems the boot process will proceed up to the point where it tries to mount the root filesystem, and then it will die with an "error 19".
Trying to mount root from cd9660:/dev/iso9660/FreeNAS_INSTALL []...
mountroot: waiting for device /dev/iso9660/FreeNAS_INSTALL ...
Mounting from cd9660:/dev/iso9660/FreeNAS_INSTALL failed with error 19.

This is actually a problem that affects all XHCI systems, but if your system supports both EHCI and XHCI, you can disable XHCI in the BIOS to make USB booting work. Skylake systems, however, have no EHCI support at all, not even on the USB 2.0 motherboard headers, so this workaround isn't available.

Some people have found success with PCI cards that add EHCI USB ports, but you have to use caution with this approach since many (most?) PCI USB cards don't provide bootable USB ports. I didn't want to have to go pick up extra hardware just to install the OS, so I've opted for another approach: load the installer over the network via PXE.

The FreeNAS developers use PXE booting when testing new builds, and there is a guide for doing this with FreeNAS 9.2. However, the guide is two years old and I found it to be missing several steps when trying to apply it to a current version of FreeNAS. It's even worse when trying to use current versions of the FreeNAS developers' tools, as they're completely missing large sections of setup instruction (they're clearly not intended for use outside the project).

So, I'm publishing an update to the guide here. Eventually this will be out of date too, but hopefully it will save someone time down the road.

If you want to follow this guide you will need:
  1. a FreeBSD server which will be your PXE and DHCP server
  2. a machine you want to install FreeNAS on (presumably you already have this, since you're reading this guide)

Set up the BIOS

You'll want to modify your system BIOS boot order on the NAS host to make sure that PXE (or Network) boot is enabled, and will be attempted before any other valid boot option (e.g. if there's an OS on any disk in your system, that disk should be ordered after the PXE boot). Exactly how you do this is going to be specific to your BIOS.

Setting up the DHCP Server

Install the isc-dhcp43-server package, and use a config file that looks mostly like the following.  Update it for the subnet you use on your network:  "next-server" should be the IP address of your PXE server.
subnet 192.168.57.0 netmask 255.255.255.0 {
    range 192.168.57.100 192.168.57.200;
    option subnet-mask 255.255.255.0;
    option routers 192.168.57.1;
    option broadcast-address 192.168.67.255;
    option domain-name-servers 192.168.57.1;
    option domain-name "mydomain.com";

    next-server 192.168.57.10;
    filename "boot/pxeboot";
    option root-path "/tftpboot/installer/";
}

Prepare the Installer

You need a copy of the FreeNAS installer ISO coped out onto the PXE server's filesystem. The following pair of commands will get the current version I'm using:
mkdir -p /tftpboot/installer
fetch -o - http://download.freenas.org/9.3.1/latest/x64/FreeNAS-9.3-STABLE-201602031011.iso | bsdtar -x -f - -C /tftpboot/installer/

Set up NFS

First, permit the installer you just set up to be exported, and start up NFS.
echo '/tftpboot -ro -alldirs' >> /etc/exports
echo 'nfs_server_enable="YES"' >> /etc/rc.conf
service nfsd start
Next, instruct the installer to mount its root filesystem from the NFS export you just setup. Be sure to set the hostname of your pxeserver (or its IP address) correctly in the fstab entry.
mkdir /tftpboot/installer/etc
echo 'pxeserver:/tftpboot/installer   /   nfs   ro   0 0' >> /tftpboot/installer/etc/fstab

Setting up TFTP

Modify the tftp lines in /etc/inetd.conf to look like the following:
tftp  dgram  udp   wait  root  /usr/libexec/tftpd  tftpd -l -s /tftpboot/installer
tftp  dgram  udp6  wait  root  /usr/libexec/tftpd  tftpd -l -s /tftpboot/installer
Finally, enable inetd and test your tftp server:
echo 'inetd_enable="YES"' >> /etc/rc.conf
service inetd start
tftp localhost
tftp> get boot/pxeboot
Received 231424 bytes during 0.0 seconds in 454 blocks

Boot!

That's it. You should now be able to boot the installer over the network, and install FreeNAS on a disk installed in your NAS server.  Don't forget to consult the FreeBSD handbook section on diskless booting if you need help troubleshooting anything.  After installing, you may need to alter the boot order again to ensure that your freshly installed OS is booted before PXE.

Good luck!