Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  PKG_UPGRADE (1)


pkg_upgrade - binary package management tool


     Explicit And Implicit Updates
     Library Changes
Implementation Notes
     Listing Outdated Packages
Implementation Details
     Download Manager
     Logfile Pseudo Bnf
Exit Codes
See Also


pkg_upgrade -h pkg_upgrade -a [-bcCdfFlnpvX] [-o new existing] [update] [install] pkg_upgrade [-bcCdfFlnpvX] [-r [-r]] [-R [-R]] [-o new existing] [update] [install]


The pkg_upgrade script allows the updating, installing and replacing of packages without using a local copy of the ports tree. Instead most required information is listed in an INDEX file that is kept in sync with the package server by uma(1).


The following options are available:
-a --all
  Updates all outdated packages listed in the INDEX file.

This flag is mutually exclusive with the -r and -R flags.

-b --no-backup
  Normally pkg_upgrade creates backups of deleted packages and leaves them in "%%PORTS%%/packages/pkg_upgrade-backup". This flag causes the deletion of theses backups right after a successful package installation or roll-back.
-c --clean
  Create clean output without status messages.
-C --replace-conflicts
  Causes existing packages that conflict with a new package to be replaced by the new package.

This flag is mutually exclusive with -X .

-d --list-discarded
  List the packages that are ignored because they are not indexed.
-f --force
  Assume every indexed package currently installed is outdated.
-F --fetch-only
  Instead of performing any updates, just download all packages that would have been required.
-h --help
  Displays the available options and terminate.
-l --no-logging
  Deactivate the logging of package installations.
-n --no-actions
  Instead of downloading required packages and performing the requested package updates and installations, just print what would have been done.
-o --origin new existing
  This flag causes an existing package to be replaced with a new one. Both named packages should be unambiguous.

An existing package can only be replaced once. While the existing argument only has to match an installed package or the origin of one, the new argument has to unambiguously identify a package listed in the INDEX file. For this the same rules as with the update and install arguments apply.

-p --paranoid
  Activates additional checks.

At the moment this only activates cyclic dependency checks. Cyclic dependencies can only be caused by errors in the ports tree used by the build server.

-r --recursive
  Also process packages the given packages depend on. Note that this is the meaning of -r used by pkg_info(1), not the meaning used by most popular port maintainance tools.

The -r flag can be specified a second time if the -R flag is also given. It causes the dependencies of depending packages listed for updating to be processed as well.

-R --upward-recursive
  Also process packages depending on the given packages.

The -R flag can also be specified for a second time to process packages depending on dependencies listed for updating as well. Because missing dependency checks are always performed, this does not require the -r flag.

-v --verbose
  Be verbose about what is currently being done.
-X --exit-on-conflict
  Instead of performing some kind of conflict handling simply exit if a conflict is encountered.

This flag is mutually exclusive with -C .

update install
  These arguments are either packages to update or to install. The pkg_upgrade script differs between package names and origins when interpreting these arguments.

Everything containing a "/" character is treated as an origin (e.g. "sysutils/bsdadminscripts"). Everything else is assumed to be a package name.

Origins or package names can either be explicit or contain the wildcards "*", "[...]" and "?". Whereas "*" matches any string, "?" matches any single character. The square brackets "[" and "]" enclose a list of characters that may be matched by a single character.

Arguments without wildcards are always attempted to be matched against a single package listed in the INDEX. Arguments with wildcards on the other hand can match more than one package. However wildcards are only matched against installed packages, so they can only be used for updating. To install new packages, the argument must not contain any wildcards.

While using origins is relatively simple, package names without wildcards are subject to a lot of guessing. If the complete argument either exactly matches an installed package or one listed in the INDEX, the identification is unambiguous.

If not pkg_upgrade tries to treat the argument as a LATEST_LINK (see The actual LATEST_LINK name of indexed packages however, is not known, so this is a guessing effort. This generally works quite well, but has some side effects.

E.g. "apache" matches whichever version of Apache is already installed. If no version of Apache is installed, the argument fails. The argument "apache13" however always matches "www/apache13". To match "russian/apache13", "ru-apache13" would be a working argument.



To pkg_upgrade there are two ways to specify packages, explicitely and implicitely. Explicitely named packages are those provided as the update and install arguments.

Implicitely named packages are missing dependencies and those enlisted through the -r , -R and -a parameters. While explicitely named packages are always reinstalled, implicitely named packages have to be outdated or missing, to be enlisted. This can be changed with the -f parameter.


Sometimes package updates cause library changes that break depending packages. Most of these cases can be identfied by running pkg_libchk(1) before and after using pkg_upgrade. The packages that yield new library errors should be explicitely updated with pkg_upgrade.


The purpose of pkg_upgrade is to update, reinstall and install binary packages. This task is divided into six major steps.


The first task is to parse the given parameters. The order of parameters has no influence on the activities performed by pkg_upgrade. However if any packages are specified before the -v flag the INDEX will be updated without the flag (should it appear later) yet having an effect.

The pkg_upgrade script is very strict about the parameters given. Contradicting parameters or unidentified package names and origins result in immediate program termination.


The second step is to create a list of outdated packages. If the -a flag is provided all outdated packages will directly be scheduled for updating instead. Only indexed packages are considered by pkg_upgrade in any way. Every unindexed package will be ignored unless it conflicts with a package to install.

This is the stage when the -f flag takes effect. With this flag every installed package in the index will be assumed outdated.


In the third step the list of scheduled updates gets checked for missing dependencies. If the -r flag is provided not only missing, but also outdated dependencies will be added to the list of packages to update.

Depending on the presence of further -r and -R flags, this process is repeated with the packages newly listed for updating until no new ones show up.

All dependency information is derived solely from the index.


The fourth step ist to sort packages in order of dependency. This is simply done by adding every package to update to a list of sorted packages and putting it into the earliest position possible that is behind all its already present dependencies.

The only way for this to fail is a cyclic dependency. Cyclic dependency checking can be activated with the -p flag. Unless the ports tree used by the build server is broken, cyclic dependencies do not occur, though.


When reaching this stage, downloading has usually already started at this point. Normally a download manager has been dispatched after the index was updated and it has started downloading from the servers listed in PACKAGESITE_MIRRORS.

So during this stage pkg_upgrade waits for finished downloads and checks the package integrity. If a package is broken, a redownload from the server listed in PACKAGESITE is attempted. If the package is still not valid, pkg_upgrade terminates. Informations on the background downloading are available in the DOWNLOAD MANAGER section below.

If the packages are locally available (e.g. over NFS) the fetching (and duplicating) of packages can be avoided by setting the environment variable PACKAGES to the package tree and setting PACKAGESITE to "$PACKAGES/Latest".


The sixth and final step is to backup, update, install, replace all the listed packages and deal with conflicts.

During all this dependency relations from old or replaced packages are inherited by the new ones. The dependency relations of conflicting packages are also preserved. The treating of conflicts can be changed with the -C and -X flags.

Upon installation failure, the backup is restored and the script terminates.

The -b flag can be used to cause the deletion of backups after completion of a package installation or a performed roll-back.


This section details certain aspects of the pkg_upgrade implementation.


The default conflict handling approach of pkg_upgrade is to assume that conflicting packages, which are already installed, provide the required functionality and the installation of the new package is skipped in favour of the conflicting ones.

The approach triggered by the -C flag is to take over the functionality of the conflicting packages. They get deinstalled in favour of the new package, inheriting all the upwards dependency relations.

The -X flag simply causes pkg_upgrade to quit and the user is left to decide what to do about a conflict.


The download manager is a background process that creates a temporary file used as a message queue.

The main process requests downloads from the manager by writing the requests into the queue. There is no communication from the download manager to the main process. So the main process gains informations about the download manager by spying on the queue.

The download manager dispatches downloads for each mirror listed in PACKAGESITE_MIRRORS. These downloads inform the download manager of their success through the queue.

Should a download fail, it is listed for retrying and another attempt is made as soon as there is nothing else left to download. Should this second attempt fail as well, it is the responsibilty of the main process to retrieve the file from the master server specified in PACKAGESITE.

The download manager is explicitely told through the queue to exit. However it also checks at least every 2 seconds whether the main process is still around. If the main process is gone (e.g. was killed or terminated because of an error), the download manager stops all dispatched downloads, deletes the queue and terminates.


For pkg_upgrade to work reliably it is required that neither the package database nor the local INDEX copy are changed during operation. So before the index copy is updated, a lock is acquired from uma(1). It ensures that no other uma(1) using tool is in use and that there is no make activity in the ports tree.

However, that does not keep any one or any program from using the ports tree after the lock has been granted by uma(1).

To prevent this from happening a lock on PKG_DBDIR is acquired. The ports tree locks on PKG_DBDIR during install and deinstall to allow the parallel building of several ports. So this lock will keep the ports from messing until pkg_upgrade is done.

Both locks are kept until the script terminates.


Unless the -l parameter is supplied pkg_upgrade creates a log file with information about performed update, install and replace tasks in "%%VAR%%/log/pkg_upgrade.log". It also contains output on performed conflict handling.

The log file format provides a compromise between machine and human readability.


LOG ::= (LINE + LF)*
LINE ::= TIMESTAMP + " - " + DATE + " - " + TEXT
LF ::= <The line feed character, often called "\n">
TIMESTAMP ::= <The output of "date -u ’+%s’", UTC time in seconds since Jan 1, 1970>
DATE ::= <The output of "date", human readable and locale dependent>
TEXT ::= ("ERROR(" + ERROR + ")" | "DONE") + ": " + MESSAGE
ERROR ::= <A number that can be looked up in the EXIT CODES section>
MESSAGE ::= <A text message about the task performed.>


Output occurs through four different channels. Verbose and regular output occurs on stdout, whereas warnings and errors are reported on stderr. The same applies to the system pkg-tools, used during package installation.

Status or progress messages are written directly to the terminal (tty) and evade regular output redirection. If this causes any problems, they can be turned off using the -c flag.

Completed and failed package installations as well as conflicts are, additionally to the regular output, reported in a log file. Please see the LOGGING section above for more information.


The following command lists all update operations:
pkg_upgrade -an

This command updates all indexed packages:

pkg_upgrade -a

This command reinstalls all indexed packages:

pkg_upgrade -fa

The next command reinstalls "www/firefox3" and updates all packages it depends on:

pkg_upgrade -r firefox3

This command reinstalls "www/firefox3" and all packages it depends on:

pkg_upgrade -fr firefox3

This command reinstalls "devel/glib20" and updates all packages depending on it:

pkg_upgrade -R devel/glib20

The following command reinstalls "devel/glib20" and updates all packages it depends on, all packages depending on it and all other packages that might be affected:

pkg_upgrade -rrRR devel/glib20

Note that adding the -f flag to this would result in an update almost as monumental as -fa .

Now assume "apsfilter" was installed, but it installed the US letter versions of "a2ps" and "psutils", however German A4 paper is used for printing.

The following command can take care of this:

pkg_upgrade -o a2ps-a4 a2ps-letter -o psutils-a4 psutils-letter

The next command does the same for lazy people:

pkg_upgrade -C a2ps-a4 psutils-a4

With the -C flag the listed packages simply replace what they conflict with.


Certain aspects of the pkg_upgrade utility and several of the underlying applications can be configured by setting environment variables.
  This is the time in seconds used by fetch(1) to time out download attempts.

This is provided by uma(1).

  This is the location of the local package repository. Both downloaded and backed up packages are stored there.

If a ports tree is present it defaults to the output of the command "make -V PACKAGES -f /usr/share/mk/". Otherwise it defaults to "%%PORTS%%/packages".

  This is provided by uma(1) and used as the fallback location to download packages from. By setting it to "$PACKAGES/Latest" download activities can be avoided. This can be considered the master server that is used if the mirrors fail.
  This is provided by uma(1) and used by the download manager to download the required packages in background.
  This is used by the system package tools pkg_version(1), pkg_create(1), pkg_delete(1) and pkg_add(1) as well as pkg_upgrade itself to keep the the database of installed packages consistent.

It defaults to "%%VAR%%/db/pkg".

  This is provided by uma(1) and the location of the local INDEX copy maintained by it. This is critical to everything pkg_upgrade does.
  This is used by the system package tools pkg_create(1), and pkg_add(1).

It defaults to "$TMPDIR".

  The location that will be used for temporary files.

It defaults to "%%TMP%%".


pkg_upgrade uses and creates a number of files and directories.
  All downloaded packages are stored in this directory.
  All backed up packages are stored in this directory.
  The index file provided by uma(1) is used to identify packages and collect dependency information from. It basically is the source of all information required by pkg_upgrade.
  Performed package installations and conflict handling are logged in this file.


Every error causes the immediate termination of pkg_upgrade. Errors are numbered in the order of implementation.
  A lock could not be acquired from uma(1) or on PKG_DBDIR. Either the script was not run as root, another process was holding the lock or there was make activity in the ports directory.
  An inprobabal argument was supplied. Either conflicting flags were provided or packages that are not indexed were listed.
  uma(1) failed to provide an up to date copy of the remote index.
  Fetching a required package failed.
  A cyclic dependency was detected. This error can only occur with the -p flag.
  A recent package backup has disappeared. This is highly improbable.
  There was an unknown error when backing up a package.
  There was an error while installing a package. The most likely cause is a lack of disk space.
  The installation was stopped by SIGINT (see signal(3)). This is normally caused by the user pressing CTRL-C.
  The installation was stopped by SIGTERM (see signal(3)).
  The package to install has an unknown package format. The only currently supported format is "1.1".
  A package to install conflicts with another one. This can only occur when the -X flag is set.


The script has been tested on FreeBSD 7.2-PRERELEASE.


bsdadminscripts(1), uma(1), pkg_libchk(1), pkg_version(1), pkg_create(1), pkg_delete(1), pkg_add(1), fetch(1)


The pkg_upgrade script first appeared in the bsdadminscripts-6.0 collection.


Dominic Fandrey <>
Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.