PAA(1) General Commands Manual PAA(1)
NAME
paa - package archive administrator
SYNOPSIS
paa [ -V | --version ] [ -v | --verbose | -d level | --debug=level ] [
-h | --help ] [ -p | --paths ] [ -n | --simulate ] [ --rcdir=dir ] [
--force ] function function-specific-arguments
DESCRIPTION
Paa is a tool for performing many administrative functions on package
repositories and related resources.
For a description of the resources see 'RESOURCES' below. For a de-
scription of the functions see 'FUNCTIONS' below. For a description of
the configuration directives used with the editrepo function see 'CON-
FIGURATION DIRECTIVES' below.
RESOURCES
repository
An authoritative archive of software packages. Generally,
repositories are public (e.g. Debian's repository at
http://ftp.debian.org/debian/, Fedora's EPEL repository at
https://fedoraproject.org/wiki/EPEL) but can also be private
(e.g. your own package archive at file:///my-debian-packages/).
Repositories are updated when developers insert packages into
them.
mirror A copy of a repository (e.g. Debian's official UK mirror at
http://ftp.uk.debian.org/debian/, your own mirror of Debian).
Generally, mirrors are updated nightly using a suitable
crontab(5) entry.
freeze A copy of a mirror (e.g. debian.201112201042 might contain a
copy of a Debian mirror as it was at 22 December 2011 at 10:42
a.m.). Freezes are deliberately not updated after they have
been created. Generally, they are implemented as directories
with timestamp suffixes.
The purpose of freezes is to ensure that, in the future, it will
not become necessary to upgrade or downgrade already installed
software in order to satisfy the dependencies of software that
is about to be installed.
indirect
A copy of a freeze for the exclusive use of one specific host
(e.g. debian.coconut might be a copy of a Debian freeze for use
by the host coconut). Paa implements indirects using symbolic
links.
share The sharing of a indirect via http, as represented by an Apache
config stanza (see apache2(8)).
access The accessing of a share by a client, as represented by a file
in /etc/apt/sources.list.d or /etc/yum.repos.d (depending on the
OS).
CONFIGURATION
See the 'CONFIGURATION DIRECTIVES' section below and the editrepo func-
tion in 'FUNCTIONS' section below.
OPTIONS
-d level, --debug=level Determines how verbose this program will be.
The message types displayed for the different
values of level are as follows: 0 displays no
messages; 1 displays only errors, 2 displays
errors and warnings; 3 displays errors, warn-
ings and informational messages; higher values
display errors, warnings, informational mes-
sages and various messages intended for debug-
ging. The default is 2.
-h, --help Displays a brief usage message.
-p, --paths Lists the compiled-in paths of various files
and directories that this program uses. -n,
--simulate Some external commands that this
program runs may be displayed rather than ac-
tually executed. BEWARE: different programs
implement different levels of simulation; so
this option may work perfectly; on the other
hand it may do nothing at all!
-v, --verbose Equivalent to -d 3.
-V, --version Prints the program's version number and exits.
--force Used in conjunction with one of unrepo, unmir-
ror, unfreeze, unindirect, unshare or unac-
cess, this option forces the deletion of mul-
tiple resources.
--rcdir=dir Sets the location of configuration and reposi-
tory information to dir; the default is
~/.paa.
FUNCTIONS
repo repo-name pkg-type repo-type is-distro
Registers a repository with paa. repo-name is the name of the
repository (e.g. 'debian' would be a good name for registering
Debian's repository, 'epel' would be a good name for registering
Fedora's EPEL repository, 'localpublic' would be a good name for
registering a repository for your own packages. pkg-type is ei-
ther deb or rpm. repo-type is one of owned, mirrored or ac-
cessed; owned means that you will be inserting packages into it
and maybe mirroring it; mirrored means that someone else will be
inserting packages into it and that you will only be mirroring
it; accessed means that someone else will be mirroring it and
that you only be accessing it, or that the repository is not
mirrored at all and you will be accessing the repository di-
rectly. is-distro is either true or false depending whether the
repository is a distribution (like 'debian' or 'centos') or
other software (like 'virtualbox' or 'epel').
listrepos [ pattern ... ]
Lists previously registered repositories with any parameters
matching pattern. If pattern is not provided then all reposito-
ries will be listed.
editrepo repo-name
The repo function specifies only limited information about a
repository but more is required. This information is provided
in a configuration file that this function edits. (Actually,
these files are exported on-the-fly from an sqlite(1) database
and after editing the files are re-imported and deleted.) The
configuration file is a POSIX shell script (see bash(1)) calling
directives to register different properties of the repository.
Paa pre-populates the configuration file with directives that
are appropriate for the type of repository that was registered,
so editing the configuration is not hard. For a description of
the these directives see 'CONFIGURATION DIRECTIVES' below. A
repository will be marked 'pending' until all required direc-
tives have been specified, at which point it will be marked
'available'.
unrepo repo-name
Deregisters a repository. repo-name is the name of the reposi-
tory to deregister. Repositories that have been mirrored may
not be deregistered until the mirrors have been deleted (see un-
mirror below).
host host [ pkg-type distro release port ]
Registers the specified host as having the specified distribu-
tion, release and port (CPU architecture). If host is THIS-HOST
then the system where the command is run will be interrogated to
get the values of pkg-type, distro, release and port and they
should not be specified on the command line, otherwise they must
be specified on the command line.
listhosts [ pattern ... ]
Lists previously registered hosts with any parameters matching
pattern. If pattern is not provided then all hosts will be
listed.
unhost host
Deregisters the specified host. If host is ALL-HOSTS then all
hosts will be deleted. Hosts that have been indirected or ac-
cessed may not be deleted until the indirects and accesses have
been deleted (see unindirect and unaccess below).
mirror repo-name
Mirrors the specified repository. repo-name is the name of the
repository to mirror. If repo-name is ALL-REPOS then all reposi-
tories are mirrored.
listmirrors [ pattern ... ]
Lists previously created mirrors with any parameters matching
pattern. If pattern is not provided then all mirrors will be
listed.
unmirror repo-name
Deletes the specified mirror. repo-name is the name of the
repository to delete. If repo-name is ALL-REPOS then all mirrors
will be deleted. Mirrors that have been frozen may not be
deleted until the freezes have been deleted (see unfreeze be-
low).
freeze repo-name
Freezes the mirror of the specified repository. Freezes are as-
signed a freeze ID, which other functions will need to use to
identify the freeze. repo-name is the name of the repository
whose mirror should be frozen. If repo-name is ALL-REPOS then
all mirrors will be frozen.
listfreezes [ pattern ... ]
Lists previously created freezes with any parameters matching
pattern. If pattern is not provided then all freezes will be
listed.
unfreeze repo-name freeze-id
Deletes the specified freeze. repo-name and freeze-id identify
the freeze to be deleted. If repo-name is ALL-REPOS then all
freezes of mirrors whose freeze ID matches freeze-id will be
deleted. If freeze-id is ALL-FREEZES then all freezes of mirrors
whose repository name matches repo-name will be deleted.
Freezes that have been indirected may not be deleted until the
indirects have been deleted (see unindirect below).
indirect repo-name host freeze-id
Direct a client's request to access a repository to the speci-
fied freeze. repo-name is the name for the repository whose
freeze should be made available to the host; host is the
client's hostname; freeze-id is the freeze id of the freeze to
make available to the host. If repo-name is ALL-REPOS then all
repositories will be indirected. If freeze-id is NEWEST-FREEZE
then only the newest freeze of each matching repository will be
indirected.
listindirects [ pattern ... ]
Lists previously created indirects with any parameters matching
pattern. If pattern is not provided then all indirects will be
listed.
unindirect repo-name host-name
Deletes the specified indirect. repo-name and host-name iden-
tify the indirect to be deleted. If repo-name is ALL-REPOS then
all indirects whose repository name matches repo-name will be
deleted. If host-name is ALL-HOSTS then all indirects whose
hostname matches host-name will be deleted. Indirects that have
been shared may not be deleted until the shares have been
deleted (see unshare below).
share repo-name host
Generate an apache2(8) configuration stanza in order to make an
indirect accessible. repo-name is the name for the repository
whose indirect should be shared; host is the host to which it
should be shared.
listshares [ pattern ... ]
Lists previously created shares with any parameters matching
pattern. If pattern is not provided then all shares will be
listed.
unshare repo-name host
Deletes an apache2(8) configuration stanza in order to make an
indirect inaccessible.
access repo-name
On Debian-based hosts, generate /etc/apt/sources.list.d/repo-
name.list so that a host may retrieve packages from its indi-
rect. On Redhat-based hosts, generate /etc/yum.repos.d/repo-
name.repo so that a host may retrieve packages from its indi-
rect. repo-name is the name for the repository whose indirect
should be accessed.
listaccesses [ pattern ... ]
Lists previously created accesses with any parameters matching
pattern. If pattern is not provided then all accesses will be
listed.
unaccess repo-name
Deletes repository access configuration files. repo-name is the
name for the repository whose indirect should be deleted.
insert repo-name release [ section ] file ...
Inserts the specified packages into the specified section of the
specified release of the specified repository. This does not add
entries to any control files, so the repository is considered to
be in an incomplete state between using this function and using
the control function. If release is ALL-RELEASES then the pack-
age is inserted into all releases that the repository repo-name
contains.
control repo-name
Generates control files for the specified repository.
upgrade
The database schema (i.e. the database layout) used by paa may
change when there is a new release of paa. For safely reasons,
paa will refuse to start if there is a mismatch between the
database schema version it is using and the database schema ver-
sion it finds in the state information files (see FILES below).
In this case, the state information files need to be upgraded in
order that they can support the newer version of paa. This
function understands old and new database schemas and can up-
grade the state information files accordingly.
listobsolete
Lists obsolete resources (e.g. mirrors without freezes, freezes
without indirects).
CONFIGURATION DIRECTIVES
Configuration files are POSIX shell scripts. This eases repeated calls
to the same directive (e.g. to register that a repository is compatible
with several distributions).
compat release pkg-type distro-name distro-release
(only required for repositories that are not distributions) This
specifies with which distributions the repository is compatible.
distro distro-name
(only required for repositories that are distributions) This
specifies the name of the distribution.
label repo-label
(only required for owned deb repositories) When required, this
is passed to apt-ftparchive(1).
layout release layout
(only required for rpm repositories) This describes the internal
layout of the specified release of the specified repository;
specifically the path from the last release- and architecture-
independent directory to the directory above the repoview direc-
tory layout is therefore <release>/Everything/<arch>/os.
layout may contains <repo>, <host>, <release>, <freeze>, or
<arch>, which will respectively be replaced with the repository
name, hostname, release, freeze ID and architecture when re-
quired.
mirror_cmd "mirror-cmd"
(only required for repositories that are mirrored) This speci-
fies the command to mirror a repository. Generally, this will be
a call to either debmirror(1) or rpmmirror(1). mirror-cmd may
contain various placeholders; see the paragraph above dealing
with the layout directive above for details.
mirror_dir directory
(only required for repositories that are mirrored) This speci-
fies the directory into which a repository will be mirrored.
directory may contain various placeholders; see the paragraph
above dealing with the layout directive above for details.
freeze_dir directory
(only required for repositories that are mirrored) This speci-
fies the directory into which a mirror will be frozen. direc-
tory may contain various placeholders; see the paragraph above
dealing with the layout directive above for details.
indirect_dir directory
(only required for repositories that are mirrored) This speci-
fies the directory into which a freeze will be indirected. di-
rectory may contain various placeholders; see the paragraph
above dealing with the layout directive above for details.
origin origin
(only required for owned deb repositories) When required, this
is passed to apt-ftparchive(1).
path directory
(only required for repositories that are owned) directory may
contain various placeholders; see the paragraph above dealing
with the layout directive above for details.
port release port
Specifies the ports (CPU architectures) that the release con-
tains; how these are written is OS-specific (e.g. Debian call
64-bit x86 'amd64', whereas Fedora calls the same thing
'x86_64').
release release
Specifies a release that the repository contains; if the reposi-
tory contains multiple releases then call this directive multi-
ple times.
section release section
(only required for deb repositories) Specifies the sections that
the release contains.
signer signer
(only required for owned deb repositories) When required, this
is passed to apt-ftparchive(1).
url url
(only required for repositories that are mirrored or accessed)
Specifies the URL of a repository being shared or of a reposi-
tory being accessed.
EXIT STATUS
On success paa returns zero. On failure it returns non-zero and dis-
plays a diagnostic message.
FILES
~/.paa Default directory for configuration and state
information.
ENVIRONMENT VARIABLES
PAA_RCDIR Equivalent to use of the --rcdir option
EXAMPLES
Several human roles are involved in making packages, mirroring them,
serving them to clients and installing them on those clients. For this
example we assume the following roles:
+o a developer develops packages on the development host 'apple'
and inserts them into a repository on the same machine (or an
NFS server he has mounted on his development host)
+o a repositories administrator manages the mirrors, freezes and
indirects on the host 'banana'
+o a system administrator installs packages on a host 'coconut'
So, to start this example session, on apple, the package developer reg-
isters a new repository:
developer@apple$ paa repo localpublic deb owned false
The package developer then needs to provide more information about the
repository (e.g. what it contains and which it is compatible with),
which he does by running:
developer@apple$ paa editrepo localpublic
This launches his favourite editor, provides an example configuration
file that he must tune. Let us suppose that the configuration he pro-
vides is the following:
#####################################################################
#
# Internal variables (defined for convenience and referenced only
# from within this file)
#
#####################################################################
_RELEASES="lenny squeeze wheezy"
_PORTS="i386 amd64"
_SECTIONS="main"
#####################################################################
#
# Repository contents (defines what is in or may be inserted into
# this repo)
#
#####################################################################
for _RELEASE in $_RELEASES; do
release $_RELEASE
for _PORT in $_PORTS; do
port $_RELEASE $_PORT
done
for _SECTION in $_SECTIONS; do
section $_RELEASE $_SECTION
done
done
#####################################################################
#
# Compatibility (defines on which distros each release in this
# non-distro repo may be installed)
#
#####################################################################
for _RELEASE in $_RELEASES; do
compat $_RELEASE deb debian $_RELEASE
done
compat squeeze deb ubuntu \*
#####################################################################
#
# Miscellaneous settings
#
#####################################################################
# Path to the repository (not the mirror of the repository)
path /pub/computing/software/local/debian/localpublic-deb
# Debian repositories need to know a few other things.
origin "Joe Bloggs"
label "Joe Bloggs"
signer "jbloggs"
At this point the developer may insert packages in to the repository
and generate the necessary control files:
developer@apple$ paa insert localpublic lenny,squeeze,wheezy main \
mjpg-streamer_r94-1_i386.deb
developer@apple$ paa insert localpublic lenny,squeeze,wheezy main \
googleearth_5.0.11733.9347+0.5.4-1_i386.deb
developer@apple$ paa control localpublic
Let us suppose that the system administrators wish to install hosts,
configuring them to access the local mirrors of the Debian repository
and the 'localpublic' repository. On host 'banana', the repository ad-
ministrator first registers the repositories:
repoadmin@banana$ paa repo debian deb mirrored true
repoadmin@banana$ paa repo localpublic deb mirrored false
(The true and false refer to the fact that Debian is a distribution,
whereas localpublic is not.)
Just as the developer did, he needs to provide more information about
the repositories, which he does by running:
repoadmin@banana$ paa editrepo ALL-REPOS
For the 'debian' repository he provides the following configuration:
#####################################################################
#
# Internal variables (defined for convenience and referenced only
# from within this file)
#
#####################################################################
_RELEASES="squeeze"
_PORTS="i386 amd64"
_SECTIONS="main contrib non-free main/debian-installer"
#####################################################################
#
# Repository contents (defines what is in or may be inserted into
# this repo)
#
#####################################################################
for _RELEASE in $_RELEASES; do
release $_RELEASE
for _PORT in $_PORTS; do
port $_RELEASE $_PORT
done
for _SECTION in $_SECTIONS; do
section $_RELEASE $_SECTION
done
done
#####################################################################
#
# Miscellaneous settings
#
#####################################################################
# URL for the repo
url "http://install.pasta.net/<;repo>.<host>/"
# The path to your mirror
mirror_dir "/pub/mirrors/<host>"
# The path to your freezes
freeze_dir "/pub/freezes/<repo>.<freeze>"
# The path to your indirects
indirect_dir "/pub/indirects/<repo>.<host>"
# The command to update the mirror in the current directory.
mirror_cmd "debmirror \
--rsync-options=\"-aIL --partial --no-motd\" \
--ignore-release-gpg --getcontents --nosource \
--method=rsync --host=ftp2.de.debian.org --root=:debian \
--arch=${_PORTS// /,} --dist=${_RELEASES// /,} \
--section=${_SECTIONS// /,} --di-dist=dists --di-arch=arches ."
# Which distribution is this repo for?
distro debian
For the 'localpublic' repository he provides the following configura-
tion, which is similar to the configuration that the developer used,
but omits signer, label, origin and path, and includes url, mirror_dir,
freeze_dir, indirect_dir and mirror_cmd:
#####################################################################
#
# Internal variables (defined for convenience and referenced only
# from within this file)
#
#####################################################################
_RELEASES="lenny squeeze wheezy"
_PORTS="i386 amd64"
_SECTIONS="main"
#####################################################################
#
# Repository contents (defines what is in or may be inserted into
# this repo)
#
#####################################################################
for _RELEASE in $_RELEASES; do
release $_RELEASE
for _PORT in $_PORTS; do
port $_RELEASE $_PORT
done
for _SECTION in $_SECTIONS; do
section $_RELEASE $_SECTION
done
done
#####################################################################
#
# Compatibility (defines on which distros each release in this
# non-distro repo may be installed)
#
#####################################################################
for _RELEASE in $_RELEASES; do
compat $_RELEASE deb debian $_RELEASE
done
compat squeeze deb ubuntu \*
#####################################################################
#
# Miscellaneous settings
#
#####################################################################
# URL for the repo
url "http://install.pasta.net/<;repo>.<host>/"
# The path to your mirror
mirror_dir "/pub/mirrors/<repo>"
# The path to your freezes
freeze_dir "/pub/freezes/<repo>.<freeze>"
# The path to your indirects
indirect_dir "/pub/indirects/<repo>.<host>"
Then he mirrors these repositories and immediately freezes the mirrors:
repoadmin@banana$ paa mirror ALL-REPOS
repoadmin@banana$ paa freeze ALL-REPOS
Paa is intelligent enough to share with a client only those reposito-
ries that are appropriate, providing it is told a little about the
client. To do this the repository administrator runs:
repoadmin@banana$ paa host coconut deb debian squeeze amd64
meaning that coconut is declared as have a deb-based OS, specifically
Debian, it is running the squeeze release of Debian and more specifi-
cally the amd64 port.
Directing incoming requests for packages to the appropriate freezes is
done by running:
repoadmin@banana$ paa indirect ALL-REPOS coconut NEWEST-FREEZE
repoadmin@banana$ paa share ALL-REPOS coconut
The system administrator on coconut tells paa about his host; he can do
this using the same paa host command that the repository administrator
just used, or can ask paa to work it out for itself by running:
root@coconut# paa host THIS-HOST
He then registers the two repositories he wants to access by running:
root@coconut# paa repo debian deb accessed true
root@coconut# paa repo localpublic deb accessed false
and, just as the developer and repositories administrator did, he needs
to provide more information about the repositories, which he does by
running:
root@coconut# paa editrepo ALL-REPOS
The configurations he provides are the same as above, except that some
directives need to be deleted (because he intends to do less with the
repositories than the developer or repositories administrator did), but
paa will warn him which directives need to be deleted, and will not
mark the repository as 'available' until all errors have been resolved.
Then he can configure coconut's package management system (apt(8) in
this example, because coconut is a Debian system) by running:
root@coconut# paa access ALL-REPOS
And finally he can install software:
root@coconut# apt-get update
root@coconut# apt-get install mjpg-streamer_r94-1_i386.deb
CAVEATS
Currently, paa's share and unshare functions only support apache2(8).
STANDARDS
This manual page documents version 4.0.1 of paa.
SEE ALSO
apache2(8), apt-ftparchive(1), apt-get(8), bash(1), crontab(5), deb(5),
debmirror(1), rpmmirror(1), sqlite(1), rpm(8), yum(8)
AUTHOR
Alexis Huxley <alexishuxley@gmail.com>
COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1995-2024 Alexis Huxley
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MER-
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.
27 Aug 2024 PAA(1)
