GSP
Quick Navigator

Search Site

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

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  UMA (1)

NAME

uma - package and ports meta data updating and locking facility

CONTENTS

Synopsis
Description
Options
Implementation Notes
     Locking
     Env
Examples
Environment
Files
Exit Codes
Compatibility
See Also
History
Author

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>
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.