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	sev-
     eral 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) data-
	     base. 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	com-
	     mands. 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 dif-
     ferent 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 applica-
     tions can be configured by	setting	environment variables. Alternatively
     these variables can be set	in the configuration file "%%PRE-
     FIX%%/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	semi-
	     colons. 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	sepa-
	     rated by line feeds or semicolons that get	converted to line
	     feeds.

	     It	defaults to "$PACKAGEROOT/pub/FreeBSD/ports/$ARCH/pack-
	     ages-$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 vulnerabil-
	     ity 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	10.3			April 27, 2009			  FreeBSD 10.3

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