Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
UMA(1)                  FreeBSD 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>

FreeBSD 11.0-PRERELEASE         April 27, 2009         FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | IMPLEMENTATION NOTES | EXAMPLES | ENVIRONMENT | FILES | EXIT CODES | COMPATIBILITY | SEE ALSO | HISTORY | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=uma&manpath=FreeBSD+10.3-RELEASE+and+Ports>

home | help