It’s often during my freelance gigs that I come across clients using dinosaur age versions of FreeBSD, requiring to spend hours to bring the OS and applications to a minimum usable standard. So today I’d like to show you, my potential future clients *wink*, how to keep your system in top condition.

(By the way, sometimes my clients are not as bad as I paint them and show me really cool stuff I didn’t know about. Like the excellent SSH terminal program Termius, which has just replaced the aging Putty in my heart. It’s even got a green phosphor monitor retro vibe I’m really digging. Give it a try, I swear I’m not getting any referals.)

Back on topic: I take no responsibility for any damage you may cause by using these commands, and I advise you to make a backup of your data if it’s of any relevance, or practice on a virtual machine first. And if you are one of those people who believe chmod 777 is the solution to the universe and everything, I beg you not to get anywhere near a terminal.

That said, don’t worry as unless you have a really old version, it is unlikely that you will break anything that can’t be fixed!

Updating the Operating System

You may ask: what’s the point of having an updated FreeBSD if everything looks and feels the same since decades?

Well, first and most obviously for security. Obsolete versions of the OS do not receive security patches. Second, for performance: contrary to the trend in the Windows world, in FreeBSD the latest software usually tends to be more stable and faster than their older incarnations. And third for convenience, since it is not even possible to comfortably install anything if your O.S. is too old as the package repositories will refuse to work.

Within FreeBSD we can distinguish between major (e.g. 13) and minor (12.3) versions. To see what’s the version number you can use this command:

uname -a

Obediently, FreeBSD will reply with a string of numbers including the version. For example something like:

FreeBSD myserver.com 13.1-RELEASE FreeBSD 13.1-RELEASE releng/13.1-n250128-fc752ac2212 GENERIC amd64

The official FreeBSD web site https://freebsd.org always informs in the front page of which versions are currently supported. This list changes with relative frequency, so always double check what’s in there before proceeding to an upgrade or installation.

Let’s see what freebsd.org says today:

Depending on what our own version is and which ones are listed here, there are 3 possible scenarios:

Updating the current version

Let’s say our server’s at version 12.3. In this case, given that 12.3 is still supported at the time of writing this article, we could simply download the latest patches for our version without upgrading it. This is the simplest process and we should get used to do it regularly, no matter which version is installed.

freebsd-update fetch install

If there’s any update to download, a list of files to be added or update will be displayed. If the list is too long to fit the console window, the program will pause to allow us to see it. To continue, press enter until you see the END prompt, at which point you can quit this list with:

:q

Some trivia: this is the quit sequence for less, an ancient Unix command used to display text files page by page. A similar one, also included in every Unix derivative since the dawn of time, is more. These apps are called pagers.

Upgrading to a new version

Let’s say that we have version 12.1. In this case, and basing our example in the screenshot from freebsd.org we saw before, it would be good enough to upgrade to version 12.3, which is the oldest supported version

Before we start, I recommend to make the task easier setting the ee editor as the default editor for the system, since vi is quite counter intuitive to use.

setenv EDITOR ee

For this change to become permanent, we can do as follows:

echo 'setenv EDITOR ee' >> /root/.cshrc

Now that we are ready for action, let’s see how to solve this scenario. The freebsd-update command now looks like this:

freebsd-update upgrade -r 12.3-RELEASE

This time your system will be checked and there will be arcane questions like:

“Does this seem reasonable? y/n”

In the absence of the information to answer such a question, we can simply type y for yes and hope for the best. Not the most technical of answers but it works.

If any system configuration file is being changed or we have made our own modifications to them, the update process will ask us which one we want to keep, giving us the option to add or remove lines on our own (hence my warning about the text editor). This is called merging, and the programmers among you will be familiar with this process.

The following file could not be merged automatically: /etc/login.conf
Press Enter to edit this file in vi and resolve the conflicts

We will press enter (not like we have a choice beyond aborting the whole update with CTRL+C). To get rid of the old, unwanted lines in the file, find every line starting with:

>>>>>>>>>>>> CURRENT VERSION

and delete every line from there up to the line that looks like this:

=======================

(Deleting an entire line can be accomplished with ctrl + k in the ee editor)

Further below, you will find another marker like this:

>>>>>>> 12.3-RELEASE

This marker signals the changes introduced with the update we are about to install, so we will leave the lines in-between the previous marker and this one intact. However, we need to delete the marker itself, which is only there to help us with the merge. Leaving it in place would cause errors or even causing the system not to boot, as it’s alien to the file.

Once you deleted the three markers and the lines between the first and the second, keep scrolling down the file as there may be more of those.

Once we’re done with the merging and the download of the necessary files is finished, we will be asked to run freebsd-update install. It is also possible that we will be asked to reboot to upgrade the kernel, and once we have rebooted we will probably have to run freebsd-update install again. In any case, I advise you to pay due attention to what it says on the screen during the process, since I cannot predict here which steps upgrading to a particular version will require in the future.

3. We have an unsupported major version

Continuing with the example of the screenshot I took from freebsd.org – remember that this changes and you should check the current situation at the time – let’s imagine now that we have version 11.3. Since no version 11 release is supported, it would be necessary to upgrade to version 12.3 in one go. The procedure is exactly the same as described above with the following exceptions:

• Once the whole process is complete, we will be advised to reinstall the software we have installed through the ports. If you don’t know what it is, or don’t have it, you can just do a pkg update.

• Since this is a major update, it is possible that certain things may stop working, or work differently. Verify your installed software and upgrade it if necessary (see below)

• We may be allowed to install newer versions of certain software than we were previously offered. Likewise, we may not be able to install older versions that were previously available for our OS.

In case we find ourselves at a dead end and want to go back to the previous version, we can do a rollback:

freebsd-update rollback

B: Updating installed software

By installed software I mean MySQL, nginx, php-fpm and any other of the pieces of software available from the FreeBSD repositories:

• The package repository, providing binaries precompiled with the default options.
• The ports collection, which allows us to compile the code on our own and choose what we want and what we don’t. Compiling ports is slower but also more flexible, permitting the use of third party modules such as nginx geoip that are otherwise not available. The ports collection also tends to be slightly more up to date than the package repository.

In the past, it was often necessary to resort to the ports system, as key application features were often not present in the pre-packaged binary. Nowadays, it is not as common to need custom binaries, so I will skip that part.

Managing packages

Update everything we have on the system:

pkg update & pkg upgrade

At this point we will be told what will be removed, reinstalled or installed, according to dependencies.

MariaDB users: always pay attention when installing new packages as some of them will insist on replacing MariaDB with MySQL, even though they work just fine with either.

If you see any such package you can install it through the ports system instead. You can also use pkg lock to prevent automatic updates to a package.

listING installed software

pkg info

SEARCHING FOR SOFTWARE IN THE REPO

pkg search <search string>

InstallING NEW software

pkg install <package>

Note that we should not specify the entire version number when installing. Commands such as pkg info and search will report packages with names such as php80-8.0.20, but the actual name of the port is just php80.

DeletING software

pkg delete <package name>

Before we finish, let’s talk about a particular case – what if we want to upgrade to a newer version of, for example, mysql or php?

The pkg upgrade command will not do this on its own. If we have, say, MySQL 5.6, pkg upgrade will just install whatever patches are available for that version, and that’s it. Just like with the operating system, if we want to upgrade to a newer version, we have to specify it.

If we have MySQL 5.6 and we want for example to install MySQL 8.0 we will have to do something like this:

pkg install mysql80-server

Note that mysqlXX-server package automatically installs mysqlXX-client as well. It is possible that we will be informed of a conflict with our current version, in which case we should first uninstall the previous version:

pkg delete mysql56-server mysql56-client

Other packages, such as python, allow for different versions to be installed in the same machine. We can then symlink python27 to the python 2.7 binary and python to the python 3.9 binary.

Remember that in FreeBSD only the binary (or the exe as its known in Windows world) is uninstalled when we delete a package: our existing data and configuration files will not be removed. Also, unlike Windows software – which needs to be stopped prior to an upgrade – FreeBSD services will happily continue running the previous version of any application we upgrade until we restart the service ourselves or reboot the machine.

Finally and as I said in the system update section, pay attention to the text show in the screen after the update is finished because it informs us of possible problems, where the configuration files are (particularly if this location has changed, which happens quite often between the different MySQL and MariaDB flavors) or what needs to be done after the installation for the software to work properly. This text is usually very short and to the point and very much worth reading, unlike the man pages which go into excruciating detail about every exotic option instead of giving the quick usage example we are hoping for.