.\" $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
]
[
.B --force
]
.I function
.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. 
For a description of the configuration directives used with the 
.B editrepo
function see \[oq]CONFIGURATION DIRECTIVES\[cq] below. 
.br
.ne 5
.SH TERMINOLOGY
.TP
.B repository
An authoritative archive of software packages.
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 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 
.B crontab\fR(5)
entry.
.TP
.B freeze
A copy of a mirror.
Freezes are deliberately not updated after they have been created. Generally,
they are implemented as directories with timestamp suffixes
(e.g. debian.201112201042 might contain a copy of a Debian mirror as it
was at 22 December 2011 at 10:42 a.m.). 
The purpose of freezes to ensure that, in the future,
it is not necessary to upgrade or downgrade already installed software in
order to satisfy the dependencies of software that is about to be installed.
.TP
.B indirect
A copy of a freeze for the exclusive use of one specific host.
Generally, indirects are implemented using symbolic links.
.TP
.B share
The sharing of a indirect via http.
.TP
.B access
The accessing of a share by an install client.
.PP
For further information on these and related terms see 
\%http://dione.no-ip.org/AlexisWiki/ManagingSoftwareRepositoriesInProductionEnvironments.
.br
.ne 5
.SH CONFIGURATION
No configuration is required before the use of the various functions.
.br
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP
.B --force
Used in conjunction with one of 
.B unrepo\fR, 
.B unmirror\fR, 
.B unfreeze\fR, 
.B unindirect\fR, 
.B unshare\fR
or
.B unaccess\fR,
forces the deletion of multiple resources.
.TP 
.B --rcdir=\fIdir\fR
Sets the location of configuration and repository information to 
.I dir\fR;
the default is
.B ~/.paa\fR.
.br
.ne 5
.SH FUNCTIONS
.TP
.B repo \fIrepo-name pkg-type repo-type is-distro
Registers a repository with
.B paa\fR. 
.I repo-name
is the name of the repository (e.g. \[oq]debian\[cq] would be a good name for 
registering Debian's repository, \[oq]virtualbox\[cq] would be a good name 
for registering Oracle's VirtualBox repository, \[oq]localpublic\[cq] would be a good name for
registering a repository for your own packages.
.I pkg-type
is either
.B deb
or
.B rpm.
.I repo-type
is one of
.B owned\fR, \fBmirrored\fR or \fBaccessed;
.B owned
means that you will be inserting packages into it;
.B mirrored
means that someone else will be inserting packages into it and that you will only be mirroring it;
.B 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 directly.
.I is-distro
is either
.B true
or
.B false
depending whether the repository is a distribution (like \[oq]debian\[cq] or \[oq]centos\[cq]) 
or other software (like \[oq]virtualbox\[cq] or \[oq]epel\[cq]).
.TP
.B listrepos \fR[ \fIpattern\fR ... ]
Lists previously registered repositories with any parameters matching
.I pattern\fR. 
If
.I pattern
is not provided then all repositories will be listed.
.TP
.B editrepo \fIrepo-name
The 
.B repo
function provides to 
.B paa 
only limited information about a repository; 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 
.B sqlite\fR(1)
database and after editing are reimported and deleted.)
The configuration file is a POSIX shell script (see
.B bash\fR(1))
calling directives to register different properties of the repository. 
.B Paa
prepopulates 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 \[oq]CONFIGURATION DIRECTIVES\[cq] below. 
A repository will be marked \[oq]pending\[cq] until all required directives have been 
specified.
.TP
.B unrepo \fIrepo-name
Deregisters a repository. 
Repositories that have been mirrored may not be deleted until the mirrors have been 
deleted (see 
.B unmirror
below).
.TP
.B mirror \fIrepo-name\fR
Mirrors the specified repository.
.I repo-name
is the name of the repository to mirror. If 
.I repo-name
is
.B ALL-REPOS
then all properly defined repositories are mirrored; a \[oq]properly defined\[cq] 
repository is one that the
.B listrepos
function shows as \[oq]available\[cq].
.TP
.B listmirrors \fR[ \fIpattern\fR ... ]
Lists previously created mirrors with any parameters matching
.I pattern\fR. 
If
.I pattern
is not provided then all mirrors will be listed.
.TP
.B unmirror \fIrepo-name\fB
Removes the specified mirror.
.I repo-name
is the name of the repository to remove. If
.I repo-name
is
.B ALL-REPOS
then all properly defined mirrors will be removed.
Mirrors that have been frozen may not be deleted until the freezes have been 
deleted (see
.B unfreeze
below).
.TP
.B freeze \fIrepo-name
Freezes the mirror of the specified repository. Freezes are
assigned a freeze ID, which other functions will need to 
identify the freeze.
.I repo-name
is the name of the repository whose mirror should be frozen. If
.I repo-name
is
.B ALL-REPOS
then all mirrors of properly defined repositories will be frozen.
.TP
.B listfreezes \fR[ \fIpattern\fR ... ]
Lists previously created freezes with any parameters matching
.I pattern\fR.
If
.I pattern
is not provided then all freezes will be listed.
.TP
.B unfreeze \fIrepo-name freeze-id
Removes the specified freeze.
.I repo-name
and
.I freeze-id
identify the freeze to be removed. If
.I repo-name
is
.B ALL-REPOS
then all freezes of all properly defined mirrors whose freeze ID matches
.I freeze-id
will be removed. If
.I freeze-id
is
.B ALL-FREEZES
then all freezes of all properly definied mirrors whose repository name matches
.I repo-id
will be removed.
Freezes that have been indirected may not be deleted until the indirects have been 
deleted (see
.B undirect
below).
.TP
.B indirect \fIrepo-name host freeze-id
Direct a client's request to access a repository to the specified freeze.
.I repo-name
is the name for the repository whose freeze should be made
available to the host;
.I host
is the client's hostname;
.I freeze-id
is the freeze id of the freeze to make available to the host.
If
.I repo-name
is 
.B ALL-REPOS
then ...
If 
.I freeze-id
is 
.B NEWEST-FREEZE
then ...
.TP
.B listindirects \fR[ \fIpattern\fR ... ]
Lists previously created indirects with any parameters matching
.I pattern\fR. 
If
.I pattern
is not provided then all indirects will be listed.
.TP
.B unindirect \fIrepo-name host-name
Removes the specified indirects
.I repo-name
and
.I host-name
identify the indirect to be removed. If
.I repo-name
is
.B ALL-REPOS
then all indirects whose repository name matches
.I repo-name
will be removed. If
.I host-name
is
.B ALL-HOSTS
then all indirects whose hostname matches
.I host-name
will be removed.
Directs that have been shared may not be deleted until the shares have been 
deleted (see
.TP
.B share \fIrepo-name host\fR
Generate an 
.B apache2\fR(8)
configuration stanza in order that a host can 
access its indirect. 
.I repo-name
is the name for the repository whose indirect should be shared,
.I host
is the host to which it should be shared.
.TP
.B listshares \fR[ \fIpattern\fR ... ]
Lists previously created shares with any parameters matching
.I pattern\fR. 
If
.I pattern
is not provided then all shares will be listed.
.TP
.B unshare \fIrepo-name host\fR
Removes an 
.B apache2\fR(8)
configuration stanza in order that a host can
no longer access its indirect. 
.TP
.B access \fIrepo-name\fR
On Debian-based hosts, generate
.B /etc/apt/sources.list.d/\fIrepo-name\fB.list 
so that
a host may retrieve packages from its indirect.
.B apt-get update
is not run.
On Redhat-based hosts, generate
.B /etc/yum.repos.d/\fIrepo-name\fR.repo
so that
a host may retrieve packages from its indirect.
.B yum clean all
is not run.
.I repo-name
is the name for the repository whose avail should accessed.
.TP
.B listaccesses  \fR[ \fIpattern\fR ... ]
Lists previously created accesses with any parameters matching
.I pattern\fR. 
If
.I pattern
is not provided then all accesses will be listed.
.TP
.B unaccess \fIrepo-name
Remove repository access configuration files.
.I repo-name
is the name for the repository whose avail should accessed.
.br
.ne 5
.SH 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).
.TP
.B cidr \fIcidr
(only required for repositories that are owned or mirrored)
.TP
.B compat \fIrelease pkg-type distro-name distro-release
(only required for repositories that are not distributions)
.TP
.B distro \fIdistro-name
(only required for repositories that are distributions)
.TP
.B label \fIrepo-label
(only required for owned deb repositories)
.B layout \fIlayout
(only required for rpm repositories)
.TP
.B mirror_cmd \[dq]mirror-cmd\[dq]
(only required for repositories that are owned or mirrored)
.TP
.B mirror_dir \fIdirectory
(only required for repositories that are owned or mirrored)
.TP
.B origin \fIorigin
(only required for owned deb repositories)
.TP
.B freeze_dir \fIdirectory
(only required for repositories that are owned or mirrored)
.TP
.B indirect_dir \fIdirectory
(only required for repositories that are owned or mirrored)
.TP
.B path \fIdirectory
(only required for repositories that are owned)
.TP
.B port \fIport
blah
.TP
.B release \fIrelease
blah
.TP
.B section \fIsection
(only required for deb repositories)
.TP
.B signer \fIsigner
(only required for owned deb repositories)
.TP
.B url \fIurl
(only required for repositories that are owned or mirrored)
.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 directory 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 making packages, mirroring them, serving them to install clients and
installing them.
For this example we assume the following roles:
.TP 
The developer develops packages in the development host \[oq]apple\[cq] and inserts them into a repository in the same machine (or an NFS server he has mounted on his development host)
.TP 
The repositories administrator manages the mirrors, freezes and indirects on the host \[oq]banana\[cq]
.TP
A system administrator installs packages on a host \[oq]coconut\[cq]
.PP
On apple, the package developer registers the new repository:
.IP
.nf
.fam C
developer@apple$ \fBpaa repo localpublic deb owned false\fR
.fam T
.fi
.br
.PP
The package developer then needs to provide more information about
the repository (e.g. what it contains and which distros it is compatible 
with), which he does by running:
.IP
.nf
.fam C
developer@apple$ \fBpaa editrepo localpublic\fR
.fam T
.fi
.br
.PP
This launches his favourite editor, provides an example configuration
file that he must tune.
The configuration he provides is this:
.IP
.nf
.fam C
.B #####################################################################
.B #
.B #\ \ Internal variables (defined for convenience and referenced only 
.B #\ \ from within this file)
.B #
.B #####################################################################
.B \ 
.B _RELEASES=\[dq]lenny squeeze wheezy UNRELEASED\[dq]
.B _PORTS=\[dq]i386 amd64\[dq]
.B _SECTIONS=\[dq]main\[dq]
.B \ 
.B #####################################################################
.B #
.B #\ \ Repository contents (defines what is in or may be inserted into 
.B #\ \ this repo)
.B #
.B #####################################################################
.B \ 
.B #\ \ The set of *all* releases, ports and sections this repository 
.B #\ \ will contain.
.B for _RELEASE in $_RELEASES; do
.B \ \ \ \ release $_RELEASE
.B \ \ \ \ for _PORT in $_PORTS; do
.B \ \ \ \ \ \ \ \ port $_RELEASE $_PORT
.B \ \ \ \ done
.B \ \ \ \ for _SECTION in $_SECTIONS; do
.B \ \ \ \ \ \ \ \ section $_RELEASE $_SECTION
.B \ \ \ \ done
.B done
.B \ 
.B #####################################################################
.B #
.B #\ \ Compatibility (defines on which distros each release in this 
.B #\ \ non-distro repo may be installed)
.B #
.B #####################################################################
.B \ 
.B #\ \ Each release in this repository is compatible with which distros?
.B for _RELEASE in $_RELEASES; do
.B \ \ \ \ compat $_RELEASE deb debian $_RELEASE
.B done
.B compat squeeze deb ubuntu \[rs]*
.B \ 
.B #####################################################################
.B #
.B #\ \ Misc settings
.B #
.B #####################################################################
.B \ 
.B #\ \ URL for the repo
.B url \[dq]http://install.pasta.net/<repo>.<host>/\[dq]
.B #\ \ The path to your mirrors
.B mirror_dir \[dq]/pub/mirrors/<repo>\[dq]
.B #\ \ The path to the paacrt work area
.B freeze_dir \[dq]/pub/freezes/<repo>.<freeze>\[dq]
.B #\ \ The path to the paacrt work area
.B indirect_dir \[dq]/pub/indirects/<repo>.<host>\[dq]
.B #\ \ What IP mask should be used for sharing?
.B cidr 192.168.0.0/16
.B #\ \ Path to the repository (not the mirror of the repository)
.B path /pub/computing/software/local/debian/localpublic-deb
.B #\ \ Debian repositories need to know a few other things.
.B origin \[dq]Alexis Huxley\[dq]
.B label \[dq]Alexis Huxley\[dq]
.B signer \[dq]alexis\[dq]
.fam T
.fi
.br
.PP
At this point the developer may insert packages in to the repository and
generate the necessary control files:
.IP
.nf
.fam C
developer@apple$ \fBpaa insert  localpublic lenny,squeeze,wheezy main \[rs]
.B \ \ \ \ XXXXXXXXXXXX\fR
developer@apple$ \fBpaa insert  localpublic lenny,squeeze,wheezy main \[rs]
.B \ \ \ \ YYYYYYYYYYYY\fR
developer@apple$ \fBpaa control localpublic\fR
.fam T
.fi
.br
.PP
Let us suppose that the administrators wish to install hosts,
configuring them to access the local mirrors of the Debian repository
and the \[oq]localpublic\[cq] repository. On host \[oq]banana\[cq], the repository administrator
first registers the repositories:
.IP
.nf
.fam C
repoadmin@banana$ \fBpaa repo debian      deb mirrored true\fR
repoadmin@banana$ \fBpaa repo localpublic deb mirrored false\fR
.fam T
.fi
.br
.PP
Just as the developer did, he needs to provide more information
about the repositories, which he does by running:
.IP
.nf
.fam C
repoadmin@banana$ \fBpaa editrepo ALL-REPOS\fR
.fam T
.fi
.br
.PP
For the \[oq]debian\[cq] repository we provides this configuration:
.IP
.nf
.fam C
.B #####################################################################
.B #
.B #\ \ Internal variables (defined for convenience and referenced only 
.B #\ \ from within this file)
.B #
.B #####################################################################
.B \ 
.B _RELEASES=\[dq]squeeze\[dq]
.B _PORTS=\[dq]i386 amd64\[dq]
.B _SECTIONS=\[dq]main contrib non-free main/debian-installer\[dq]
.B \ 
.B #####################################################################
.B #
.B #\ \ Repository contents (defines what is in or may be inserted into 
.B #\ \ this repo)
.B #
.B #####################################################################
.B \ 
.B #\ \ The set of *all* releases, ports and sections this repository 
.B #\ \ will contain.
.B for _RELEASE in $_RELEASES; do
.B \ \ \ \ release $_RELEASE
.B \ \ \ \ for _PORT in $_PORTS; do
.B \ \ \ \ \ \ \ \ port $_RELEASE $_PORT
.B \ \ \ \ done
.B \ \ \ \ for _SECTION in $_SECTIONS; do
.B \ \ \ \ \ \ \ \ section $_RELEASE $_SECTION
.B \ \ \ \ done
.B done
.B \ 
.B #####################################################################
.B #
.B #\ \ Misc settings
.B #
.B #####################################################################
.B \ 
.B #\ \ URL for the repo
.B url \[dq]http://install.pasta.net/<repo>.<host>/\[dq]
.B #\ \ The path to your mirrors
.B mirror_dir \[dq]/pub/mirrors/<host>\[dq]
.B #\ \ The path to the paacrt work area
.B freeze_dir \[dq]/pub/freezes/<repo>.<freeze>\[dq]
.B #\ \ The path to the paacrt work area
.B indirect_dir \[dq]/pub/indirects/<repo>.<host>\[dq]
.B #\ \ What IP mask should be used for sharing?
.B cidr 192.168.0.0/16
.B #\ \ The command to update the mirror in the current directory.
.B mirror_cmd \[dq]debmirror --rsync-options=\[rs]\[dq]-aIL --partial \[rs]
.B \ \ \ \ --no-motd\[rs]\[dq] --ignore-release-gpg --getcontents --nosource \[rs]
.B \ \ \ \ --method=rsync --host=ftp2.de.debian.org --root=:debian \[rs]
.B \ \ \ \ --arch=${_PORTS// /,} --dist=${_RELEASES// /,} \[rs]
.B \ \ \ \ --section=${_SECTIONS// /,} --di-dist=dists --di-arch=arches .\[dq]
.B #\ \ Which distribution is this repo for?
.B distro debian
.fam T
.fi
.br
.PP
For the \[oq]localpublic\[cq] repository the administrator can use the same configuration that 
the developer used.
.PP
Then he mirrors these repositories and immediately freezes his mirrors:
.IP
.nf
.fam C
repoadmin@banana$ \fBpaa mirror ALL-REPOS\fR
repoadmin@banana$ \fBpaa freeze ALL-REPOS\fR
.fam T
.fi
.br
.PP
.PP
.B Paa
is intelligent enough to share with an install client only what is appropriate,
providing it is told a little about the install client. To do this the repository administrator
runs:
.IP
.nf
.fam C
repoadmin@banana$ \fBpaa host coconut deb debian squeeze amd64\fR
.fam T
.fi
.br
.PP
.PP
Directing incoming requests for packages to the appropriate
repositories is done by running:
.IP
.nf
.fam C
repoadmin@banana$ \fBpaa indirect ALL-REPOS coconut NEWEST-FREEZE\fR
repoadmin@banana$ \fBpaa share\ \ \ \ ALL-REPOS coconut\fR
.fam T
.fi
.br
.PP
.PP
The system administator on coconut tells his paa about his host:
.IP
.nf
.fam C
root@coconut# \fBpaa host THIS-HOST\fR
.fam T
.fi
.br
.PP
.PP
He then registers the two repositories he wants to access by running:
.IP
.nf
.fam C
root@coconut# \fBpaa repo debian      deb accessed true\fR
root@coconut# \fBpaa repo localpublic deb accessed false\fR
.fam T
.fi
.br
.PP
.PP
and, just as the developer and repositories administrator did, he needs 
to provide more information about the repositories, which he does by running:
.IP
.nf
.fam C
root@coconut# \fBpaa editrepo ALL-REPOS\fR
.fam T
.fi
.br
.PP
The configurations he provides are the same as above, except that some 
directives need to be removed (because he intends to do less with the
repositories did than the developer or repositories administrator did),
but
.B paa
will warn him which directives need to be removed, and will not mark
the repository as '\[oq]available\[cq] until all errors have been
resolved.
.PP
Then he can configure coconut's package management system (apt in this
example) by running:
.IP
.nf
.fam C
root@coconut# \fBpaa access ALL-REPOS\fR
.fam T
.fi
.br
.PP
And finally he can install software:
.IP
.nf
.fam C
root@coconut# \fBapt-get update\fR
root@coconut# \fBapt-get install XXXXXXXXXXXXX\fR
.fam T
.fi
.br
.ne 5
.SH CAVEATS
Currently,
.B paa\fR's
.B share
and
.B unshare
functions only support
.B apache2\fR(8).
.PP
The developer must supply several settings that are not needed for his tasks
(e.g.
.B url\fR, 
.B cidr\fR).
.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), bash(1), crontab(5), deb(5), debmirror(1), rpmmirror(1), sqlite(1), rpm(8)
.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]