Automating the deployment of FreeBSD & PC-BSD® systems
byKris Moore
kris@pcbsd.org

Introduction
When I had originally designed the pc-sysinstall system-installation utility for PC-BSD, one of thecritical features was the ability to make every install a fully-scripted install. This would ensure that wecould always replicate a particular type of installation and keep track of what steps were taken during
the process. This functionality allowed us to easily develop and maintain a graphical front-end to thesystem installation process, by having it simply create a small configuration script of installation
options. Over the years the pc-sysinstall utility has evolved to support more advanced features, such assupport for ZFS, including RAIDZ and dataset control, package installation, FreeBSD dist-file supportand much more.
With this functionality in mind, the pc-sysinstall backend could also be adapted to quickly
automate the deployment of FreeBSD servers and PC-BSD desktops using a network bootenvironment. In PC-BSD & TrueOS™ 9.1 and higher, this functionality has been added in the form of
the “pc-thinclient” utility. This utility walks you through the process of downloading and configuring
the necessary software to 'PXE' boot your systems via the LAN interface, as opposed to using
traditional media, such as DVD or USB. In order for clients to boot via PXE they will need a PXEcapable network adapter, which is often a capability indicated in the specifications of your networkcard. In this paper we will take a look at the initial setup and configuration of your PXE installation
server.

The initial PXE setup
To get started, you will need to have a system with two network interfaces running PC-BSD orTrueOS 9.1 and a complete ports tree in /usr/ports. If you do not have the ports tree installed, you candownload it by running the command “portsnap fetch extract update” as root. With these pieces inplace, open a root prompt and run the “pc-thinclient” command. The first screen you see will looksomething like this:Enter “y” to continue, and the following screen will be shown:

In this case you are going to be setting up a PXE installation server, so enter “i” to continue.
(The “r” option can be used to make your system a X thin-client server. More information about thiscan be found on the wiki page at the end of the article.) After selecting your type of PXE system, thethin-client wizard will then begin to build the “net/isc-dhcp42-server” port. You will most likely only
need the default port options, and can hit enter at any confirmation screens that appear. Once the port
has finished installing, the thin-client setup will prompt you again for the PXE network interface to use:

Enter the interface name of the network card you wish to use as the PXE interface. Thisinterface will be running the DHCP server, and should not be connected to an existing network withanother DHCP server running. The wizard will then finish up the configuration for PXE booting, anddisplay a message similar to this:Your initial PXE setup is now complete! You may now try to PXE boot a client connected on
the network interface you specified. If the client boots successfully, you should be presented with aninstallation screen like below:

By selecting the “install” option you will be presented with the example configuration option,

which can be used to install a basic FreeBSD system. (Below we will look at adding your own) By
selecting it, you will be asked to confirm one last time that you wish to perform the installation using
this configuration, and then the installation will proceed. In addition to performing installs, you canalso access an emergency shell prompt. This can be very useful if you have a system which can nolonger boot, and you wish to access the disk or attempt repairs of some kind.

Customizing the installation scripts
With your initial PXE configuration finished, you will now most likely want to create your own
installation scripts. The thin-client wizard creates an example installation script in the/usr/home/thinclient/installscripts/ directory, which is where you will want to place your custom
scripts as well. Any scripts placed in this directory will be selectable as an installation option on thePXE client.
With the location of the install scripts in hand, lets now take a look at the provided pcsysinstall.example file in that directory.
# Sample configuration file for an installation using pc-sysinstallinstallMode=fresh
installInteractive=no
hostname=examplesystem# Set the disk parameters
disk0=ada0
partition=all
bootManager=none
commitDiskPart# Setup the disk label# All sizes are expressed in MB# Avail FS Types, UFS, UFS+S, UFS+J, ZFS, SWAP
# Size 0 means use the rest of the slice size
disk0-part=UFS+SUJ 1000 /disk0-part=SWAP 2000 none
disk0-part=UFS+SUJ 0 /usr
commitDiskLabel# Set if we are installing via optical, USB, or FTP
installType=FreeBSD
installMedium=local
localPath=/installarchive
packageType=tar
installFile=fbsd-release.txz# Set the root pass
rootPass=root# Setup our users

# Setup our users
userName=kris
userComment=Kris Moore
userPass=krisuserShell=/bin/csh
userHome=/home/kris
userGroups=wheel,operator
commitUser

The included comments in the example make most of the functionality fairly self-explanatory.
However there are a few sections we will take a closer look at customizing. The first place to note is the“installMedium=local” and “localPath=/installarchive” options. The pc-sysinstall backend supports anumber of methods of fetching the archive files for installation. In this case we are using the local file“fbsd-release.txz”, stored in /usr/home/thinclient/installarchive. This directory will appear to PXEclients as /installarchive, allowing you on the host OS to supply your own tar archives of any FreeBSD/ PC-BSD release or configuration you wish.
PRO Tip!
By using the Warden utility in PC-BSD / TrueOS, it is possible to setup your installenvironment inside a jail on the host system. Then when you are satisfied with theconfiguration, you can stop the jail and create the install archive on the host system with the“tar” command as shown below:# tar cvJf /usr/home/thinclient/installarchive/myarchive.txz -C /usr/jails/<jailip> .

After selecting your installation archive options you will most likely want to customize the disklayout of the new system. In the example provided we are performing a very simple full-disk
installation to the disk ada0, using UFS with Soft Updates + Journaling. The resulting installation willcontain a 1000MB root partition, a 2000MB swap, and use the rest of the disk space for /usr as seenbelow.
# Set the disk parameters
disk0=ada0
partition=allbootManager=none
commitDiskPart# Setup the disk label# All sizes are expressed in MB# Avail FS Types, UFS, UFS+S, UFS+J, ZFS, SWAP
# Size 0 means use the rest of the slice size
disk0-part=UFS+SUJ 1000 /disk0-part=SWAP 2000 none
disk0-part=UFS+SUJ 0 /usr
commitDiskLabelIn addition to UFS support, the pc-sysinstall backend can also handle more advanced ZFS disklayouts in a similar manner:# Setup the disk label# All sizes are expressed in MB# Avail FS Types, UFS, UFS+S, UFS+J, ZFS, SWAP
# Size 0 means use the rest of the slice size
disk0-part=ZFS 0 /,/usr,/var,/root (mirror: ada1)
commitDiskLabelIn the example above we have changed our disk layout from UFS to a single ZFS pool using theentire disk, and added the disk drive ada1 to the resulting zpool as a mirror device. While this example
is fairly simplistic much more complex layouts can be created using ZFS, including raidz, dataset
options and more.
PRO Tip!
Since every single install with pc-sysinstall is fully scripted, a good way to experiment withalternative ZFS layouts is using a virtualization tool such as VirtualBox and your PC-BSD
installation DVD. By running the install GUI, you can customize your ZFS disk layout in aneasy-to-use manner inside a virtual machine. Then when the installation is finished, a copy ofthe saved pc-sysinstall configuration file will be saved onto the installed system at /root/pcsysinstall.cfg.
One last feature to look at with the thinclient utility is the ability to perform completely
unattended installations. If you plan on only doing fully-automated installations via this PXE interface,
you may do so simply by creating a configuration script named “unattended.cfg” and placing it in the/usr/home/thinclient/installscripts/ directory alongside the example. When a client first boots it will
check for this unattended.cfg file, and if found it will automatically use it for installation. Somecaution should be taken when using this method, since simply plugging a PXE booting system into thewrong LAN cable could cause it to be re-installed.

Scalability
With the thin-client server now setup, one of the most often asked questions is that ofscalability. How many systems can be installed at a time using this method? The answer of course will
depend greatly upon your hardware setup. At its core the PXE server is just a large file-server, running
DHCP for clients, and using NFS to share files. This is not very CPU intensive and will rather be more
limited by the speeds of your disk drives, and networking systems. In order to scale up to doing larger
volumes of system installations simultaneously, it may be wise to install your PXE server usingmultiple disk drives in a ZFS Mirror or RAIDZ configuration. On a system with RAM to spare it iseven be possible to setup the /usr/home/thinclient/installarchive/ directory as a ramdisk, removing
the physical hard-disk bottleneck all together. This could be done using a command such as:# mount -t tmpfs tmpfs /usr/home/thinclient/installarchive/
Since this is now running in system memory, you will need to take care that files placed here are
not lost after a system reboot. From a configuration stand-point another limiting factor may be theDHCP daemon itself. The default location for its configuration is /usr/local/etc/dhcpd.conf. The initialvalues provided by pc-thinclient will set up DHCP to serve up IP addresses starting at 192.168.2.100,
and ending at 192.168.2.199. If you wish to support booting more clients these values may be adjusted
to your particular needs.

Conclusion
We have briefly looked at some of the ways PC-BSD and TrueOS 9.1 make it easy to setup
PXE booting and perform rapid deployment of FreeBSD based systems. We have also just begun toscratch the surface of the type of installations that can be performed with the pc-sysinstall backend. If
you want to do further research into more complex installations please take a look at the included wikireferences on pcbsd.org. We also will be happy to continue the discussion with you on the PC-BSD
mailing lists or forums.

References
Wiki Articles:
http://wiki.pcbsd.org/index.php/Thin_Client
http://wiki.pcbsd.org/index.php/Creating_an_Automated_Installation_with_pc-sysinstall
Mailing Lists & Forums
http://lists.pcbsd.org
http://forums.pcbsd.org/