= Upgrading All FreeBSD Ports via portupgrade =

''portupgrade'' is a tool that allows you to upgrade ports on your FreeBSD system. It has its faults, and it doesn't always work (see below), but its about as close as you can get on FreeBSD to a 'one-click' upgrade.

There are other tools for doing upgrades, and several (including ''portupgrade'' are outlined in the [[http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports-using.html#PORTS-UPGRADING|FreeBSD handbook]].

== Before the Upgrade ==

Think about updating the base system. See the [[freebsd-stable-upgrade|FreeBSD - Stable Upgrade]] page, or do a binary update.
== Prepare to Upgrade ==

First, make sure the ports tree and index file are up-to-date. You can do this either via ''portsnap'', or via ''cvsup''. 

==== CVSup Method ====
 * ''cd /usr/ports''
 * ''cvsup ports-supfile'' (if you're doing this for the first time, you'll need to copy the ''ports-supfile'' from ''/usr/share/examples/cvsup/ports-supfile'' to ''/usr/ports/ports-supfile'', and change the settings in the file as appropriate).
 * ''portsdb -Uu'' to sync up the ports index file with the ports tree you just updated

==== portsnap Method ====
 * ''portsnap fetch''
 * ''portsnap extract''  (only needed the first time you run portsnap)
 * ''portsnap update''

Once the ports are up to do, you should backup the package database:
 *''tar  cvfz ~/pkg_db_backup.tar.gz /var/db/pkg''

Run an audit:
 * ''portaudit -Fda''

Then, update the package database:
 * ''pkgdb -F''

If the database is corrupted, fix it:
 * ''pkgdb -fu''

Look at the packages that need to be updated (note that ''portversion'' uses the ports index file, so you need to make sure you ran ''portsdb -Fu'' earlier to get the latest file):
 * ''portversion -v | grep -v up-to-date''

To see the full list, do:
 * ''portversion -v''

If you would prefer to check your ports against an actual can of the ports tree, you can use ''pkg_version'' instead of ''portsversion'': 
 * ''pkg_version -v''
Doing it this way is a lot slower than using ''portversion''

== Doing the Upgrade ==

First, figure out if any packages need to be upgraded manually. There isn't really any good way of doing this that I've figured out, but I've made a list of packages I've had problems with below. Feel free to add to it.

Next, do the actual update. You can do this one of two ways: either do a fully automatic upgrade, or do the upgrade bit-by-bit. The latter is **STRONGLY** recommended, as it allows you to go slowly and test things. The fully automatic upgrade will break things, and may take a lot of time to fix.

 * Do it all at once: ''portupgrade -aRv''  If you do decide to do this, you will want to use the -x option to exclude packages that shouldn't be upgraded automatically (see below), or upgrade those packages manually first.

 * Do it one package at a time: ''portupgrade -Rv <pkgname>'' The ''-R'' is optional; it will upgrade all the packages that ''<pkgname>'' depends on.

== After the Upgrade ==

Run ''portsclean -PCDL'' to clean up old ports, libraries, distfiles and packages.

Then, reboot and then check /var/log/messages for any errors. Also check that all expected services are working on the box.
== Updating Multiple Servers ==

On the first server you do the upgrade on, do:
 * Create the ''/usr/ports/packages'' directory if it doesn't exist already
 * ''portupgrade -p -aRv''  This will build packages for each port in ''/usr/ports/packages''
 * tar up the contents of the packages directory, and copy it to another server: ''cd /usr/ports/packages; tar cvfz ~/packages_030309.tar.gz *''
 * Once logged into the other server, use ''portupgrade -P -aRv'' to install the ports using the packages you've made.

== Notes on the Special Snowflakes == 

Some software doesn't behave well with the ''portupgrade'' process. Sometimes it's because you need to run a certain command after the upgrade and ''portupgrade'' doesn't know about it, or because you've installed the software with custom configuration options (although there are ways to mitigate that).

 * **Perl** If perl needs to be upgraded, you should do that FIRST (manually), then run ''perl-after-upgrade -f'' to tell the system about the new version and update all packages necessary. See ''man perl-after-upgrade'' for full details.

 * **DSpam** If DSpam is part of the upgrade process, you'll have to upgrade the CGI part of it by hand. Once its installed, you'll probably have to reset perms on ''/var/db/dspam'' to that the ''dspam'' user can write to its database.
 

== Other Notes ==
 
 * **WARNING:** If you have a lot of ports installed (who doesn't?), start this process **EARLY** in the day, because the whole thing takes several hours to run, and there are usually a few things that have to be fixed manually at the end.

 * If some ports will not compile because of security problems, make them manually and use
''make -DDISABLE_VULNERABILITIES'' Of course, make sure you actually know what you're getting yourself into when you're installing a port with known vulnerabilities.