FreeBSD Handbook
Prev | Chapter 25 Updating and Upgrading FreeBSD | Next

# 25.2 FreeBSD Update

Written by Tom Rhodes. Based on notes provided by Colin Percival.

Applying security patches is an important part of maintaining computer software, especially the operating system. For the longest time on FreeBSD this process was not an easy one. Patches had to be applied to the source code, the code rebuilt into binaries, and then the binaries had to be re-installed.

This is no longer the case as FreeBSD now includes a utility simply called `freebsd-update`. This utility provides two separate functions. First, it allows for binary security and errata updates to be applied to the FreeBSD base system without the build and install requirements. Second, the utility supports minor and major release upgrades.

> Note: Binary updates are available for all architectures and releases currently supported by the security team. Before updating to a new release, the current release announcements should be reviewed as they may contain important information pertinent to the desired release. These announcements may be viewed at the following link: http://www.FreeBSD.org/releases/.

If a `crontab` utilizing the features of `freebsd-update` exists, it must be disabled before the following operation is started.

## 25.2.1 The Configuration File

Some users may wish to tweak the default configuration file in `/etc/freebsd-update.conf`, allowing better control of the process. The options are very well documented, but the following few may require a bit more explanation:

    # Components of the base system which should be kept updated.
    Components src world kernel

This parameter controls what parts of FreeBSD will be kept up to date. The default is to update the source code, the entire base system, and the kernel. Components are the same as those available during the install, for instance, adding `world/games` here would allow game patches to be applied. Using `src/bin` would allow the source code in `src/bin` to be updated.

The best option is to leave this at the default as changing it to include specific items will require the user to list every item they prefer to be updated. This could have disastrous consequences as source code and binaries may become out of sync.

    # Paths which start with anything matching an entry in an IgnorePaths
    # statement will be ignored.
    IgnorePaths

Add paths, such as `/bin` or `/sbin` to leave these specific directories untouched during the update process. This option may be used to prevent `freebsd-update` from overwriting local modifications.

    # Paths which start with anything matching an entry in an UpdateIfUnmodified
    # statement will only be updated if the contents of the file have not been
    # modified by the user (unless changes are merged; see below).
    UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile

Update configuration files in the specified directories only if they have not been modified. Any changes made by the user will invalidate the automatic updating of these files. There is another option, `KeepModifiedMetadata`, which will instruct `freebsd-update` to save the changes during the merge.

    # When upgrading to a new FreeBSD release, files which match MergeChanges
    # will have any local changes merged into the version from the new release.
    MergeChanges /etc/ /var/named/etc/

List of directories with configuration files that `freebsd-update` should attempt merges in. The file merge process is a series of diff(1) patches similar to mergemaster(8) with fewer options, the merges are either accepted, open an editor, or `freebsd-update` will abort. When in doubt, backup `/etc` and just accept the merges. See Section 25.7.11.1 for more information about the `mergemaster` command.

    # Directory in which to store downloaded updates and temporary
    # files used by FreeBSD Update.
    # WorkDir /var/db/freebsd-update

This directory is where all patches and temporary files will be placed. In cases where the user is doing a version upgrade, this location should have a least a gigabyte of disk space available.

    # When upgrading between releases, should the list of Components be
    # read strictly (StrictComponents yes) or merely as a list of components
    # which *might* be installed of which FreeBSD Update should figure out
    # which actually are installed and upgrade those (StrictComponents no)?
    # StrictComponents no

When set to `yes`, `freebsd-update` will assume that the `Components` list is complete and will not attempt to make changes outside of the list. Effectively, `freebsd-update` will attempt to update every file which belongs to the `Components` list.

## 25.2.2 Security Patches

Security patches are stored on a remote machine and may be downloaded and installed using the following command:

    # freebsd-update fetch
    # freebsd-update install

If any kernel patches have been applied the system will need a reboot. If all went well the system should be patched and `freebsd-update` may be run as a nightly cron(8) job. An entry in `/etc/crontab` would be sufficient to accomplish this task:

    @daily                                  root    freebsd-update cron

This entry states that once every day, the `freebsd-update` utility will be run. In this way, using the `cron` argument, `freebsd-update` will only check if updates exist. If patches exist, they will automatically be downloaded to the local disk but not applied. The `root` user will be sent an email so they may install them manually.

If anything went wrong, `freebsd-update` has the ability to roll back the last set of changes with the following command:

    # freebsd-update rollback

Once complete, the system should be restarted if the kernel or any kernel modules were modified. This will allow FreeBSD to load the new binaries into memory.

The `freebsd-update` utility can automatically update the `GENERIC` kernel only. If a custom kernel is in use, it will have to be rebuilt and reinstalled after `freebsd-update` finishes installing the rest of the updates. However, `freebsd-update` will detect and update the `GENERIC` kernel in `/boot/GENERIC` (if it exists), even if it is not the current (running) kernel of the system.

> Note: It is a good idea to always keep a copy of the `GENERIC` kernel in `/boot/GENERIC`. It will be helpful in diagnosing a variety of problems, and in performing version upgrades using `freebsd-update` as described in Section 25.2.3.

Unless the default configuration in `/etc/freebsd-update.conf` has been changed, `freebsd-update` will install the updated kernel sources along with the rest of the updates. Rebuilding and reinstalling your new custom kernel can then be performed in the usual way.

> Note: The updates distributed via `freebsd-update`, do not always involve the kernel. It will not be necessary to rebuild your custom kernel if the kernel sources have not been modified by the execution of `freebsd-update install`. However, `freebsd-update` will always update the `/usr/src/sys/conf/newvers.sh` file. The current patch level (as indicated by the `-p` number reported by `uname -r`) is obtained from this file. Rebuilding your custom kernel, even if nothing else changed, will allow uname(1) to accurately report the current patch level of the system. This is particularly helpful when maintaining multiple systems, as it allows for a quick assessment of the updates installed in each one.

## 25.2.3 Major and Minor Upgrades

This process will remove old object files and libraries which will break most third party applications. It is recommended that all installed ports either be removed and re-installed or upgraded later using the `ports-mgmt/portupgrade` utility. Most users will want to run a test build using the following command:

    # portupgrade -af

This will ensure everything will be re-installed correctly. Note that setting the `BATCH` environment variable to `yes` will answer `yes` to any prompts during this process, removing the need for manual intervention during the build process.

If a custom kernel is in use, the upgrade process is slightly more involved. A copy of the `GENERIC` kernel is needed, and it should be placed in `/boot/GENERIC`. If the `GENERIC` kernel is not already present in the system, it may be obtained using one of the following methods:

- If a custom kernel has only been built once, the kernel in `/boot/kernel.old` is actually the `GENERIC` one. Simply rename this directory to `/boot/GENERIC`.

- Assuming physical access to the machine is possible, a copy of the `GENERIC` kernel can be installed from the CD-ROM media. Insert your installation disc and use the following commands:

      # mount /cdrom
      # cd /cdrom/X.Y-RELEASE/kernels
      # ./install.sh GENERIC

  Replace ``X.Y-RELEASE`` with the actual version of the release you are using. The `GENERIC` kernel will be installed in `/boot/GENERIC` by default.

- Failing all the above, the `GENERIC` kernel may be rebuilt and installed from the sources:

      # cd /usr/src
      # env DESTDIR=/boot/GENERIC make kernel
      # mv /boot/GENERIC/boot/kernel/* /boot/GENERIC
      # rm -rf /boot/GENERIC/boot

  For this kernel to be picked up as `GENERIC` by `freebsd-update`, the `GENERIC` configuration file must not have been modified in any way. It is also suggested that it is built without any other special options (preferably with an empty `/etc/make.conf`).

Rebooting to the `GENERIC` kernel is not required at this stage.

Major and minor version updates may be performed by providing `freebsd-update` with a release version target, for example, the following command will update to FreeBSD 8.1:

    # freebsd-update -r 8.1-RELEASE upgrade

After the command has been received, `freebsd-update` will evaluate the configuration file and current system in an attempt to gather the information necessary to update the system. A screen listing will display what components have been detected and what components have not been detected. For example:

    Looking up update.FreeBSD.org mirrors... 1 mirrors found.
    Fetching metadata signature for 8.0-RELEASE from update1.FreeBSD.org... done.
    Fetching metadata index... done.
    Inspecting system... done.

    The following components of FreeBSD seem to be installed:
    kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games
    src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue
    src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin
    world/base world/info world/lib32 world/manpages

    The following components of FreeBSD do not seem to be installed:
    kernel/generic world/catpages world/dict world/doc world/games
    world/proflibs

    Does this look reasonable (y/n)? y

At this point, `freebsd-update` will attempt to download all files required for the upgrade. In some cases, the user may be prompted with questions regarding what to install or how to proceed.

When using a custom kernel, the above step will produce a warning similar to the following:

    WARNING: This system is running a "MYKERNEL" kernel, which is not a
    kernel configuration distributed as part of FreeBSD 8.0-RELEASE.
    This kernel will not be updated: you MUST update the kernel manually
    before running "/usr/sbin/freebsd-update install"

This warning may be safely ignored at this point. The updated `GENERIC` kernel will be used as an intermediate step in the upgrade process.

After all patches have been downloaded to the local system, they will then be applied. This process may take a while depending on the speed and workload of the machine. Configuration files will then be merged -- this part of the process requires some user intervention as a file may be merged or an editor may appear on screen for a manual merge. The results of every successful merge will be shown to the user as the process continues. A failed or ignored merge will cause the process to abort. Users may wish to make a backup of `/etc` and manually merge important files, such as `master.passwd` or `group` at a later time.

> Note: The system is not being altered yet, all patching and merging is happening in another directory. When all patches have been applied successfully, all configuration files have been merged and it seems the process will go smoothly, the changes will need to be committed by the user.

Once this process is complete, the upgrade may be committed to disk using the following command.

    # freebsd-update install

The kernel and kernel modules will be patched first. At this point the machine must be rebooted. If the system was running with a custom kernel, use the nextboot(8) command to set the kernel for the next boot to `/boot/GENERIC` (which was updated):

    # nextboot -k GENERIC

> Warning: Before rebooting with the `GENERIC` kernel, make sure it contains all drivers required for your system to boot properly (and connect to the network, if the machine that is being updated is accessed remotely). In particular, if the previously running custom kernel contained built-in functionality usually provided by kernel modules, make sure to temporarily load these modules into the `GENERIC` kernel using the `/boot/loader.conf` facility. You may also wish to disable non-essential services, disk and network mounts, etc. until the upgrade process is complete.

The machine should now be restarted with the updated kernel:

    # shutdown -r now

Once the system has come back online, `freebsd-update` will need to be started again. The state of the process has been saved and thus, `freebsd-update` will not start from the beginning, but will remove all old shared libraries and object files. To continue to this stage, issue the following command:

    # freebsd-update install

> Note: Depending on whether any libraries version numbers got bumped, there may only be two install phases instead of three.

All third party software will now need to be rebuilt and re-installed. This is required as installed software may depend on libraries which have been removed during the upgrade process. The `ports-mgmt/portupgrade` command may be used to automate this process. The following commands may be used to begin this process:

    # portupgrade -f ruby
    # rm /var/db/pkg/pkgdb.db
    # portupgrade -f ruby18-bdb
    # rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db
    # portupgrade -af

Once this has completed, finish the upgrade process with a final call to `freebsd-update`. Issue the following command to tie up all loose ends in the upgrade process:

    # freebsd-update install

If the `GENERIC` kernel was temporarily used, this is the time to build and install a new custom kernel in the usual way.

Reboot the machine into the new FreeBSD version. The process is complete.

## 25.2.4 System State Comparison

The `freebsd-update` utility may be used to test the state of the installed FreeBSD version against a known good copy. This option evaluates the current version of system utilities, libraries, and configuration files. To begin the comparison, issue the following command:

    # freebsd-update IDS >> outfile.ids

> Warning: While the command name is IDS it should in no way be a replacement for an intrusion detection system such as `security/snort`. As `freebsd-update` stores data on disk, the possibility of tampering is evident. While this possibility may be reduced by using the `kern.securelevel` setting and storing the `freebsd-update` data on a read only file system when not in use, a better solution would be to compare the system against a secure disk, such as a DVD or securely stored external USB disk device.

The system will now be inspected, and a list of files along with their sha256(1) hash values, both the known value in the release and the current installed value, will be printed. This is why the output has been sent to the `outfile.ids` file. It scrolls by too quickly for eye comparisons, and soon it fills up the console buffer.

These lines are also extremely long, but the output format may be parsed quite easily. For instance, to obtain a list of all files different from those in the release, issue the following command:

    # cat outfile.ids | awk '{ print $1 }' | more
    /etc/master.passwd
    /etc/motd
    /etc/passwd
    /etc/pf.conf

This output has been truncated, many more files exist. Some of these files have natural modifications, the `/etc/passwd` has been modified because users have been added to the system. In some cases, there may be other files, such as kernel modules, which differ as `freebsd-update` may have updated them. To exclude specific files or directories, add them to the `IDSIgnorePaths` option in `/etc/freebsd-update.conf`.

This system may be used as part of an elaborate upgrade method, aside from the previously discussed version.

Prev | Home | Next
Updating and Upgrading FreeBSD | Up | Portsnap: A Ports Collection Update Tool