DragonFly On-Line Manual Pages
UMA(1) DragonFly General Commands Manual UMA(1)
NAME
uma - package and ports meta data updating and locking facility
SYNOPSIS
uma [-hv] [pid] [env] [fetch] [extract] [update] [...]
uma [-hv] [pid] [env] fetch [ports] [audit] [ftpindex]
uma [-hv] [pid] [env] extract [ports]
uma [-hv] [pid] [env] update [ports]
uma [-hv] lock [pid]
uma [-hv] unlock [pid]
DESCRIPTION
The uma script is a locking and meta data updating facility for package
management tools. It is not primarily designed for human use, but it
might still be handy occasionally, especially in environments with
several system administrators.
OPTIONS
The following options are available:
-v --verbose
Activates error output. Without this flag errors are only
silently reported with the return value.
-h --help
Prints the available command parameters.
pid A numerical value representing a process id. This can be used to
identify the caller as the lock owner.
env Causes uma to print some environment variables in an executable
format. Some of them are actively set by uma if not present. E.g.
PACKAGESITE.
fetch The fetch command for several targets.
extract
The extract command, only applicable to the ports target.
update The update command, only applicable to the ports target.
audit The audit target, can be used to fetch a new portaudit(1)
database. This only works if "ports-mgmt/portaudit" is installed.
ftpindex
This target can be used with the fetch command to fetch the INDEX
file from the location provided by PACKAGESITE.
ports This target can be used with the fetch, update and extract
commands. It works by calling portsnap(8).
IMPLEMENTATION NOTES
Most of the commands provided by uma exist for the sake of convenience.
The only noteworthy features are the env argument and the locking.
LOCKING
Apart from -h and env all uma commands are only executed if a lock is
held or can be acquired. By providing pid a command can be run for a
different process.
If a lock is explicitely requested via the lock argument, it will be held
until the process specified with pid terminates or the unlock command is
called. If the lock or unlock command is supplied, all others will
silently be ignored. the unlock command has preference over lock.
ENV
The env lists the values of the environment variables ARCH, BRANCH,
PACKAGEROOT, PACKAGEROOT_MIRRORS, PACKAGESITE, PACKAGESITE_MIRRORS,
FTP_TIMEOUT and PKG_INDEX in an executable format. The noteworthy part is
that uma attempts to set reasonable default values for variables that are
not set.
Other programs like pkg_upgrade(1) can use this to acquire a sensible
PACKAGESITE value, if only PACKAGEROOT or even neither one is set in the
environment.
EXAMPLES
The following command downloads the current INDEX from a FreeBSD package
building server:
uma fetch index
The following command can be used by a system administrator to block all
uma using applications:
uma -v lock $$
This creates a lock for the current terminal session. If all system
administrators use this command this is a simple way of telling each
other that system maintainance is being performed and the system should
be left alone.
The lock can be freed by closing the terminal or by running the following
command in the same terminal:
uma -v unlock $$
ENVIRONMENT
Certain aspects of the uma utility and several of the underlying
applications can be configured by setting environment variables.
Alternatively these variables can be set in the configuration file
"%%PREFIX%%/etc/uma.conf".
ARCH The current processor architecture. This is used to construct
PACKAGESITE.
It defaults to the output of "uname -m".
BRANCH The system branch, this is used to construct PACKAGESITE.
The default is system dependent. E.g. "7-stable", "7.2-release",
"8-current".
FTP_TIMEOUT
The time out time in seconds used by fetch(1) when downloading
the index.
PACKAGEROOT
The server to download the INDEX from.
It defaults to "ftp://ftp.freebsd.org".
PACKAGEROOT_MIRRORS
A list of server mirrors either separated by line feeds or
semicolons. Note that semicolons will be converted to line feeds.
Defaults to the primary FreeBSD mirrors.
PACKAGESITE
The location of the "Latest" directory on the server. Also
separated by line feeds or semicolons that get converted to line
feeds.
It defaults to
"$PACKAGEROOT/pub/FreeBSD/ports/$ARCH/packages-$BRANCH/Latest".
PACKAGESITE_MIRRORS
The location of the "Latest" directory on the mirrors.
Defaults to the primary FreeBSD mirrors.
PKG_INDEX
This names the location to store the downloaded INDEX file. It
defaults to "%%VAR%%/db/uma/FTPINDEX".
FILES
uma uses and creates a number of files and directories.
%%PREFIX%%/etc/uma.conf
The configuration file to set environment variables.
%%PREFIX%%/etc/uma.conf.sample
A file with example configurations.
$PKG_INDEX
This is the location of the downloaded INDEX file.
%%VAR%%/run/uma.lock
The location of the file that is locked on.
%%VAR%%/run/uma.pid
The PID file of the lock holding process.
%%VAR%%/run/uma.ident.pid
The file containing the PID of the lock owner.
EXIT CODES
The uma script has both fatal and non-fatal errors. In order to be able
to report several errors at once, the return value is treated as a bit
mask. Because the return value is only a byte this is limited to eight
different possible errors.
The following table lists the possible errors and their bit positions.
ERR_LOCK 0
The first bit represents a locking error. Locking errors are
fatal.
ERR_ARG 1
The second bit is set for unknown arguments. This error is fatal.
ERR_FETCH_PORTS 2
The third bit is set if uma was unable to fetch the ports tree.
ERR_FETCH_VULNDB 3
The fourth bit is set if uma was unable to fetch the
vulnerability database.
ERR_FETCH_INDEX 4
The fifth bit is set if uma was unable to fetch the INDEX file
from a server.
ERR_EXTRACT_PORTS 5
The sixth bit is set if the ports tree could not be extracted.
ERR_UPDATE_PORTS 6
The seventh bit is set if the ports tree could not be updated.
COMPATIBILITY
The script has been tested on FreeBSD 7.2-PRERELEASE.
SEE ALSO
bsdadminscripts(1), pkg_upgrade(1), fetch(1), portsnap(8), portaudit(1),
nc(1)
HISTORY
The original idea, together with a specification draft, originates from
Hannes Hauswedell, originator of the KPorts project and a member of the
BSDForen.de team.
The uma script first appeared in the bsdadminscripts-6.0 collection.
AUTHOR
Dominic Fandrey <kamikaze@bsdforen.de>
DragonFly 6.5-DEVELOPMENT April 27, 2009 DragonFly 6.5-DEVELOPMENT