|Activates error output. Without this flag errors are only silently reported with the return value.|
|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.|
|The extract command, only applicable to the ports target.|
|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.|
|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).|
Most of the commands provided by uma exist for the sake of convenience. The only noteworthy features are the env argument and the 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.
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.
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 $$
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".
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.
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.
The script has been tested on FreeBSD 7.2-PRERELEASE.
bsdadminscripts(1), pkg_upgrade(1), fetch(1), portsnap(8), portaudit(1), nc(1)
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.
Dominic Fandrey <email@example.com>