Keeping up-to-date

• Updating the ports collection and source
• Updating the registry databases
• Updating the kernel
• Updating installed packages

New ports is added and existing is updated every day, therefore you have to maintain your ports collection. The applications you installed from your ports collection also need to be upgraded from time to time.

You need two tools to carry out these tasks CVSup and portupgrade.

• CVSup will keep the information in your ports collection op to date (remember that the ports collection don't actually contain the applications, only the information on how to get the source code and installing it.
• Portupgrade will help you keep the installed applications up to date (upgrading to newer versions).

I'll assume that CVSup is installed. Portupgrade is installed from
/usr/ports/ports-mgmt/portupgrade/

Updating the ports collection and source

I update the source daily, and ports weekly. For this purpose I have two files which is used by cvsup when updating: src-all and ports-all.

Content for /etc/cvsup/src-all :

*default host=cvsup.dk.FreeBSD.org
*default base=/usr
*default prefix=/usr
*default release=cvs tag=RELENG_6
*default delete use-rel-suffix
#*default compress
src-all

Content for /etc/cvsup/ports-all :

*default host=cvsup.dk.FreeBSD.org
*default base=/usr
*default prefix=/usr
*default release=cvs tag=.
*default delete use-rel-suffix
#*default compress
ports-all tag=.
docs-all tag=.

Text in bold should be replaced with values of your choice: I have cvsup.dk.FreeBSD.org as the nearest server for fetching updates and RELENG_6 means I get the latest stable version 6.x (for more information see /usr/share/examples/cvsup/ports-supfile).

It is now possible to update your ports like this:

cvsup -g -L 2 /etc/cvsup/ports-all

... and your source like this

cvsup -g -L 2 /etc/cvsup/src-all

If you want to make sure the update runs, even if you are disconnected from the machine, you can use nohup like this:

nohup [commands here] > log-file.log &

The command will now run on its own independent of your account. You can follow the progress by tailing the log file:

tail -f log-file.log

Here is an example:

nohup cvsup -g -L 2 /etc/cvsup/ports-all > ports-all.log &
tail -f ports-all.log

Updating registry databases

After each update of the ports collection, it is recommended that you run 'portsdb -Uu' in order to keep /usr/ports/INDEX and the /usr/ports/INDEX.db database always up-to-date and in sync with the ports collection.

portsdb -Uu
Updating the ports index ... Generating INDEX.tmp - please wait.. Done.
done
[Updating the portsdb <format:bdb1_btree> in /usr/ports ... - 11875 port
entries found .........1000.........2000.........3000.........4000.........
5000.........6000.........7000.........8000.........9000.........10000.........
11000........ ..... done]

If instead the above command returns this...

...
/usr/ports/INDEX-5:3:Port info line must consist of 10 fields.
/usr/ports/INDEX-5:4:Port info line must consist of 10 fields.
/usr/ports/INDEX-5:5:Port info line must consist of 10 fields.
...

... it could be that the format of portupgrade has changed. A reinstallation of portupgrade has been known to fix this problem.

Sometimes you get warnings when running 'portsdb -Uu'. Example:

Updating the ports index ... Generating INDEX.tmp - please wait..
Warning: Duplicate INDEX entry: freeciv-gtk-2.0.7
Warning: Duplicate INDEX entry: openssl-stable-0.9.7i
Warning: Duplicate INDEX entry: mod_rpaf-ap2-0.5

You don't need to worry about duplicate entry warnings, but you may consider using make fetchindex from /usr/ports instead of portsdb -U, which will download a pre-made, current copy of the INDEX file for you. It takes about 30 seconds, compared to the time it takes to rebuild the INDEX from scratch. When using fetchindex you must run portsdb -u afterwards to create the binary database used by portupgrade.

Another database keeps track on installed software. You will at some point encounter stale dependencies, cyclic dependencies, complete stale or missing origins and duplicates in this database. These problems can be fixed with the pkgdb tool. You should run this command periodically so portupgrade(1) and other pkg_* tools can work effectively and reliably.

It might look something like this:

pkgdb -F
Duplicated origin: textproc/expat2 - expat-1.95.6_1 expat-1.95.7
Unregister any of them? [no] yes
Unregister expat-1.95.6_1 keeping the installed files intact? [no] yes

Stale dependency: mod_php4-4.3.5_7,1 -> apache-1.3.29_3 (www/apache13):
apache+mod_ssl-1.3.29+2.8.16_1 (score:88%) ? ([y]es/[n]o/[a]ll) [yes] yes
Fixed. (-> apache+mod_ssl-1.3.29+2.8.16_1)

The expat package was registered twice with to different versions. pkgdb automatically suggests to keep the name of the most recent version and unregister the old one.

I recently uninstalled apache and replaced it with apache-mod_ssl. This caused the above problem in the registry database since php still has the old apache package name registered as a dependency. By answering yes, pkgdb fixed this.

When ports and source is updated, and your databases are in shape, it is time to have a look at the FreeBSD kernel and installed software.

Updating the kernel

Before doing this, you should backup any important data and the /etc directory. Also read the UPDATING file in /usr/src/ which provides valuable information (all entries are marked with a date. You should of course just read those added since your last update).

If the output from cvsup /etc/cvsup/src-all shows that important files has been updated, it is time to build the kernel. This takes quite a while, depending on the speed of the computer. My 1.5Ghz cpu server builds a new kernel in approximately 1 hour.

The steps for updating the kernel is:

# uname -a # cvsup -g -L 2 /etc/cvsup/src-all
# cd /usr/src
# make buildworld
# make buildkernel KERNCONF=GENERIC
# make installkernel KERNCONF=GENERIC
# mergemaster -p
# make installworld
# mergemaster -i
# reboot
# uname -a

Run 'uname -a' and save the output for later. When your are done, run it again to confirm the update.

As explained earlier, cvsup will fetch the source from which the new kernel is build. After that you cd into the /usr/src directory to build the world and build/install the kernel.

And then the ugly monster appears... mergmaster.

The command 'mergemaster -p' is used to compare files known to be essential to the success of {build|install}world. This one is not likely to give you any trouble.

It takes a few updates to become confident with 'mergemaster i'. As you can almost guess from the name, mergemaster is used to merge files which have been changed. It's up to you to decide which changes you want to keep. The -i options tells mergemaster to automatically install any files that do not exist.

The first question that appears with 'mergemaster -i' is whether or not you want to delete the old '/var/tmp/temproot':

*** The directory specified for the temporary root environment, /var/tmp/temproot, exists. This can be a security risk if untrusted users have access to the system.

Use 'd' to delete the old /var/tmp/temproot and continue
Use 't' to select a new temporary root directory
Use 'e' to exit mergemaster

Default is to use /var/tmp/temproot as is

How should I deal with this? [Use the existing /var/tmp/temproot]

If temproot is a leftover from a previous run, choose 'd'. If you need to re-run mergemaster, do it with 'mergemaster -r'. The -r options tells mergemaster to just use the current temproot.

I always choose 'install' (i), when presented to changes in files I never modified. But when mergemaster reaches a customized file, I choose 'merge' (m).

If you are too quick with the [enter] button, mergemaster will leave the existing file unchanged, since this is the default. But this is no disaster, just run mergemaster again (with the -r options), when your done. But I generally use [arrow down], since it does not let you get past the question at the end of each file diff.

... and now proceed to the exiting part of an upgrade - reboot :-). If your server seems happy after a reboot, you are homefree... You should check that any running applications are still working.

Updating installed packages

You should read all entries of /usr/ports/UPDATING added since the last update. It informs you of any vital information that might be needed for updating packages. If you skip this, the punishment may be prompt and cruel.

Run this command. It produces a lot of output, but at the end you will get a list of all installed ports. Those in need of update, will be marked with a + sign.

portupgrade -a -n

The -a options says "update all packages", and the -n option ensures that it is not actually executed. So it does not do anything, it just shows what would be done.

You now have a list of packages in need of update. To update a package an dependencies (both upwards and downwards), do...

portupgrade -rR <packagename>

Example:

portupgrade -rR mysql-server-5.0.37

The above will update the mysql-server, and any other packages it depends on (-r) and also packages which depend on mysql-server (-R).

You can execute 'portupgrade -a -n' once in a while to view your progress.

Remember to run pkgdb -F when you are done.

To make sure your packages are always build by portupgrade with the same arguments, add them to the MAKE_ARGS section of pkgtools.conf (located in /usr/local/etc). The comments contains some nice examples.