This is an installation and configuration guide for FreeBSD. I now use FreeBSD for my server which acts both as a NAS for all of my data and as a media server for my TV. I have managed to add some pretty neat features such as a Time Capsule for my MacBook and a PVR for BBC iPlayer. This guide describes the FreeBSD installation, ZFS configuration and user-land software installation and configuration. I include all of my configuration files so that you can see how I have set it all up.
- Installation Notes
- General Setup
- Adding Users
- Installing Software
- Configuring Cron
- Time Machine
- Web Server
- Media Servers
- SMART Daemon
- Usage Notes
- Word Of Warning
§1 Installation Notes
I used a bootable USB image to install FreeBSD, you can grab one from the FreeBSD download page. During the first section of the installer I disabled "games" and "ports". The automatic partitioner decided to go with:
Further on in the process I decided to disable IPv6 and "dumpdev". Once the process finished I decided to not immediately reboot into the new system, instead I opened a shell and typed
gpart set -a active ada0 to set the drive as active before the first boot (which was needed to side-step a nasty bug which meant that you couldn’t boot into your nice new system).
§2 Configuration Notes
Now you should have a working fresh installation of FreeBSD. The majority of this tutorial covers the configuration of this fresh clean system. Firstly I talk about how I configured FreeBSD itself, then I add users, then I install user-land software, and finally I configure that user-land software.
§2.1 General Setup
Firstly, I tweaked the start-up configuration file, "/boot/loader.conf", so that some additional kernel modules would be loaded during start-up. These modules allow the CPU temperature to be obtained (for my Intel CPUs), enable ACPI (for my ASUS motherboard) and finally enable disk encryption to be used (if the user wants). I did this with the following commands (as root) - the changes do not take effect until the system is rebooted, hence the final command.
Next, I added some lines to the other start-up configuration file so that some additional software would be loaded during start-up. The "/etc/rc.conf" file is very important in FreeBSD as it contains most of the custom configuration for my system. The commands (as root) I used are below - likewise, the changes do not take effect until the system is rebooted, however, I do not reboot immediately as some further tweaking can be performed during this boot.
The first command enables ZFS to be used (if the user wants); the second sets the default encryption settings for GELI; the third enables the inet daemon (which is often called the "super server"); the fourth clears "/tmp" during boot; the fifth enables the daemon to automatically mount removeable storage (such as USB drives); and the final command enables memory disks (a.k.a. RAM disks).
Next I configured the system to automatically mount removeable storage (such as USB drives). The instructions for this can be found in the section on USB disks in the FreeBSD handbook. Run
vi /etc/auto_master and un-comment
/media -media -nosuid. My only comment is that you don’t have to add all the lines to "/etc/devd.conf" as they are already there, just move the
*/ line further up the file and then they will not be commented out anymore. Run
vi /etc/devd.conf and un-comment:
Before rebooting I edited "/etc/fstab" to create a RAM disk (to hold temporary copies of sensitive un-encrypted data) and to encrypt the swap partition. This final step ensures that any sensitive data that is written to swap (because the RAM is full) is unrecoverable if the machine is powered off (just like the data in RAM). Of course, the swap has no knowledge of which data it stores is sensitive and which isn't: this method encrypts the whole partition. The downside to this is that your machine cannot be hibernated (which requires reading the swap during wake-up) or debugged completely (as memory dumps are sometimes written to swap). I believe that these two hindrances are acceptable.
Next I cleaned the beginning of all of my data disks that were going to be my ZFS array. WARNING: This will make any existing data on the drive inaccessible. I then created the pool and created some useful partitions on the pool. You’ll notice that I enabled LZ4 compression and set the flags for snapshots on all partitions except "timecapsule" (which has its own snapshots in Mac OS X). The "autoexpand=on" line is needed if in future I decide to replace the disks (one-by-one) with larger ones.
Next I mounted the partitions so that they could be used straight away (whilst keeping copies of any data in the two targets that already existed).
I like using BASH as my shell, which is not included in the default install of FreeBSD. I installed BASH using the port system, which means that I had to set up the port system first. The following command (as root) will download the port tree and extract it to the local directory:
portsnap fetch extract.
Once that is done I created the "/etc/make.conf" file so that all ports were installed using the settings I wished. Use the Vi editor (by typing the command
vi) to create the file and make it look like mine below.
Finally, I installed BASH by typing
make -C /usr/ports/shells/bash config-recursive first to configure it (deselect "implicitcd" when the first configuration screen appears) and then
make -C /usr/ports/shells/bash install to actually install it. BASH will not work straight away as it needs two specific file-systems to exist. You can make them with appear at boot with the following two commands.
BASH should now be there ready for you to use - after you do a reboot.
§2.2 Adding Users
I created all of the infrastructure for users to use the ZFS file-system, have a data store and a Time Capsule. This resulted in quite a few ZFS commands, but hopefully they will all make sense (and most are duplicates).
Note that there is no need to put quotas on the Time Capsules as they are handled in the configuration file later on and work quite well. Users are added using the aptly named
adduser command. Once that is done I modified their groups and the permissions of their directories.
§2.3 Installing Software
The first thing that I did at this stage is to download the source code for FreeBSD. If you are just going to use this machine as a server or some such then you don’t need to do this. However, if you intend on using it as a build platform for other FreeBSD machines (such as ARM boards) then you’ll need the source code. You can grab it with the command
svnlite co https://svn0.us-west.freebsd.org/base/head /usr/src/.
Next, I installed Portmaster as it is a handy tool for installing software from the ports tree. To install it you’ll need to run the command
make -C /usr/ports/ports-mgmt/portmaster install.
Now I start installing other software that I need, using Portmaster instead of Make. Below you’ll find a list of all of the software that I have installed. I do each one in turn using the command
portmaster -y foo/bar (i.e.,
portmaster -y editors/vim). Next to some of them is a description of what configuration settings I changed from default, some of them are configuration options for [grand-]daughters.
- editors/vim ["tcl86": add "tzdata"]
- lang/python27 [add "sem"]
- mail/ssmtp [add "logfile"]
- security/gnupg [add "pinentry"; "pinentry": remove "gtk", remove "gtk2", remove "qt4"]
- www/lynx [add "default_colors"]
- audio/normalize [add "flac", add "ogg"; "curl": add "rtmp"]
- databases/sqlite3 [add "dbstat"]
- graphics/ImageMagick [add "hdri"; "lcms": add "jpegicc", add "tifficc"]
- graphics/ufraw [remove "gtk2"] (when I did this I had to type the following hack
mkdir -p /usr/local/share/icu/52.1 && cp /usr/ports/graphics/ufraw/work/ufraw-0.19.2/mkinstalldirs /usr/local/share/icu/52.1/mkinstalldirsto get it to compile, hopefully this has been fixed by the time you are following these instructions)
- math/gnuplot [add "pdf", remove "wx"; "libgd": add "iconv"]
- multimedia/ffmpeg [add "ass", add "faac", add "fdk_aac", add "lame", remove "ffserver", add "libbluray"; "x264": add "gcc", add "pgo"; "gmp": add "cpu_opts"]
- multimedia/mplayer [add "bluray", remove "gui", remove "skins"]
- net/get_iplayer ["p5-libwww": add "https"; "p5-IO-Socket-SSL": add "idn"]
- net/mediatomb [remove "external_transcoding", remove "js", remove "mysql"]
- net/netatalk [add "zeroconf"]
- net/samba44 [add "avahi", remove "cups"]
- www/youtube_dl [add "ffmpeg"]
That will take a long time to run/wait for. Once it is all done I like to create a link to Python using this command
cd /usr/local/bin && ln -s python2.7 python. I then append some lines to the end of "/etc/rc.conf" so that some of the recently installed software starts automatically. You can do this with the following commands.
At this point it is probably worth doing a reboot just to check that everything is working OK for you. A lot of the daemons that have just been installed will probably not run because we have not configured them yet, but the fact that they print an error message means that they are at least trying to start up - which is good.
§2.4 Configuring Cron
Here is a copy of my Cron file, I think that it is fairly self-explanatory. All it does is correct permissions of user’s private/shared folders, check for updates in both FreeBSD and the ports system; and finally it performs some maintenance of the ZFS pool.
§2.5 Configuring Software
I have highlighted a few keys pieces of software (such as media servers and the like) to describe how I configured them for my needs.
§2.5.1 Time Machine
The settings for the Time Capsules are kept in "/usr/local/etc/AppleVolumes.default". Use your favourite editor (I use Vim) to change the file so that the un-commented lines look like the ones below. Now Mac computers should be able to see, and use, your FreeBSD machine as a Time Capsule.
§2.5.2 Web Server
Above I installed Nginx so that I could have a very light weight webserver on my local network. The settings for Nginx are in "/usr/local/etc/nginx/nginx.conf". Use your favourite editor (I use Vim) to change the file so that it looks like the one below.
§2.5.3 Media Servers
I have installed two separate media servers to serve my music and videos over different protocols: Firefly (a.k.a. mt-daapd) serves content over DAAP for Apple devices; and Mediatomb serves content over UPnP/DNLA for Android, Linux and Windows devices. The two configuration files for these pieces of software are "/usr/local/etc/firefly/mt-daapd.conf" and "/usr/local/etc/mediatomb/config.xml" respectively. Below I have included both configuration files - Firefly first and Mediatomb second.
For advice on mt-daapd then check out this excellent article. I feel like the Mediatomb one can still be trimmed out some more. It is derived from the one that is included in the package but I do feel that a lot of the MIME-type related lines are superfluous.
I found Chapter 9 of the Samba documentation particularly useful for this part. The settings for Samba are kept in "/usr/local/etc/smb4.conf". Use your favourite editor (I use Vim) to change the file so that the un-commented lines look like the ones below.
Now you need to go ahead and actually create the Samba users (and their passwords), which are in addition to the FreeBSD users. To create the guest account run
adduser like below.
Now it is time to add the Samba users: this is done by using
smbpasswd like below.
The settings for the SSH server are kept in "/etc/ssh/sshd_config". Use your favourite editor (I use Vim) to change the file so that the un-commented lines look like the ones below.
All the options are pretty self-explanatory I think but I would like to draw your attention to the line
ForceCommand internal-sftp -l VERBOSE -u 077 under the section
Match group sftp_only. These two lines mean that users who are members of the group "sftp_only" ("user3" and "user4" in this tutorial) cannot run commands over SSH on my server but do have the ability to use it’s storage over an SFTP connection. If one of those users tries to connect using
ssh user3@HOST then it will always fail but they can still transfer files using an encrypted SFTP connection. In essence, my server is simply a data store for them and it will refuse all attempts to log in, run commands, forward ports or open GUIs.
§2.5.6 SMART Daemon
The settings for the SMART daemon are kept in "/usr/local/etc/smartd.conf". Use your favourite editor (I use Vim) to change the file so that the un-commented lines look like the ones below. This will start a short self-test on all disks between 2AM and 3AM on Tuesday morning and any changes in their health will be emailed to you.
For some reason the default installation of Python from the ports system does not load up the machine’s SSL certificates correctly. This means that Python scripts which connect to servers securely, such as
youtube-dl, fail with "CERTIFICATE_VERIFY_FAILED" errors. After a fair amount of searching I found other people had similar issues. I was able to implement a workaround by typing the following command as root
ln -s /usr/local/etc/ssl/cert.pem /etc/ssl/cert.pem.
§4 Usage Notes
To find a port in the port tree run
To perform an audit of all known security holes in the installed software run
pkg audit. Before you update the software using
portmaster foo/bar you should check
UPDATING to see if there are any issues for updating any specific package.
To update the base of FreeBSD run
freebsd-update fetch install.
To restart servers run one of the following commands:
service mediatomb restart
service mt-daapd restart
service netatalk restart
service samba restart
To update the time after a long down period run (during which the clock may have drifted)
ntpdate -v -b uk.pool.ntp.org.
To upgrade all installed ports in the correct order run
To list all ports that have upgrades available run
portmaster -L | grep "New version available" | sort.
To upgrade from 10.0-RELEASE to 10.1-RELEASE (according to the Installation Notes) run the following commands (I have added the
-m DISABLE_VULNERABILITIES=yes because sometimes updating FreeBSD to a secure version is more important than ensuring all installed packages are themselves secure):
If you have changed the
umask of the root account then some permissions will be more restrictive than intended. To correct port’s documentation installation (which assumes default
umask) run the following commands:
If you have changed the
umask of the root account then some permissions will be more restrictive than intended. To correct a PIP installation (which assumes default
umask) run the following commands:
To update all PHP 5.6 packages, for example, run
portmaster $(portmaster -l | egrep -o php56.+ | sed "s/-5.6.*//g;s/-1.0//g").
For advice on which folders to copy on Windows to backup Origin downloads then check out this informative article (remembering to connect to the SMB share as "WORKGROUP\user4" from Windows).