1. Plugins
==========

Each supported distribution needs to have its proper plugin. The plugin
itself consists of 2 parts:

* plugin file - A python file dropped in /usr/share/retrace-server/plugins
                containing the following elements:

  - distribution: String considered plugin name and identifier.

  - abrtparser:   Parser able to get release from ABRT's os_release file.

  - guessparser:  Parser able to guess release from package's name. Can not
                  be relied on (e.g. el6 does not give enough information).

  - yumcfg:       a string that will be appended to yum config file for all
                  repositories

  - repos:        An array of public repositories and their mirrors.
                  The synchronization is realized using rsync or yum, so
                  repository path is either a directory in the filesystem,
                  rsync:// URL, http:// URL or ftp:// URL. $ARCH and $VER
                  meta-variables are expanded to appropriate strings.
                  The repo is either defined as list of mirrors or
                  a two-member tuple where the first member is the same
                  list of mirrors and second is a part of yum config file
                  that will only be appended to the repo.
                  Example:
                  repos = [
                    [ #repo1
                      /srv/repos/repo1_mirror1,
                      rsync://repo1/mirror2,
                    ],
                    [ #repo2
                      ftp://repo2/repo2_mirror1,
                      /srv/repos/repo2_mirror2,
                    ],
                    [ #repo3
                      rsync://repo3/mirror1,
                    ],
                    ( #repo4
                      [
                        "rsync://repo4/mirror1",
                        "http://repo4/mirror2",
                      ],
                      "gpgcheck = 0", # local yum config
                    ),
                  ]

* GPG keys - Files containig GPG keys to verify downloaded package's signature.
             Dropped in /usr/share/retrace-server/gpg.

2. Repository synchronization
=============================

Since older versions of packages are deleted from public repositories (Fedora),
Retrace server needs to maintain local copies of repositories containing all
versions of all packages. This job is realized by retrace-server-reposync tool
by running 'retrace-server-reposync distribution version architecture' where
'distribution' is a plugin name (see 1. Plugins). The retrace-server-reposync
tool should be set up in retrace's crontab.

3. Garbage collection
=====================

There are 3 types of garbage:

* old tasks - Tasks older than DeleteTaskAfter config option.

* failed tasks - Tasks which made Retrace server crash. This most probably
                 signifies Retrace server application error. These are not
                 tasks finished by FINISHED_FAILURE.

* long running tasks - Task running for > 1 hour. Tasks who got stuck in
                       an endless loop, deadlocks etc. It may happen that
                       if the server is hard loaded, regular tasks do not
                       finish in time, but it is server admin's job to
                       limit task count by setting MaxParallelTasks config
                       option. No real user will wait 1 hour for the backtrace.

The retrace-server-cleanup tool handles all of these types. It should be set up
in apache's crontab (it needs root privileges to clean up mock chroots) to run
every hour.

4. SELinux
==========

At the moment you need to disable SELinux to make Retrace server work properly.
We are working on the policy, however the code changes too quickly to maintain
a long-term working policy.