reprepro manual

This manual documents reprepro, a tool to generate and administer Debian package repositories.
Other useful resources:

the homepage of reprepro.
local directory with documentation and examples, if you have reprepro installed.
the Frequently Asked Questions

Sections of this document:

Introduction
First steps
Repository basics
Config files
Generation of index files
Local packages
- Including via command line
- Processing an incoming queue
Mirroring
Propagation of packages
Snapshots (TODO)
Source package tracking (TODO)
Extending reprepro / Hooks and more
Maintenance
Internals
Disaster recovery
Paranoia
What reprepro cannot do

Introduction

What reprepro does

Reprepro is a tool to take care of a repository of Debian packages (.dsc,.deb and .udeb). It installs them to the proper places, generates indices of packages (Packages and Sources and their compressed variants) and of index files (Release and optionally Release.gpg), so tools like apt know what is available and where to get it from. It will keep track which file belongs to where and remove files no longer needed (unless told to not do so). It can also make (partial) partial mirrors of remote repositories, including merging multiple sources and automatically (if explicitly requested) removing packages no longer available in the source. And many other things (sometimes I fear it got a few features too much).

What reprepro needs

It needs some libraries (zlib, libgpgme, libdb (Version 3, 4.3 or 4.4)) and can be compiled with some more for additional features (libarchive, libbz2). Otherwise it only needs apt's methods (only when downloading stuff), gpg (only when signing or checking signatures), and if compiled without libarchive it needs tar and ar installed.
If you tell reprepro to call scripts for you, you will of course need the interpreters for these scripts: The included example to generate pdiff files needs python. The example to extract changelogs needs dpkg-source.

What this manual aims to do

This manual aims to give some overview over the most important features, so people can use them and so that I do not implement something a second time because I forgot support is already there. For a full reference of all possible commands and config options take a look at the man page, as this manual might miss some of the more obscure options.

First steps

generate a repository with local packages

Choose a directory (or create it).
Create a subdirectory called conf in there.
In the conf/ subdirectory create a file called distributions, with content like:
```
Codename: mystuff
Components: main bad
Architectures: sparc i386 source
```
or with content like:
```
Codename: andy
Suite: rusty
Components: main bad
Architectures: sparc i386 source
Origin: myorg
Version: 20.3
Description: my first little repository
```
(Multiple distributions are separated by empty lines, Origin, Version and Description are just copied to the generated Release files, more things controlling reprepro can appear which are described later).
If your conf/distributions file contained a Suite: and you are too lazy to generate the symbolic links yourself, call:
```
reprepro -b $YOURBASEDIR createsymlinks
```

Include some package, like:

reprepro -b $YOURBASEDIR include mystuff mypackage.changes

or:

reprepro -b $YOURBASEDIR includedeb mystuff mypackage.deb

Take a look at the generated pool and dists directories. They contain everything needed to apt-get from. Tell apt to include it by adding the following to your sources.list:
```
deb file:///$YOURBASEDIR mystuff main bad
```
or make it available via http or ftp and do the same http:// or ftp:// source.

mirroring packages from other repositories

This example shows how to generate a mirror of a single architecture with all packages of etch plus security updates:

Choose a directory (or create it).
Create a subdirectory called conf in there (if not already existent).
In the conf/ subdirectory create a file called distributions, with content like (or add to that file after an empty line):
```
Origin: Debian
Label: Debian
Suite: stable
Version: 4.0
Codename: etch
Architectures: i386
Components: main
Description: Debian 4.0 etch + security updates
Update: - debian security
Log: logfile
```
Actually only Codename, Components, Architecture and Update is needed, the rest is just information for clients. The Update line tells to delete everything no longer available (-), then add the debian and security rules, which still have to be defined:

In the conf/ subdirectory create a file called updates, with content like (or add to that file after an empty line:): or with content like:

Name: security
Method: http://security.debian.org/debian-security
Fallback: ftp://klecker.debian.org/debian-security
Suite: */updates
VerifyRelease: A70DAF536070D3A1|B5D0C804ADB11277
Architectures: i386
Components: main
UDebComponents:

Name: debian
Method: http://ftp2.de.debian.org/debian
Config: Acquire::Http::Proxy=http://proxy.myorg.de:8080
VerifyRelease: A70DAF536070D3A1|B5D0C804ADB11277

(If there are no Architecture, Components or UDebComponents, it will try all the distribution to update has. Fallback means a URL to try when the first cannot offer some file (Has to be the same method)).

Tell reprepro to update:
```
reprepro -b $YOURBASEDIR update etch
```
Take a look at the generated pool and dists directories. They contain everything needed to apt-get from. Tell apt to include it by adding the following to your sources.list:
```
deb file:///$YOURBASEDIR etch main
```
or make it available via http or ftp.

Repository basics

An apt-getable repository of Debian packages consists of two parts: the index files describing what is available and where it is and the actual Debian binary (.deb), installer binary (.udeb), and source (.dsc together with .tar.gz or .orig.tar.gz and .diff.gz) packages.
While you do not know how these look like to use reprepro, it's always a good idea to know what you are creating.

Index files

All index files are in subdirectories of a directory called dists. Apt is very decided what names those should have, including the name of dists. Including all optional and extensional files, the hierarchy looks like this:

dists

CODENAME

Each distribution has it's own subdirectory here, named by it's codename.

Release

This file describes what distribution this is and the checksums of all index files included.

Release.gpg

This is the optional detached gpg signature of the Release file. Take a look at the section about signing for how to active this.

Contents-ARCHITECTURE.gz

This optional file lists all files and which packages they belong to. It's downloaded and used by tools like apt-file to allow users to determine which package to install to get a specific file.
To activate generating of these files by reprepro, you need a Contents header in your distribution declaration.

COMPONENT1

Each component has it's own subdirectory here. They can be named whatever users can be bothered to write into their sources.list, but things like main, non-free and contrib are common. But funny names like bad or universe are just as possible.

source

If this distribution supports sources, this directory lists which source packages are available in this component.

Release

This file contains a copy of those information about the distribution applicable to this directory.

Sources

Sources.gz

Sources.bz2

These files contain the actual description of the source Packages. By default only the .gz file created, to create all three add the following to the declarations of the distributions:

DscIndices Sources Release . .gz .bz2

That header can also be used to name those files differently, but then apt will no longer find them...

Sources.diff

This optional directory contains diffs, so that only parts of the index file must be downloaded if it changed. While reprepro cannot generate these so-called pdiffs itself, it ships both with a program called rredtool and with an example python script to generate those.

binary-ARCHITECTURE

Each architecture has its own directory in each component.

Release

This file contains a copy of those information about the distribution applicable to this directory.

Packages

Packages.gz

Packages.bz2

These files contain the actual description of the binary Packages. By default only the uncompressed and .gz files are created. To create all three, add the following to the declarations of the distributions:

DebIndices Packages Release . .gz .bz2

That header can also be used to name those files differently, but then apt will no longer find them...

Packages.diff

debian-installer

This directory contains information about the .udeb modules for the Debian-Installer. Those are actually just a very stripped down form of normal .deb packages and this the hierarchy looks very similar:

binary-ARCHITECTURE

Packages
Packages.gz

COMPONENT2

There is one dir for every component. All look just the same.

SUITE -> CODENAME

To allow accessing distribution by function instead of by name, there are often symbolic links from suite to codenames. That way users can write

deb http://some.domain.tld/debian SUITE COMPONENT1 COMPONENT2

instead of

deb http://some.domain.tld/debian CODENAME COMPONENT1 COMPONENT2

in their /etc/apt/sources.list and totally get surprised by getting something new after a release.

Package pool

While the index files have a required filename, the actual files are given just as relative path to the base directory you specify in your sources list. That means apt can get them no matter what scheme is used to place them. The classical way Debian used till woody was to just put them in subdirectories of the binary-ARCHITECTURE directories, with the exception of the architecture-independent packages, which were put into a artificial binary-all directory. This was replaced for the official repository with package pools, which reprepro also uses. (Actually reprepro stores everything in pool a bit longer than the official repositories, that's why it recalculates all filenames without exception).
In a package pool, all package files of all distributions in that repository are stored in a common directory hierarchy starting with pool/, only separated by the component they belong to and the source package name. As everything this has disadvantages and advantages:

disadvantages
- different files in different distributions must have different filenames
- it's impossible to determine which distribution a file belongs to by path and filename (think mirroring)
- packages can no longer be grouped together in common subdirectories by having similar functions
advantages
- the extremely confusing situation of having differently build packages with the same version if different distributions gets impossible by design.
- the source (well, if it exists) is in the same directory as the binaries generated from it
- same files in different distributions need disk-space and bandwidth only once
- each package can be found only knowing component and sourcename

Now let's look at the actual structure of a pool (there is currently no difference between the pool structure of official Debian repositories and those generated by reprepro):

pool

The directory all this resides in is normally called pool. That's nowhere hard coded in apt but that only looks at the relative directory names in the index files. But there is also no reason to name it differently.

COMPONENT1

a: As there are really many different source packages, the directory would be too full when all put here. So they are separated in different directories. Source packages starting with lib are put into a directory named after the first four letters of the source name. Everything else is put in a directory having the first letter as name.

reprepro manual

Table of contents

Introduction

What reprepro does

What reprepro needs

What this manual aims to do

First steps

generate a repository with local packages

mirroring packages from other repositories

Repository basics

Index files

Package pool