PKG_UPGRADE(1) BSD General Commands Manual PKG_UPGRADE(1)NAMEpkg_upgrade — binary package management tool
SYNOPSISpkg_upgrade-h
pkg_upgrade-a [-bcCdfFlnpvX] [-o new existing] [update] [install]
pkg_upgrade [-bcCdfFlnpvX] [-r [-r]] [-R [-R]] [-o new existing] [update]
[install]
DESCRIPTION
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).
OPTIONS
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 success‐
ful 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. How‐
ever 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 argu‐
ment 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 bsd.ports.mk). The actual LATEST_LINK name of indexed pack‐
ages 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.
NOTES
EXPLICIT AND IMPLICIT UPDATES
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.
LIBRARY CHANGES
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.
IMPLEMENTATION NOTES
The purpose of pkg_upgrade is to update, reinstall and install binary
packages. This task is divided into six major steps.
PARAMETERS
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. Contra‐
dicting parameters or unidentified package names and origins result in
immediate program termination.
LISTING OUTDATED PACKAGES
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 pack‐
age 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.
DEPENDENCIES
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 out‐
dated 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.
SORTING
The fourth step ist to sort packages in order of dependency. This is sim‐
ply 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.
DOWNLOADING
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 vari‐
able PACKAGES to the package tree and setting PACKAGESITE to "$PACK‐
AGES/Latest".
UPGRADING
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 pack‐
ages 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 termi‐
nates.
The -b flag can be used to cause the deletion of backups after completion
of a package installation or a performed roll-back.
IMPLEMENTATION DETAILS
This section details certain aspects of the pkg_upgrade implementation.
CONFLICTS
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.
DOWNLOAD MANAGER
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 man‐
ager 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 sec‐
ond 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. How‐
ever 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 down‐
loads, deletes the queue and terminates.
LOCKING
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 paral‐
lel 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.
LOGGING
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 con‐
flict handling.
The log file format provides a compromise between machine and human read‐
ability.
LOGFILE PSEUDO BNF
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 depen‐
dent>
TEXT ::= ("ERROR(" + ERROR + ")" | "DONE") + ": " + MESSAGE
ERROR ::= <A number that can be looked up in the EXIT CODES sec‐
tion>
MESSAGE ::= <A text message about the task performed.>
OUTPUT
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.
EXAMPLES
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 ver‐
sions of "a2ps" and "psutils", however German A4 paper is used for print‐
ing.
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.
ENVIRONMENT
Certain aspects of the pkg_upgrade utility and several of the underlying
applications can be configured by setting environment variables.
FTP_TIMEOUT
This is the time in seconds used by fetch(1) to time out download
attempts.
This is provided by uma(1).
PACKAGES
This is the location of the local package repository. Both down‐
loaded and backed up packages are stored there.
If a ports tree is present it defaults to the output of the com‐
mand "make -V PACKAGES -f /usr/share/mk/bsd.port.mk". Otherwise
it defaults to "%%PORTS%%/packages".
PACKAGESITE
This is provided by uma(1) and used as the fallback location to
download packages from. By setting it to "$PACKAGES/Latest" down‐
load activities can be avoided. This can be considered the master
server that is used if the mirrors fail.
PACKAGESITE_MIRRORS
This is provided by uma(1) and used by the download manager to
download the required packages in background.
PKG_DBDIR
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".
PKG_INDEX
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.
PKG_TMPDIR
This is used by the system package tools pkg_create(1), and
pkg_add(1).
It defaults to "$TMPDIR".
TMPDIR The location that will be used for temporary files.
It defaults to "%%TMP%%".
FILESpkg_upgrade uses and creates a number of files and directories.
$PACKAGES/All
All downloaded packages are stored in this directory.
$PACKAGES/pkg_upgrade-backup
All backed up packages are stored in this directory.
$PKG_INDEX
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.
%%VAR%%/log/pkg_upgrade.log
Performed package installations and conflict handling are logged
in this file.
EXIT CODES
Every error causes the immediate termination of pkg_upgrade. Errors are
numbered in the order of implementation.
ERR_LOCK 1
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.
ERR_ARG 2
An inprobabal argument was supplied. Either conflicting flags
were provided or packages that are not indexed were listed.
ERR_INDEX 3
uma(1) failed to provide an up to date copy of the remote index.
ERR_FETCH 4
Fetching a required package failed.
ERR_SORT 5
A cyclic dependency was detected. This error can only occur with
the -p flag.
ERR_BACKUP_MISS 6
A recent package backup has disappeared. This is highly improba‐
ble.
ERR_BACKUP_UNKNOWN 7
There was an unknown error when backing up a package.
ERR_INSTALL 8
There was an error while installing a package. The most likely
cause is a lack of disk space.
ERR_USER 9
The installation was stopped by SIGINT (see signal(3)). This is
normally caused by the user pressing CTRL-C.
ERR_TERM 10
The installation was stopped by SIGTERM (see signal(3)).
ERR_PACKAGE_FORMAT 11
The package to install has an unknown package format. The only
currently supported format is "1.1".
ERR_CONFLICT 12
A package to install conflicts with another one. This can only
occur when the -X flag is set.
COMPATIBILITY
The script has been tested on FreeBSD 7.2-PRERELEASE.
SEE ALSObsdadminscripts(1), uma(1), pkg_libchk(1), pkg_version(1), pkg_create(1),
pkg_delete(1), pkg_add(1), fetch(1)HISTORY
The pkg_upgrade script first appeared in the bsdadminscripts-6.0 collec‐
tion.
AUTHOR
Dominic Fandrey <kamikaze@bsdforen.de>
BSD April 23, 2009 BSD
