FreeBSD is constantly evolving; the team is adding new features and patching security vulnerabilities. Keeping your server operating system up to date ensures better security and compatibility, and FreeBSD includes the tool to make this easy. In this tutorial, you'll upgrade an existing FreeBSD server running FreeBSD 10.2-RELEASE to 10.3.RELEASE-p4.
Warning: As with almost any upgrade between major releases of an operating system, this process carries an inherent risk of failure, data loss, or broken software configuration. Comprehensive backups and extensive testing are strongly advised.
To avoid these problems, when possible, we recommend migrating to a fresh FreeBSD server rather than upgrading in-place. You may still need to review differences in software configuration when upgrading, but the core system will likely have greater stability. You can check out our series on how to migrate to a new Linux server which should mostly apply when migrating to new FreeBSD servers as well.
To follow this tutorial, you will need:
- A server running FreeBSD 10.2.
- A user account configured to run commands with . We will use the default freebsd account which is created automatically when you create a FreeBSD Droplet. To learn more about logging into your FreeBSD Droplet and its basic management, check out the Getting Started with FreeBSD tutorial series.
Step 1 — Fetching and Applying Patches
In order to upgrade the operating system, we first need to fetch the packages and patches for our destination release. Log into the server with the freebsd account.
Then, use the command to gather information about the system upgrade and determine what needs to change. Run the following command:
We use the switch to specify the version we want to upgrade to, which is . After a short time you'll see the following output:
This gives you a chance to review any potential problems. Type and press to continue.
Note: Please remember that this tutorial uses a fresh FreeBSD 10.2 server to guide you through all the steps for upgrading the FreeBSD base system to version 10.3-RELEASE-p4. If you have modified or customized some of the components, create a backup before you continue, and accept all procedures described in this tutorial at your own risk.
Once you agree to continue, the process applies updates and patches. You'll see the following output:
However, the process can't patch everything automatically. We'll need to intervene manually.
Step 2 — Resolving Conflicts
After applying patches to the operating system, will show you two warning messages, and you will need to manually resolve some minor conflicts in two different configuration files. One is and the other one is .
The first warning you see is as follows:
When you press , the file opens in the text editor and you'll see the following text:
/etc/rc.subr file with conflicts to solve manually
Modify this section by removing the lines related to the current version, which are highlighted in red above. Even though we are currently running FreeBSD 10.2, this file references 10.1 as “current.” Remove those lines so the section looks like the following example:
/etc/rc.subr ready to proceed
Warning: DigitalOcean keeps its custom configuration and data for FreeBSD Droplets under the directory, and it's referenced in the file. Please do not change or remove the files or configuration related to DigitalOcean. The custom configurations and data under is what keeps your Droplet up, running in a good shape, and integrated with DigitalOcean's API.
Save your changes to the file and exit the editor.
As soon as you close the text editor, you will see a line reporting the successful merge of the file you just changed. Then you'll see the second warning which says that the configuration file needs your attention:
Just like before, when you press you will be presented with a text file you'll have to modify. The piece you'll need to change will be similar to the first file you edited.
/etc/ssh/sshd_config file with conflicts to solve manually
Once again, modify this section by removing the lines related to the current version until the section of the file looks like this:
/etc/ssh/sshd_config ready to proceed
Save your changes to the file and close the editor.
Once the editor closes, the process will display each file you changed and ask if the changes look reasonable. Answer to both questions to continue the installation.
Once you agree to the changes, you will see a list of binaries and configuration files that will be updated. This list is very long; press to scroll down the list one page at a time. Or, if you don't want to review the list, type to quit. Don't worry; pressing won't abort the upgrade process.
The list looks like this:
Once you've reviewed the list, you'll be back at your terminal prompt. You're ready to perform the installation.
Step 3 — Installing FreeBSD 10.3
The updates have been downloaded and essential files have been successfully merged or configured, so to install the downloaded upgrades, use the following command:
Here is the output you will see:
The installation prompts you to perform a reboot, so execute this command to reboot your machine:
You'll be disconnected from your SSH session, and the reboot will take about a minute. Once your machine has come back online, log back in and move on to the next step.
Note: You must reboot your server in order to load the new 10.3-RELEASE-p4 kernel and its patched binary files, which are loaded only during the boot process. Do not move on to the next steps without rebooting.
Step 4 — Completing the Installation Process
Let's check the version of our server to make sure the upgrade process worked and the new kernel is loaded. First, log back into your server:
Once logged in, run the following command:
and you'll see the following output indicating that the upgrade worked:
But we're not quite done with the upgrade. We need to install any final updates that may have occurred since the release was created, so run once more.
You'll see the following output:
It's safe to disregard the two warnings at the end. Both files will be created or updated by this process.
When you upgrade FreeBSD, you should also upgrade all of your third-party installed packages, especially if you are doing a major release upgrade. To do that, run the following command:
The output will look like this:
Type and press to continue, and you'll see the following output:
Once again, type , followed by to continue.
The packages will upgrade, but to make sure your user has access to the latest versions, run the command:
With that, the upgrade process is complete. But what if something went wrong?
Step 5 — Rolling Back a Failed Installation (Optional)
This entire upgrade process should go smoothly, but if something goes wrong for you during the upgrade you can roll back recently installed packages with the following command:
This will initiate the rollback process, getting you back to where you were. You could also restore the most recent backup you made before you began the process.
Upgrading an operating system to a newer release and applying security patches in a timely manner are important aspects of ongoing system administration. The command makes both of those tasks easy to do. Once you become familiar with the process, you'll be able to perform future upgrades on your own.
To learn even more about how to upgrade FreeBSD, you can read An Introduction To Basic FreeBSD Maintenance, or review the corresponding chapter at the FreeBSD Handbook.
When administering FreeBSD servers, it is important to understand the basic maintenance procedures that will help you keep your systems in good shape.
In this guide, we will be covering the basic processes needed to keep your server up-to-date and functioning properly. We will be covering how to update the base operating system that the FreeBSD team maintains. We will also discuss how to update and maintain optional software installed through the ports or packages systems.
If you need help getting started with FreeBSD, follow our guide here.
Updating the Base FreeBSD Operating System
One important thing to realize when working with FreeBSD is that the base operating system is built and managed separate from the other software on the system. This provides a number of benefits and allows the FreeBSD team to carefully test and develop the core functionality of the system.
Note: Read the note at the bottom of this section regarding a bug in the current update procedure before proceeding.
When you start using your server, there is a good chance that security updates have been published to the base system. To query the FreeBSD project's servers for these updates, download any new files, and install them on your system, type the following command:
If you are working off of a DigitalOcean FreeBSD installation, is included by default. If you are using another platform, you may need to install through the ports system or packages, or to root.
The command is the management utility for software in the base operating system. The subcommand downloads any new updates, while the subcommand applies them to the live system.
If there are updates, you will see a list of software impacted by the update. You can scroll through with the down arrow or page through with the space bar. Once you reach the bottom of the list, the updates will be applied.
Any long-running software that was updated will need to be restarted to use the new version. If you see any updates to the kernel, a reboot will be needed to prevent strange behavior. You can do this by typing:
IMPORTANT: Bug in Update Procedure
Currently, there is an upstream bug with the FreeBSD update procedure being worked on here. The bug results in a hang on system reboot following the update procedure.
There are two ways of dealing with this situation, the second being preferred in most cases.
The first is to simply force a power cycle to the server using the DigitalOcean control panel. This will result in a forceful and ungraceful restart of the server, but when you boot back up, it will be using the updated environment.
A safer alternative is to disable soft-updates or the journaling of soft-updates on the filesystem prior to updating. Soft-updates are at the core of the issue, so this will prevent the reboot hang. This is a bit more of an extensive procedure and will add some time to any recovery that your disks require in the future (until you re-enable these features).
To do this, before you apply any updates, boot into single user mode. You can do this by typing:
Next, go into the DigitalOcean control panel for your Droplet and click on the "Console Access" button to get to the web console. Press "Enter" when the boot finishes to get a rescue shell session. From here, you can either turn off soft-updates or soft-update journaling.
To disable soft-updates completely, type:
If you wish to just disable the soft-update journaling, a less drastic compromise, you can use this command instead:
Once this is complete, you can initiate a reboot to restart the server in full multi-user mode once again:
After the boot is finished, you can fetch and apply FreeBSD updates using the procedure described above without the reboot hang.
We recommend that you keep an eye on the bug report so that you can revert these changes when the upstream fix is available.
Automating Update Checking
It is possible to configure your system to automatically check for these security patches daily by setting up a job. The utility has a special subcommand that is available specifically for this purpose.
This will pause for a random amount of time (up to an hour) in order to spread out the load on the download servers. It will then check for updates and download them (basically the operation in the background). If updates are downloaded, a specified user account will be notified. Updates are not automatically installed so that the administrator can decide on an appropriate time.
To set up this automatic checking, edit the file with privileges:
At the bottom of the file, add a line that looks like this:
The above command will run the update command automatically as the root user. If updates are found, the user account specified after the component will be notified. In the above example, the default user will be notified.
Save and close the file when you are finished.
The next time you log into the account, you can check your mail by typing:
If updates were downloaded, you will see something like this:
You can view the list of updates by typing the message number associated with the notification:
When you are satisfied with the software that will be changed, you can quickly install the updates by typing:
Remember to restart the machine if any kernel patches were applied and to restart any services that were affected by the update.
Syncing the Operating System Sources
One task you probably want to do from time-to-time is to sync a copy of the FreeBSD source code to your system. This is useful for a variety of reasons. Some ports require the current source to build correctly and the source can also be used to start tracking to a new software branch.
The FreeBSD source code is maintained in an SVN repository. If you just need the most up-to-date version of the source, without the large overhead that subversion entails, you can use a utility called to sync the current sources. This is much faster than using subversion itself.
You can install the package by typing:
If you prefer using the port, you can get that by typing:
Once you have the utility, we should adjust the configuration file slightly. Open it with privileges in your text editor:
First, we need to select a mirror from the list. There are multiple lines in the configuration file, all of which are commented out. Select one that you think may be close to you and uncomment it:
Next, you should make sure that the sections of the file that describe each SVN branch are referencing the release version you are using. You can find this out your release version by typing this from the command line:
This tells us the branch of the operating system as well as the system patch level at the end. The portion we want to pay attention to for our current purposes is the number before the first dash. In this case, it specifies . The means that we are currently tracking the release branch, the most stable branch available for FreeBSD.
Back in the file, make sure that the definition for the parameter under is pointing to this number:
This will ensure that you are downloading the correct source. Save and close the file when you are finished.
Now, since we are tracking the release branch, we can type:
This will download the most recent version of the source tree to . You can update it at any time by re-running this command.
If you need the ability run subversion commands on the source, you will have to download the subversion tool. You can install the package by typing:
If you prefer to use ports, you can acquire the tool by typing:
Using the command will take significantly more time. It will not only download the current version of each file in the tree, but the entire history of the project.
If you have previously synced source using the tool, you will need to remove the source tree before checking out the source using :
Detailed instructions on how to use is outside of the scope of this guide. However, the general idea is to issue a command against one of the branches on one of the FreeBSD source mirrors.
For instance, to checkout the same exact source that we did using the command above, we could type something like this:
Note that the URL for this command is basically just a combination of the and definitions that we saw in the configuration file.
Updating the System's Record of Optional Software
FreeBSD provides two different formats to install additional software on your server. The first is a source-based system called "ports" and the second is a repository of pre-compiled packages based on the available ports. For software that resides outside of the base operating system, a number of additional tools are used for management.
The system keeps information about the ports that can be installed within a directory hierarchy rooted at . This directory structure is called the "ports tree". Before we touch any ports, we should make sure our ports tree has up-to-date information about our available software. We can use the command to do this.
The syntax of the command mirrors that of the command in some ways. On DigitalOcean, the source tree will be pre-populated with initial information about the available ports, which you can update as demonstrated in the second command.
If you are not using DigitalOcean, your directory will likely be empty when you are starting out. If this is the case, the first time you use , you should use :
This will fetch a complete ports tree and extract it into . This can take awhile and is only necessary if you don't have any information in .
To update our system's information about available ports (every subsequent run), type:
This process can take a bit of time depending on how recently you last updated the ports tree. It must download a fair number of files for every piece of available software that has been modified since its last run. This will populate the hierarchy with information about ports.
The packaging system can leverage some of this information too. However, it also maintains its own database to keep track of the pre-built binary packages available for installation. To update this, you can type:
This will fetch the most recent package database information from the FreeBSD project's servers. It's worth noting that for many operations, a is performed automatically as part of the command execution, so it is not always needed as a stand-alone command.
Update the Optional Software
So far, we have learned how to update and apply updates to the base operating system. We have also learned how to update our operating system source code and how to refresh our local information about available ports and packages.
Now, we can use this updated software information to download and apply updates to our optional software. The process will be different depending on whether you are using ports or packages. If you are using a mixture of these two, you may need to juggle some processes.
Finding Out Which Software can be Updated
The first step in updating your software is to find out which applications have new versions available. We can do this in a few different ways.
Checking for Updates with the pkg Command
If you would like to compare software that you have installed on your system against updated information about the newest versions available, you can use the subcommand of . This shows you the installed version and can optionally display information about available versions.
It is worth noting that this command will show optional software installed through both ports and packages. This command does not distinguish between the installation sources, so it is able to accurately show all updates available on your system.
We can see if our software is up-to-date by typing:
If there are references to a new version of any software in the latest index file (downloaded through the command earlier), the output will display the discrepancies. For example:
Since we are checking the software installed on our system against the latest index file in our ports tree, sometimes you will be checking this at a point when there are updates in the ports tree that have not made their way to the package yet. This happens because the packages are built from the ports tree and often have to lag behind slightly.
Because of this possibility, the above command may show updates that are not actually available as packages yet. To spot these instances, you can compare the output of the above command to the output of this command:
This command checks for new versions in the system's database of available packages (instead of the index file in the ports tree). If the two commands produce the same output, then you will be able to update any packages using the system.
If there are updates in the first command that do not show up in the second command, this means that the changes haven't been packaged yet. If you are using packages for the software that needs to be updated, you can either wait until the package catches up, or you can switch to the port to get the latest update now.
Checking for Updates with Portmaster
If you more often choose to build software from source using the ports system, an attractive alternative is the command. This tool is useful for any ports-based software management tasks on FreeBSD, from checking for and applying updates, to installing or removing ports and all of their dependencies.
To get the command, you can either install the package or compile it from the ports system.
To install the package, type:
If you'd rather compile the tool from source, switch to the package's directory in the ports tree and install it using make:
Upon installation, you may see a message about adding some information to your file and converting your package database. This is not necessary if you are starting from FreeBSD 10.1 or later.
Once you have installed, you can check for updates by typing:
This will examine all of the software installed on your system and compare it against the index file to see if new versions are available. This operates in the same way as the command in that it will show updates regardless of whether the software was installed using ports or a package. It categorizes the software based on how it is connected to other software in terms of dependencies.
Any software that has updates available will have an indented line like this:
At the bottom, a summary line will describe the number of applications that can be updated:
Since works primarily with ports, all of the detected updates should be available for application.
Checking for Software Vulnerabilities
FreeBSD maintains a vulnerability database that should be checked regularly to ensure that there are no vulnerabilities in the software you have installed on your system.
While it is sometimes beneficial to update all of the software on your system, at the very least, any software with known vulnerabilities should be updated at the earliest possible time. To check for known vulnerabilities with any of the optional software you have installed on your system, type:
This will download the latest vulnerability database from the FreeBSD servers and check it against the installed software on your system. If any vulnerabilities exist with your installed software, it will alert you.
Checking the UPDATING Notes
Before you update any software, it is essential to check for any breakages that the updates may cause. The FreeBSD port maintainers must sometimes make changes that cannot be applied cleanly without user intervention. If you fail to check for these situations, you may end up with non-working software and potentially a broken system.
In the directory, a file called contains information about any software updates that may have unexpected results. To read this file, type:
This simple text file will contain information about any updates that require additional attention, regardless of whether the software is installed or not. Each entry will be marked with the date when the referenced update was committed to the ports tree. Another thing to note is that the file contains update information going all the way back to 2008. The file will look something like this:
You should check this file for any update issues that have been added since the last time that you updated. Since this file contains a large amount of information that will not be relevant to the update you are considering, either because it concerns software not installed on your system, or because it details an issue from a previous update, you usually only have to check the entries closer to the top of the file.
If there are any extra steps you need to take before the upgrade, complete them now.
Updating Packages and Ports
After taking any actions recommended in the file, you should now be ready to update your software. The methods that we use will depend on whether you want to use pre-compiled packages or source-based ports for your software.
If you are mainly using packages and wish to use this format for your upgrades, you can use the command:
This should offer to upgrade all of the packages for which there are updates available.
One thing to note about this method is that, if you are mixing packages and ports, a package update may attempt to reinstall software that you built using the ports system. This can happen when you compiled the application with different options, selected customizations that required different dependencies, etc. from the packaged version.
This scenario will look like this:
In this case, the command was installed through the ports system, but is trying to bring it into line with the version it knows about. If you wish to keep your customized ports version, you can press "N" to this operation and then lock the package by typing:
This will prevent the software from being upgraded, allowing you to upgrade the rest of the software using the command. When you wish to upgrade the locked software, you can unlock it temporarily by typing:
If you are mainly using and ports to handle your packages, you can upgrade all of your optional installed software by typing:
You will be asked to select options for the ports you are upgrading. If you do not know what any of the options mean, or if you don't have any specific reason for making a selection, it is okay to use the defaults.
If you use before you upgrade your packages, because of the lag between port and package updates, there is a chance that some software that was previously installed using a package will now be updated using ports. If this is not a problem for you, feel free to use this method. If you would rather stick with packages for your software, it is probably best to wait until the update is repackaged.
If you wish to granularly update your packages, you can also upgrade a specific package by specifying its category and name as found in the port tree:
For instance, to upgrade the port, you could issue this command:
As you can see, there are quite a few different processes that need to take place in order to maintain your FreeBSD servers.
Some of these, like the process of updating the base system's source, do not need to be run frequently, while other tasks, like updating the base operating system and updating any software with known vulnerabilities, should be completed often. Maintaining your system may seem complicated at first, but will become fairly straight forward as you get familiar with the tools you are using.
To find out more information about how to work with packages, follow this link. To get a better idea of how to work with ports, follow this guide.