FreeBSD --- UPGRADING IT

Upgrading network servers is perhaps the most annoying 
task in the system administrator’s routine. I can 
manage unexplained behavior on my desktop 

after an upgrade, but when a whole company 
or hundreds of customers depend on one 

system, even thinking of touching
that system makes my bowels 

churn.

While a few Unix-like systems have straightforward upgrade 

procedures, they require several hours to complete and a 

certain amount of luck. On the other hand, one of 

FreeBSD’s greatest strengths is its upgrade 

procedure.

FreeBSD Versions

Upgrading FreeBSD is a relatively simple matter because of the FreeBSD’s development method. FreeBSD is a continually evolving operating system. If you download the current version of FreeBSD in the afternoon, it will be slightly different from the morning version. Developers from around the world continually add changes and improvements, which makes the traditional strict release numbering used by less open software impractical. At any given moment, you can get several different versions of FreeBSD:

• Releases  If you’re in a production environment, you should probably install a release version of FreeBSD and then patch your system to the proper errata branch.
      A FreeBSD release has a conventional version number, like those you’d see on any other software: 5.5, 6.3, 7.0, and so on. A release is simply a copy of the most stable version of FreeBSD at a particular moment in time. Three or four times a year, the Release Engineering team asks the developers to focus on resolving outstanding problems rather than making major changes.
      The Release Engineering team cuts several release candidates from this code and offers each for public testing. When the FreeBSD team is satisfied with the results of their own and the community’s testing, the result is given a release number. The development team then returns their attention to their regular projects.

• Errata Branches  An errata branch is a particular FreeBSD release plus any security and stability patches issued for that release. While the FreeBSD team works very hard to assure that each and every release is bug free, that goal just isn’t realistic. It sometimes happens that a security junkie with nothing better to do discovers a new way to breach deployed servers a week after FreeBSD’s latest release. The security team provides the errata branches to support users who want their systems to remain as stable as humanly possible without sacrificing security.
      Each release has its own errata branch. For example, FreeBSD 7.0-errata is different than FreeBSD 7.1-errata, and upgrading between the two is just as error-prone as upgrading from FreeBSD 7.0 to FreeBSD 7.1. API and ABI changes are completely, absolutely, entirely forbidden in an errata branch; applications that work on a release will perform in exactly the same manner on any version of the errata branch. For maximum stability, stay with the errata branch of the version you installed. The FreeBSD Project supports errata branches for two years after release, but this can change. Watch http://www.freebsd.org/security or the FreeBSD-announce@FreeBSD.org mailing list for updates on support scheduling and end-of-life notices.
      Of course, with the source code available, it’s possible for you to continue to support an old release for as long as you use it. You just can’t expect the FreeBSD team to keep doing all the work for you forever!
  

• FreeBSD-current  or just -current, is the bleeding-edge, latest version of FreeBSD which contains code that is making its first public appearance.
  While the developers have test servers and post patches for review before applying, that’s still much less exposure than the wide userbase of FreeBSD-current. FreeBSD-current is where much initial peer review takes place; at times, -current undergoes radical changes that give experienced system administrators migraines.
      FreeBSD-current is made available for developers, testers, and interested parties, but it is not intended for general use. Support for user questions about -current is very slim because the developers simply don’t have time to help a user fix his web browser while thousands more critical problems demand attention.  Users are expected to help fix these problems or to patiently endure them until someone else fixes them.
      To make matters worse, -current’s default settings include assorted debugging code, special warnings, and related developer features. These make -current run slower than any other version of FreeBSD. You can disable all this debugging, but if you do so, you won’t be able to file a proper trouble report when you have a problem. This means that you’re even more out on your own. Check out the file /usr/src/UPDATING on your -current system for debugging details. If you can’t read C and shell code, or don’t feel like debugging your OS, or don’t like computer functions failing arbitrarily, or just don’t like being left hanging until your problem annoys someone who can fix it, -current is not for you. The brave are certainly welcome to try -current, as is anyone willing to devote a large amount of time to learning and debugging FreeBSD or anyone who needs a lesson in humility.
     You are not forbidden to use -current; you’re just on your own. -current isn’t always the bleeding edge, but sometimes it might be the why-are-my-fingers-suddenly-little-wiggling- stumps? edge. You have been warned.
      To run -current you must read the FreeBSD-current@FreeBSD.org and cvs-src@FreeBSD.org mailing lists. These are high-traffic lists with hundreds of warnings, alerts, and comments a day. If you’re reading these lines, you probably shouldn’t post on these lists; just read and learn. If someone discovers that the newest filesystem patches transform hard drives into zombie minions of Cthulhu, this is where the information will be made available.   
• -current Code Freezes   Every 12 to 18 months, FreeBSD-current goes through a month of code freeze, during which no non-critical changes are permitted  and all known critical problems are being fixed. The goal is to  stabilize FreeBSD’s latest and greatest and to polish off the rough corners. At the end of the code freeze (or shortly after), -current becomes the .0 release of a new version of FreeBSD. For example, FreeBSD 6.0 was -current at one point, as was FreeBSD 7.0. Once the .0 release is out the door, current work branches into two lines: FreeBSD-current and FreeBSD-stable.

• FreeBSD-stable  or just -stable is the “bleeding edge for the average user,” containing some of the most recent peer-reviewed code. FreeBSD-stable is expected to be calm and reliable, requiring little user attention. Once a piece of code is thoroughly tested in -current, it might be merged back into -stable. The -stable version is the one that is mostly safe to upgrade to at almost any time; you might think of it as FreeBSD-beta.
      As -stable ages, the differences between -stable and -current become greater and greater, to the point where it becomes necessary to branch a new -stable off of -current. The older -stable is actively maintained for several months while the new -stable is beaten into shape. Some users upgrade to the new version of -stable immediately, others are more cautious. After a release or two of the new -stable, the older -stable is obsoleted and the developers encourage users to migrate to the new version. After some time, the older -stable will be receiving only critical bug fixes, and finally it will be abandoned entirely. You can see how this works in Figure 13-1.
      Every so often -stable is polished and tested. Developers stop backporting features from -current and focus on testing. When everyone’s happy with -stable’s quality, it’s issued a number and released. For example, the fourth release of FreeBSD 7 is FreeBSD 7.3. FreeBSD 7.3-release is just a point on the continuum of FreeBSD-stable 7. Users of FreeBSD-stable must read the FreeBSD-stable@FreeBSD.org mailing list. While this mailing list has a moderate level of traffic and a fair amount of question-and-answer exchanges that really should be on -questions@, important messages from developers generally have a subject beginning with HEADS UP. Look for those messages; they generally mean that a change in the system can ruin your day if you don’t know about it. 
• Merging from -current
  The phrase merged from -current (MFC) means that a function or subsystem has been backported from FreeBSD-current into FreeBSD-stable (or, rarely, into an errata branch). Not all features are MFC’d, however. The point of FreeBSD-current is that it’s where major changes take place, and many of those changes require months of testing and debugging. Those large changes cannot be backported, as they would badly impact the -stable users who expect a stable codebase. New drivers, bug fixes, and minor enhancements can be MFC’d—but that’s about it. The FreeBSD Project makes it a point to not MFC large changes that could break user applications.

• Snapshots   Every month or so, the FreeBSD Release Engineering team releases snapshots of -current and -stable and makes them available on an FTP site. Snapshots are just points along the development branch; they undergo no special packaging or testing. Snapshots do not receive the same attention to quality that releases do, but are intended as a good starting point for people interested in running -current or -stable. There is only modest quality control, and many developers have no idea that a snapshot has come out until it appears on the FTP servers. You will find bugs. You will find errors. You will experience issues.

T H E   S T AB I LI T Y   O F  -S T AB LE

The word stable describes the code base, not FreeBSD itself. Running code from a random point along a stable branch doesn’t guarantee that your system will be stable, only that the underlying code won’t change radically. The API and ABI are expected to remain unchanged. While the developers take pains to ensure that -stable remains, well, stable, mistakes can and do happen. If this risk worries you, run an errata branch.

FreeBSD and Testing
Each version and release of FreeBSD is tested in a variety of ways. Individual developers check their work on their own hardware and ask each other to double-check their work. If the work is sufficiently complicated, they might use a private source code repository to offer their work to a broader community before committing it to -current.
    Coverity has donated analysis software to the FreeBSD team so that the source code can be automatically audited, tested, and debugged on an ongoing basis, catching many errors before they have a chance to affect real-world users.
    Corporations such as Yahoo!, Sentex, and iX Systems have donated high-quality test facilities to the FreeBSD Project, providing a build/test server farm for the security team and a network performance test cluster for the kernel team. Several highly regarded FreeBSD developers have made testing a major issue within the Project.
    Ultimately, however, a volunteer project with a few hundred developers cannot purchase all computer hardware ever made, nor can they run that hardware under all possible loads. The FreeBSD Project as a whole relies on donations from hardware vendors who want their equipment to run FreeBSD, companies who want to use FreeBSD on the equipment they already own, and on the user base.
    The most useful testing comes from users who have real-world equipment and real-world testbeds with real-world workloads. Sadly, most of these users perform testing when they

• put a release CD into the computer, 
• run an install, and 
• fire up the system.

 At that point, it’s too late to benefit the release. Any bugs you find might help the next release, but in the meantime an upgrade to the errata branch for that release might fix your problem.
    The solution here is obvious—test FreeBSD on your real-world workloads before the release is cut. Requests for testing of new -stable releases appear on FreeBSD-stable@FreeBSD.org. By testing a -stable or -current, you will get even better value from FreeBSD.


Which Version Should You Use?
-current, -stable, -errata, snapshots—the head spins. Yes, this seems complicated, but it all works to ensure levels of quality.

• Users can rest assured that an errata branch is as stable as possible and has been through extensive testing and peer review.
• The same user knows that the nifty new features in -stable and -current are available, if he’s willing to assume the risk inherent in each version.

So, which version should you use? Here are my suggestions:

•  Production If you’re using FreeBSD in a production setting, track an errata branch  of a -stable release.
• Test If you’re interested in how FreeBSD changes will affect your environment, track -stable on a test system.
• Development Operating system developers, people with too much spare time and too little excitement, and blind idiots should run -current. When -current destroys your MP3 collection, debug the problem and submit a patch to fix it.
• Hobby If you’re a hobbyist, run any version! Just keep in mind the limitations of the branch you choose. If you’re just learning Unix, I’d recommend -release. Once you have your feet under you, upgrade to -stable. If you have nothing but utter contempt for your data, the masochists on -current.

Upgrade Methods

FreeBSD provides three main ways to upgrade:

• sysinstall  is the FreeBSD installer; it can be used to upgrade to whatever release that installer ships with. For example, the installer for FreeBSD 7.5 can be used to upgrade to FreeBSD 7.5. Use sysinstall when upgrading from one release or snapshot to another.

• binary  FreeBSD supports binary updates through freebsd-update. This is very similar to the binary update services offered for Windows, Firefox, and other commercial software.
  
      You can use freebsd-update to upgrade on an errata branch.
  
  
• source Using source code allows you to build the programs that make up FreeBSD and install them to your hard drive. For example, if you have the source code for FreeBSD 7.5, you can upgrade to that version. This requires more effort to set up and use, but gives you much more flexibility.
  
      Upgrade from source when tracking -stable or -current.

Upgrades can destroy your data. Back up your system before attempting any sort of upgrade! I upgrade my laptop every week or so, just for fun (see my earlier comment about blind idiots and -current). But before I upgrade, I make sure that all my important data is on a tarball safely cached on another machine. Copy your data to tape, file, or whatever, but don’t run an upgrade without a fresh backup. You have been warned.

Binary Updates
Many operating systems offer binary updates, where users can download new binaries for their operating system.

1. FreeBSD provides a similar program with freebsd-update, allowing you to easily upgrade your system along an errata branch. freebsd-update does not let you track -stable or -current, only an errata branch. For example, if you installed FreeBSD 7.0, freebsd-update will help you upgrade to 7.0-errata but not 7.0-stable or 7.1-release.
2. freebsd-update is designed to be used with standard systems running the GENERIC kernel. If you have upgraded from source, freebsd-update is not suitable for your system. Similarly, freebsd-update only provides patches to the GENERIC kernel. If you have a custom kernel, you must build updates to your kernel by hand instead of relying upon the update service.

Perform binary updates with freebsd-update(8), as configured in /etc/freebsd-update.conf.


/etc/freebsd-update.conf
freebsd-update(8) is designed to be seamless for the average user, and updating its configuration is rarely advisable. You might have unusual circumstances, however, so here are the most useful options you’ll find in this file:

$ cat /etc/freebsd-update.conf
# $FreeBSD: src/etc/freebsd-update.conf,v 1.6.2.2.2.1 2009/10/25 
01:10:29 kensmith Exp $

# Trusted keyprint.  Changing this is a Bad Idea unless you've received
# a PGP-signed email from  telling 
you to
# change it and explaining why.
KeyPrint 800651ef4b4c71c27e60786d7b487188970f4b4169cc055784e21eb71d410cc5

# Server or server pool from which to fetch updates.  You can change
# this to point at a specific server if you want, but in most cases
# using a "nearby" server won't provide a measurable improvement in
# performance.
ServerName update.FreeBSD.org

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

# Example for updating the userland and the kernel source code only:
# Components src/base src/sys world

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

# Paths which start with anything matching an entry in an IDSIgnorePaths
# statement will be ignored by "freebsd-update IDS".
IDSIgnorePaths /usr/share/man/cat
IDSIgnorePaths /usr/share/man/whatis
IDSIgnorePaths /var/db/locate.database
IDSIgnorePaths /var/log

# 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
# 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/ /boot/device.hints


### Default configuration options:

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

# Destination to send output of "freebsd-update cron" if an error
# occurs or updates have been downloaded.
# MailTo root

# Is FreeBSD Update allowed to create new files?
# AllowAdd yes

# Is FreeBSD Update allowed to delete files?
# AllowDelete yes

# If the user has modified file ownership, permissions, or flags, should
# FreeBSD Update retain this modified metadata when installing a new 
version
# of that file?
# KeepModifiedMetadata yes

# 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 installing a new kernel perform a backup of the old one first
# so it is possible to boot the old kernel in case of problems.
# BackupKernel yes

# If BackupKernel is enabled, the backup kernel is saved to this
# directory.
# BackupKernelDir /boot/kernel.old

# When backing up a kernel also back up debug symbol files?
# BackupKernelSymbolFiles no

KeyPrint 800...
KeyPrint lists a cryptographic signature for the update service. If the FreeBSD Update service suffered a security breach and an intruder replaced the patches with Trojan horse versions, the FreeBSD Project would need to repair the breach and issue new cryptographic keys. In this case, the breach would be announced on the security announcements mailing list (and would also be big news in the IT world). In other words, there’s no reason to change this in normal use and very little reason to change it in abnormal use.

ServerName update.freebsd.org
The ServerName tells freebsd-update(8) where to fetch its updates from. While the FreeBSD Project does provide the tools to build your own updates, those tools are poorly documented. Configuring your own update server is for the brave.

Components src world kernel
By default, FreeBSD Update provides the latest patches for the source code in /usr/src, the userland (world), and the GENERIC kernel. You might not need all of these components, however.
    While the kernel and userland are mandatory, you might not have the source code installed on your machine. In that case you could eliminate the src entry and only fetch the userland and kernel updates. You could also choose to receive only portions of the source code update, as described in freebsd-update.conf(5).

UpdateIfUnmodified  /etc/   /var/
FreeBSD Update provides updates to configuration files in /etc. If you have modified these files, however, you probably don’t want freebsd-update(8) to overwrite them. Similarly, /var is very fluid, designed for customization by the system administrator; you don’t want FreeBSD Update to muck with your settings.
    FreeBSD Update only applies patches to files in the directories listed in UpdateIfUnmodified if they are unchanged from the default.
 
MailTo root
If you schedule a run of FreeBSD Update (as described later), freebsd-update(8) sends an email of the results to the account listed in MailTo.

KeepModifiedMetadata yes
Perhaps you’ve modified the permissions or owner of a system file or command. You probably don’t want freebsd-update(8) to change those permissions back.
    With KeepModifiedMetadata set to yes, freebsd-update(8) leaves your custom permissions and ownership unchanged.


Running freebsd-update(8)
Updating your system with binary updates has two stages:

1. downloading the updates and 
2. applying them.

To download the latest updates to your errata branch, run freebsd-update fetch.

# freebsd-update fetch

You’ll see the program finding the download sources for the patches, comparing cryptographic keys for those download sources, and eventually downloading patches. Finally you’ll see a message(see Fig.):

The following files will be updated as part of updating to 8.0-RELEASE-p4:

freebsd-update(8) stores these files in /var/db/freebsd-update. To install the downloaded files, run freebsd-update install:

# freebsd-update install
Installing updates... done

That’s really everything. Reboot your system, and you’ll see that you’re running the newest errata branch!

$ uname -a After freebsd-upgrade install and Before reboot
FreeBSD harrykarfBSD.homelinux.net 8.0-RELEASE FreeBSD 8.0-RELEASE #0: Tue May 25 20:52:11 UTC 2010     root@amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC  amd64
$ uname -a  After freebsd-upgrade install and After reboot
FreeBSD harrykarfBSD.homelinux.net 8.0-RELEASE-p3 FreeBSD 8.0-RELEASE-p3 #0: Tue May 25 20:54:11 UTC 2010     root@amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC  amd64

Scheduling Binary Updates
Best practice would say to download and apply updates at a consistent time on a regular schedule, such as on your monthly maintenance day.

FreeBSD Update includes specific support for this, to avoid flooding the download servers with requests every hour, on the hour. The freebsd-update cron command tells the system to download the updates at a random point in the next hour. Put this command in /etc/crontab to download updates during that one-hour window. This helps reduce the load on the download servers.

You’ll get an email when the system has updates, so you can schedule a reboot at your convenience.


Optimizing and Customizing freebsd-update
Two common questions about FreeBSD Update concern the custom builds of FreeBSD and distributing updates locally.
    Many people build their own versions of FreeBSD for internal use. Frquently, this is just a version of FreeBSD with various sections cut out, like NanoBSD verions, but some companies use extensive modifications. If you have deleted files from your FreeBSD install, freebsd-update(8) will not attempt to patch them.
    Similarly, many companies like to have internal update servers for patch management. The FreeBSD Update system is specifically designed to work with caching web proxies. While all the files are cryptographically signed and verified, they are transmitted over vanilla HTTP so that your proxy can cache them. This reduces bandwidth usage.

If you really want to build your own FreeBSD Update server, the code for the update server is available in the FreeBSD CVS repository under the projects directory. If you don’t understand what this means, you really should not be building your own update server.

Upgrading via sysinstall
The FreeBSD installer, sysinstall(8), can also upgrade a system from one release of FreeBSD to another or from the errata branch of one release to another release.
    The sysinstall upgrade path simply overwrites the old binaries on disk with the binaries from the next release. For example, if you’re running 7.1-errata, you can use sysinstall to upgrade to 7.2.

Note that this sort of upgrade is most successful when making comparatively small jumps. Updating from 7.1 to 7.2 with sysinstall(8) is very likely to be successful, updating from 7.1 to 7.5 might give you headaches, and updating from 7.1 to 9.0 will probably cause problems.

The installation CD includes upgrade instructions in the Install document. Before you consider upgrading, read those instructions. Also check http://www.freebsd.org for any last-minute errata that may affect your upgrade. Finally, confirm the integrity of your backups.

You should also know that very few developers actually use sysinstall for upgrades. It’s provided only for the end users who really don’t want to build their own binaries. This means that the sysinstall upgrade method has a few more rough corners compared to other methods, such as updating from source code.

The easiest way to upgrade via sysinstall is to boot off the installation CD for the release you want to upgrade to. Then follow these steps:

1. When you reach the graphic install menu, choose the Upgrade an Existing System option.
2. sysinstall reminds you to read the upgrade instructions. If you haven’t yet read them, do so now.
3. You must now choose the distribution components. Here, it’s best to update exactly the same software you installed originally. For example, if you installed the Developer distribution set, upgrade the Developer distribution set. Choosing a different distribution set causes headaches. For example, if you installed a complete FreeBSD 7.0 system but only upgrade to a minimal FreeBSD 7.1 install, you’ll have programs from 7.1 but documentation from 7.0.
4. sysinstall asks if you wish to install the Ports Collection. If you are using portsnap(8) or csup(1) to update your Ports Collection, you do not want to install the Ports Collection. If you are not updating your Ports Collection separately, install the new Ports Collection.
5. Back at the Distribution Sets menu, arrow up to Exit and leave the menu.
6. If you selected the system sources as an upgrade target, sysinstall(8) tells you that it cannot update the sources. That’s fine, proceed anyway.
7. Now you’re asked for a backup directory to store your original /etc in. Remember, /etc holds your vital system configuration information. The default /usr/tmp/etc might be fine, but I usually back up /etc somewhere on the root partition, such as /oldetc.
8. Finally, sysinstall asks for your installation source. Use the CD you booted from.
9. After offering you one last chance to change your mind, sysinstall overwrites all the system binaries you chose to install. It replaces your kernel with a GENERIC kernel of the new version and replaces many files in /etc.
10. Reboot.
11. After booting again, go through /etc and verify that your vital system files are in the condition you want. While your password and group files and /etc/fstab should be intact, you’ll want to check /etc/rc.conf and any other files you’ve edited.
12. Reboot again. Your base system is now safely upgraded. You must upgrade any third-party software separately.

Upgrading via Source
Another way to update your system is to build it from source code. FreeBSD is self-hosting, meaning that it includes all the tools needed to build FreeBSD.
    If you want to build the latest version of FreeBSD from source code, your first step is to get the latest source.
    When a developer releases improvements to FreeBSD, the changes are made available worldwide within about an hour (66 minutes, to be pedantic).
    The FreeBSD master source code server tracks the source code, all changes made to that code, and the author of those changes. Developers can check in new code, and users can check out the latest versions through Concurrent Versions System (CVS). CVS is a decent system for source code management, but an awful tool for source code distribution.

CVS requires large amounts of system resources and bandwidth, and heavy usage eats hard drives. FreeBSD’s resources are all donated, and it’s only polite to not waste them. Thus, instead of using CVS, the Project uses a custom-written CVS repository mirroring protocol. This is much faster, more efficient, easier on the servers, and generally nicer when supporting millions of users all over the world. The master CVS source code repository is replicated to the worldwide CVSup servers, and users download the source code from those mirrors with a tool called csup.

1. csup connects to a FreeBSD CVSup mirror, 
2. compares the source code on your machine to the source code on the server, and 
3. copies any changes to your local hard drive. 

As complex as this might sound, it’s actually fairly simple to use.

CSUP, CVSUP , CVS , AND SUP ?

A lot of FreeBSD documentation and websites mention using a tool called CVSup for source code updates. csup replaced CVSup for average end users, so you can ignore any references you see to CVSup or cvsup(1) as a program. A lot of related documentation still mentions CVSup, however; for example, the mirror servers are called cvsup servers, the sample configurations are in /usr/share/example/cvsup, and so on. Similarly, CVSup is a combination of CVS and sup (Software Update Protocol). You’ll see occasional mentions of these tools, but you don’t need to know them.

Begin by confirming that your system has the FreeBSD source code installed under /usr/src. This is the top directory of the FreeBSD source tree, which contains all the code needed to build all of FreeBSD. We discussed source code at length. Go ahead and look through these directories to get an idea of what source code looks like.
    If you find that this directory is empty, you haven’t installed the source. But don’t worry, you can install the source code from the installation CD by doing the following as root:

# mount /dev/acd0c /cdrom
# cd /cdrom/src
# ./install.sh all

If you don’t have an install CD, you can grab the source tarball from a FreeBSD FTP mirror.
    However you install the source, you start with the source code for the version of FreeBSD you installed. For example, the CDs for FreeBSD 7.0 contain the source code for FreeBSD 7.0. This source code is useful for managing the system as it is installed, but it isn’t what you want for an upgrade; if you build and install the source code for FreeBSD 7.0, you’ll end up reinstalling FreeBSD 7.0.

1. csup compares the source code on your disk to the source code available on the Internet
2. downloads the changes between the two versions. 
3. csup then applies these diffs to the source code you have on disk, changing it to the source code of the version you want.

This is far more efficient than redownloading the entire 450MB source tree every time you want to upgrade! Even if you skip a release or two between upgrades, csup will only have to download a megabyte or two of new source code to complete the changes. To update your source tree, tell csup

1. what to update
2. where to update it from, and 
3. how to perform the updates

Selecting Your Supfile
csup uses a configuration file, or supfile, to update your source repository. See /usr/share/examples/cvsup for sample supfiles for updating to different versions.
    Once you’ve chosen or written a supfile that meets your needs, you can use that supfile forever. A recent /usr/share/examples/cvsup contains the following samples:

• cvs-supfile This supfile maintains the entire FreeBSD source repository. While most users have no need for this, FreeBSD developers need it. Only use this if you roll your own releases, including floppy disk images, CD images, and so on. To get the entire CVS repository, you must use CVSup instead of csup.
• doc-supfile This supfile tells csup to update the system’s local documentation (the FAQ, Handbook, and associated articles). 
• gnats-supfile Use this to make a local copy of the FreeBSD Problem Report (PR) database. Again, most users won’t want this.
• ports-supfile This supfile updates your ports tree to the latest version. 
• stable-supfile Use this supfile to upgrade your source code to the latest stable version.
• standard-supfile This brings your source code up to the latest for the version of FreeBSD you are running. If you’ve installed a snapshot of FreeBSD 7-stable, it upgrades the source code to the latest FreeBSD 7-stable. If you’re running -current, it upgrades the source code to the most recent -current. If you’re tracking the FreeBSD 7.1 errata branch, it will bring your system up to the latest errata release of that version. (Historically, the standard-supfile only tracked -current.) 
• www-supfile This supfile downloads the latest version of the FreeBSD website.

The various components that can be updated with csup are called collections. For example, there is the source code collection, the documentation collection (doc-supfile), the Ports Collection (ports-supfile), and so on. Many collections are also broken up into subcollections. The source tree has subcollections for components such as userland programs, compilers, the kernel, and so on. Our main concern when upgrading FreeBSD is the source collection.


Modifying Your Supfile
Once you’ve chose the supfile you want, you must modify it to fit your environment. First, copy your chosen sample supfile under /etc and open it in your preferred editor. Any line beginning with a hash mark (#) is a comment, and
the sample supfiles have more comments than actual configuration entries.
Most supfiles have seven entries, much like this:

*default  host=CHANGE_THIS.freebsd.org
*default  base=/var/db
*default  prefix=/usr
*default  release=cvs tag=RELENG_6
*default  delete use-rel-suffix
*default  compress
src-all

Your first step is to choose a source code mirror, or CVSup server. You’ll find a complete list of mirrors at the FreeBSD website, but they generally have a name in the format

cvsup..freebsd.org

For example you’ll find cvsup15.us.FreeBSD.org (the fifteenth US CVS mirror),
cvsup2.si.freebsd.org (the second Slovenian mirror), and so on. Ping each server to determine which has the shortest response time from your part of the Internet, or use /usr/ports/sysutils/fastest_cvsup to automatically determine which CVSup server has the fastest response time.

1. Put your choice in the default host space marked by CHANGE_THIS.freebsd.org .
2. The *default base tells csup where to store status files, including a list of uploaded files. This accelerates future updates. The default means that you’ll find these files in /var/db/sup.
3. The *default prefix is where csup looks for the collection you’ve chosen. The default path is an src subdirectory under the prefix or, in this case, /usr/src. Don’t change this unless you want to store the system source code in a non standard location. csup(1) expects to control everything in this directory and can erase anything that doesn’t seem to belong.
4. The *default release indicates the data repository you’re synchronizing—in this case, the CVS repository. The tag= is a branch of the repository; this is where you select the desired FreeBSD version. 
5. When a developer removes some source files from the main FreeBSD repository, csup must remove those files from your system to maintain an identical copy. The delete keyword gives csup permission to do so. Similarly, the use-rel-suffix option allows csup to share a common base directory among several versions of the source without confusing them. 
6. Compression saves bandwidth and costs nothing but CPU time. Use it.  
7. Finally, tell csup which collection to update. The src-all flag tells
   csup to update the entire source tree.

The sample stable-supfile contains a commented-out list of subcollections, such as usr.bin (the contents of /usr/bin), contrib (the /usr/src/contrib directory), sys (the kernel), and so on.

You could theoretically update just one part of the source tree, but this is a spectacularly bad idea. Installing the /usr/bin programs from FreeBSD-current on your FreeBSD-stable system causes all sorts of unpredictable problems and is completely unsupported.

You can specify multiple collections in a single supfile. For example, I need access to the source code collection for FreeBSD 7-stable. As a documentation committer, I need the latest documentation collection. Finally, I want the latest ports tree so I can install the most recent software on my computer. You’ll find sample supfiles for each of these collections in /usr/share/examples/cvsup, but I don’t want to run csup once for each collection. I list each of these collections in my supfile.


A Complete Supfile
Here’s my complete supfile, including all the changes needed to update my source code:

*default host=cvsup15.us.freebsd.org
*default base=/var/db
*default prefix=/usr
*default release=cvs tag=RELENG_7
*default delete use-rel-suffix
*default compress
src-all
ports-all tag=.
doc-all tag=.

Note how few changes I’ve made to the sample. I chose a nearby CVSup server and set my desired version of FreeBSD . The last two lines are the interesting bit, where I add the ports-all and doc-all collections. Only the source code collection has releases or branches; if I ask for the RELENG_7 version of the ports tree, the CVSup server would have no idea what I’m talking about and I wouldn’t get any updates. By adding tag=. to the end of the collection name, I tell csup to get the latest version of this collection.


Blocking Updates: The Refuse File
While I want the whole source tree and the whole documentation tree, I only use certain parts of the ports tree. If you look under /usr/ports you’ll see
subdirectories for software in Arabic, French, German, Hebrew, Hungarian,
Japanese, Korean, Polish, Portuguese, Russian, Ukrainian, and Vietnamese.
While I’m glad that this software is available for people who speak those languages, the chances that I will need any of these programs range from negligible to non existent. To tell csup to not update these directories, make a file /var/db/sup/refuse that contains the directories you don’t want updated, much like this:

ports/arabic
ports/french
ports/german
...
ports/vietnamese

The refuse file cannot contain comments.

While you can refuse anything you like, it’s best to not refuse anything under /usr/src. If you refuse updates to a critical system program, that program will eventually become incompatible with the rest of the system.

Refuse files work by pattern matching, so a refuse file entry saying sys would block everything that contains the word sys, which happens to include the entire kernel source code under /usr/src/sys.

Make your refuse entries specific enough to block only what you really want to block.

If you use a refuse file, it’s best to delete the corresponding files from your hard drive. It’s better to have something fail because the software doesn’t exist than to have it fail in creative and difficult to diagnose ways because it exists but hasn’t been updated in three years.

Also, refuse files create risk. Updating only a part of the source tree will almost certainly cause build failures. The Ports Collection is designed to work as an integrated whole, and refusing parts of it can be problematic. While the  documentation tree is nicely segmented, you might have trouble even there. A refuse file might cause more trouble than it’s worth, but only you can decide that.

Updating System Source Code
Once you’ve created a supfile, run csup by becoming root and running this command:

# csup supfile
Cannot connect to 2001:468:902:201:209:3dff:fe11:442c: Protocol not 
supported
Connected to 128.205.32.21
Updating collection src-all/cvs
Edit src/Makefile
Edit src/Makefile.inc1
...

The first thing we see is a scary-looking warning that csup cannot connect to a really long string of hexadecimal numbers. That long string is an IPv6 address, which FreeBSD supports but most Internet service providers do not yet provide. csup then prints out each file it edits, and eventually prints Finished successfully when complete. Congratulations! You now have the latest source code.


Using csup to Get the Whole Source Tree
You can run csup without a local source tree installed. csup compares what you have (nothing) with what you need (everything) and installs what you’re missing (the whole tree).
    Mirror maintainers prefer that you install the source from CD if you have it, however; they’re donating servers and bandwidth for this service and would like as many people as possible to benefit from it.
A full uncompressed source tree fills about 450MB of disk space, while downloading updates to an existing tree only needs a few megabytes. Even with compression, you’re using a lot of donated bandwidth. The technical term for this type of activity is rude.

Resources

•  Release Engineering
• ABSOLUTE FREEBSD 2ND EDITION THE COMPLETE GUIDE TO FREEBSD (2008 by No Starch press) by Michael Lucas  ISBN: 978-1-59327-151-0