.\" $HeadURL$ $LastChangedRevision$
.\"
.pso ade-config --format=man
.so \*[ade_include_prefix]/ade.man
.pso paa-config --format=man
.TH PAA 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
paa - package archive administrator
.br
.ne 5
.SH SYNOPSIS
.B paa
\*[ade_standard_synopsis_component]
[
.B --rcdir=\fIdir\fR
]
.I function
[
.I function-specific-options
]
.I function-specific-arguments
.br
.ne 5
.SH DESCRIPTION
.B Paa
is a tool for performing many administrative functions on package repositories and related
resources. 
For a description of the resources see \[oq]TERMINOLOGY\[cq] below.
For a description of the functions see \[oq]FUNCTIONS\[cq] below. 
.br
.ne 5
.SH TERMINOLOGY
.TP
.B repository
An archive of software packages that is authoritative and
most upstream (and inherently singular in both 
respects). 
Generally, repositories are public (e.g. Debian's
repository at \%http://ftp.debian.org/debian/, Oracle's VirtualBox repository at
\%http://download.virtualbox.org/virtualbox/debian/) but can also be
private (e.g. your own package archive at \%file:///my-debian-packages/).
.TP
.B mirror
A clone 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 kept up to date using a suitable 
.B crontab\fR(1) 
entry.
.TP
.B freeze
A clone of a mirror.
Freezes are deliberately not updated and generally
are implemented as directories with timestamp suffixes
(e.g. debian-201112201042 might contain a copy of a Debian mirror as it
was at 22/12/2011 at 10:42). 
The purpose of freezes to ensure that it
is not necessary to upgrade or downgrade already installed software in
order to satisfy the dependencies of software that may be installed in the
future.
.TP
.B avail
A clone of a freeze for the exclusive use of one specific host.
Generally, avails are implemented using symbolic links.
.PP
For further information on these and related terms see 
\%http://dione.no-ip.org/AlexisWiki/ManagingSoftwareRepositoriesInProductionEnvironments.
.br
.ne 5
.SH CONFIGURATION
.B Paa
is configured using its 
.B initialise
function; see \[oq]FUNCTIONS\[cq] below for details.
.br
.ne 5
.SH OPTIONS
General options are described here; for function-specific options see \[oq]FUNCTIONS\[cq] below.
\*[ade_standard_options_component]
.TP 
.B --rcdir=\fIdir\fR
Sets the location of configuration and repository information to 
.I dir\fR;
the default location is
.B ~/.paa\fR.
.br
.ne 5
.SH FUNCTIONS
Functions related to the 
creation of local repositories and the insertion of packages into them
are Debian-specific; all other functions are distribution-neutral.
.PP
Many of these functions require settings by be made the files under
.B ~/.paa
but 
.B paa
has been designed to help with this: error messages triggered by
missing settings explain which file needs to be edited; comments
in the files explain further. Such configuration really is best
left until such error messages are encountered.
.TP
.B initialise
Creates various files under 
.B ~/.paa
that are needed for all other functions; therefore this
function must be used before any other. 
.TP
.B upstreamrepo \fIrepo-name\fR
Two types of repository may be registered with
.B paa\fR, 
of which the 
first is an upstream repository that will be mirrored locally.
.IP
One argument is required: 
.I repo-name
is the name for the repository (e.g. \[lq]debian\[rq] would be a good name for 
registering Debian's repository, \[lq]virtualbox\[rq] would be a good name 
for registering Oracle's VirtualBox).
.TP
.B createrepo \fIrepo-name local-debian-path\fR
The second type of repository that may be registered with
.B paa
is a local 
.B deb\fR(5)
repository intended for the insertion of arbitrary
packages by the user. Typically, this is either a public
repository for the user's own software or a private repository
containing packages from various upstream repositories (e.g.
google-earth_amd64.deb from Google, skype_i386.deb
from Skype). 
.IP
Two arguments are required:
.I repo-name
is the name for the repository (e.g. \[lq]localpublic\[rq] would be
a good name for a repository of locally written software that
you will share with the community, \[lq]localprivate\[rq] would be a
good name for a repository of arbitrary packages collected together
just for you own machine or local network);
.I local-debian-path
is the local directory under which packages will be archived.
.TP
.B listrepos
Lists previously registered repositories.
.TP
.B insert \fR[\fB --section=\fIsection\fR ] [ \fB--dists=\fIdist\fR[,...] ] \fIrepo-name deb\fR ...
Inserts a package in a previously created repository and records information
pertinent to the generation of Debian repository control files in an sqlite (see
.B sqlite3\fR(1))
database.
.IP
At least two arguments are required:
.I repo-name
is the name for the repository into which the files will be inserted;
.I deb\fR...
are the paths to the 
.B deb\fR(5)
files to be inserted.
.IP
Options allow the overriding (or, in the case that no optional settings
were made in 
.B ~/.paa/\fIrepo-name\fR,
the specification) of the section and/or release(s) for which the the package
will be made available.
.TP
.B control \fIrepo-name\fR
Primarily intended for internal use only; this function is not of general interest.
.TP
.B mirror \fIrepo-name \fB
Enables mirroring by
.B paa\fR's \fBupdatemirrors
function (see below).
.IP
One argument is required:
.I repo-name
is the name for the repository for which mirroring should be enabled.
.\" Actually, 'mirror' is a bit of a no-op.
.TP
.B unmirror \fIrepo-name \fB
Disables mirroring by
.B paa\fR's \fBupdatemirrors
function (see below).
.IP
One argument is required:
.I repo-name
is the name for the repository for which mirroring should be disabled.
.\" Actually, 'unmirror' is a bit of a no-op.
.TP
.B updatemirrors \fR{\fB --all-repos \fR| \fIrepo-name \fR}
Update the mirrors.
.IP
One argument is required:
.I repo-name
is the name for the repository whose mirror is to be updated.
.IP
Options allow the updating of the mirrors of 
.I all
repositories to be enabled, in which case the argument
.I repo-name
is not needed.
.TP
.B listmirrors
Lists previously created mirrors.
.TP
.B freeze \fR{\fB --all-repos \fR| \fIrepo-name \fR}
Freezes the mirror of a repository.
.IP
One argument is required:
.I repo-name
is the name for the repository whose mirror should be frozen.
.IP
Options allow 
.I all
mirrors to be frozen, in which case the argument
.I repo-name
is not needed.
.TP
.B listfreezes
Lists previously created freezes.
.TP
.B avail \fR{\fB --all-hosts \fIrepo-name tag \fR| \fIrepo-name tag host \fR}
Makes a freeze available for a specific host.
.IP
Three arguments are required:
.I repo-name
is the name for the repository whose freeze should be made
available to the host;
.I tag
is the tag of the freeze to make available to the host (use function
.B listfreezes
to see what tags are available);
.I host
is the host.
.IP
Options allow
.I all 
hosts which currently have any freeze of 
.I repo-name
available to them to have the specified freeze made available to them, in which
case the argument
.I host
is not needed.
.TP
.B unavail \fIrepo-name host\fR
Makes a freeze unavailable for a specific host.
.IP
Two arguments are required:
.I repo-name
is the name for the repository whose freeze should be made
available to the host;
.I host
is the host.
.TP
.B listavails
Lists previously created avails.
.TP
.B apache \fIrepo-name host\fR
Generates an 
.B apache2\fR(8)
configuration stanza in order that a host can 
access its avail. 
.IP
Two arguments are required:
.I repo-name
is the name for the repository whose avail should shared via 
.B apache2\fR(8);
.I host
is the host to which it should be shared.
.TP
.B unapache \fIrepo-name host\fR
Removes an 
.B apache2\fR(8)
configuration stanza in order that a host can
no longer access its avail. 
.B Apache2\fR(8)
is not reloaded. 
.TP
.B listapaches
Lists all previously created
.B apache2\fR(8)
shares.
.TP
.B apt \fIrepo-name\fR
Generates
.B /etc/apt/sources.list.d/\fIrepo-name\fB.list 
so that
a host may access packages from its avail.
.B apt-get update
is not run.
.IP
One argument is required:
.I repo-name
is the name for the repository whose avail should accessed.
.TP
.B unapt \fIrepo-name\fR
Removes /etc/apt/sources.list.d/\fIrepo-name\fR.list.
.B apt-get update
is not run.
.br
.ne 5
.SH EXIT STATUS
On success
.B paa
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.TP
.B ~/.paa
Default location for configuration and state information
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.TP 25
.B PAA_RCDIR
Equivalent to use of the
.B --rcdir
option
.br
.ne 5
.SH EXAMPLES
Several roles are involved in mirroring packages, serving them to install 
clients and installing them. For this example we assume two machines are
fulfilling all roles:
.TP 
apple:
server doing all repository administration
.TP 
banana:
client installing packages
.PP
Running the following commands on apple would initialise
.B paa\fR,
register Oracle's VirtualBox repository and create a local repository:
.IP
.nf
.fam C
.B paa initialise
.B paa upstreamrepo virtualbox
.B echo -e \[dq]ALL_SECTIONS=\[rs]\[dq]contrib non-free\[rs]\[dq]\[dq] \[char62]\[char62] ~/.paa/virtualbox
.B paa createrepo localprivate /pub/local/localprivate
.B echo -e \[dq]ALL_SECTIONS=main\[dq] \[char62]\[char62] ~/.paa/localprivate
.B echo -e \[dq]ALL_CPUS=\[rs]\[dq]i386 amd64\[rs]\[dq]\[dq] \[char62]\[char62] ~/.paa/localprivate
.B paa listrepos    #  afterwards check the status 
.fam T
.fi
.br
.PP
(Obviously, one would not ordinarily use 
.B echo\fR(1)
to make these settings, but for the purposes of this example it is clearest.)
.PP
Running the following commands on apple would set the default distribution and sections for any 
package being inserted into the local repository; it would download Skype and
insert it in to local repository:
.IP
.nf
.fam C
.B wget http://dl.google.com/dl/earth/google-earth_amd64.deb
.B paa insert --dists=lenny,squeeze --section=main localprivate google-earth_amd64.deb
.fam T
.fi
.br
.PP
Alternately, default releases and section to be used for insertions can be set and then
the 
.B paa insert
command line is shorter:
.IP
.nf
.fam C
.B echo -e \[dq]DFLT_DISTS=\[rs]\[dq]lenny squeeze\[rs]\[dq]\[dq] \[char62]\[char62] ~/.paa/localprivate
.B echo -e \[dq]DFLT_SECTION=main\[dq] \[char62]\[char62] ~/.paa/localprivate
.B wget http://dl.google.com/dl/earth/google-earth_amd64.deb
.B paa insert localprivate google-earth_amd64.deb
.fam T
.fi
.br
.PP
Running the following commands on apple would facilitate mirroring both repositories and then mirror them:
.IP
.nf
.fam C
.B echo -e \[dq]MIRROR_DIR_PREFIX=/pub/mirrors\[dq] \[char62]\[char62] ~/.paa/general
.B echo -e \[dq]MIRRORER_CMD=\[rs]\[dq]debmirror --ignore-release-gpg --getcontents \[rs]
.B \ \ \ \ --nosource --method=http --host=download.virtualbox.org \[rs]
.B \ \ \ \ --root=/virtualbox/debian --arch=i386,amd64 --dist=lenny,squeeze \[rs]
.B \ \ \ \ --section=contrib,non-free \[rs]\[rs]\[rs]\[dq]\[rs]\[rs]\[rs]$1\[rs]\[rs]\[rs]\[dq]\[rs]\[dq]\[dq] \[rs]
.B \ \ \ \ \[char62]\[char62] ~/.paa/virtualbox
.B paa mirror virtualbox
.B paa mirror localprivate
.B paa updatemirrors --all-repos
.B paa listmirrors    #  afterwards check the status
.fam T
.fi
.br
.PP
(That 
.B paa updatemirrors --all-repos
command would be a good entry in a 
.B crontab\fR(1).)
.PP
Running the following commands on apple would would facilitate freezing both repositories and freeze them:
.IP
.nf
.fam C
.B echo -e \[dq]PAACRT_DIR_PREFIX=/pub/paacrt\[dq] \[char62]\[char62] ~/.paa/general
.B paa freeze --all-repos
.fam T
.fi
.br
.PP
Assuming the freeze tag that that last command displayed was \[oq]20111220\[cq], then 
running the following commands on apple would
avail that freeze for each repository to host \[oq]banana\[cq]:
.IP
.nf
.fam C
.B paa avail virtualbox 20111220 banana
.B paa avail localprivate 20111220 banana
.B paa listavails    #  afterwards check the status
.fam T
.fi
.br
.PP
Running the following commands on apple would make
.B apache2\fR(8)
read additional configuration from /etc/apache2/paa.d and make it serve packages from
the two repositories to the client banana:
.IP
.nf
.fam C
.B mkdir -p /etc/apache2/paa.d
.B echo -e \[dq]Include /etc/apache2/paa.d/\[dq] \[char62] /etc/apache2/conf.d/paa.conf
.B echo -e \[dq]URL=http://apple/paacrt/\[dq] \[char62]\[char62] ~/.paa/general
.B paa apache virtualbox banana
.B paa apache localprivate banana
.B service apache2 reload
.B paa listapaches    #  afterwards check the status
.fam T
.fi
.br
.PP
Assuming
.B paa
was already installed on banana, and that banana is running one of the releases for which
apple has versions of both repositories, then running the following commands there would initialise
.B paa\fR,
tell it about the virtualbox and localprivate avails
and install Skype:
.IP
.nf
.fam C
.B paa initialise
.B echo -e \[dq]URL=http://apple/paacrt/\[dq] \[char62]\[char62] ~/.paa/general
.B paa upstreamrepo virtualbox
.B paa upstreamrepo localprivate    #  not upstream but fibbing easier
.B echo -e \[dq]ALL_SECTIONS=\[rs]\[dq]contrib non-free\[rs]\[dq]\[dq] \[char62]\[char62] ~/.paa/virtualbox
.B echo -e \[dq]ALL_SECTIONS=main\[dq] \[char62]\[char62] ~/.paa/localprivate
.B paa apt virtualbox
.B paa apt localprivate
.B ls /etc/apt/sources.list.d/
.B apt-get update
.B apt-get install skype
.fam T
.fi
.PP
In practice, one often applies the settings made above only on the server 
and then just copies the entire
.B ~/.paa
directory from the server (in this case apple) to the client (in this case banana).
.br
.ne 5
.SH CAVEATS
The 
.B initialise
function has an English spelling because the author is English.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B paa\fR.
.br
.ne 5
.SH SEE ALSO
apache2(8), apt-get(8), crontab(1), deb(5), debmirror(1), echo(1), mkdir(1), paa-config(1), service(8), sqlite3(1), wget(1),
.br
\%http://dione.no-ip.org/AlexisWiki/ManagingSoftwareRepositoriesInProductionEnvironments
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1995-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
\*[ade_standard_copyright_component]