README.config

Explanation of configuration files options for dak
==================================================

DB
--

Essential.  List of database details, e.g.

| DB
| {
|   Name "projectb";
|   Host ""; 
|   Port -1;
| };

Name (required): The name of the PostgreSQL database which has been created
for dak.

Host (required): The name of the host on which the database is located.  If
the database is local, Host should be blank.

Port (required): The port of the database.  If the port is the default
value (5432), this option should be set to -1.

================================================================================

Dir
---

Mandatory.  List of directory locations, e.g.

| Dir
| {
|   Root "/org/ftp.debian.org/ftp/";
|   Pool "/org/ftp.debian.org/ftp/pool/";
|   Templates "/org/ftp.debian.org/dak/templates/";
|   PoolRoot "pool/";
|   Override "/org/ftp.debian.org/scripts/override/";
|   Lists "/org/ftp.debian.org/database/dists/";
|   Log "/org/ftp.debian.org/log/";
|   Morgue "/org/ftp.debian.org/morgue/";
|   MorgueReject "reject";
|   QueueBuild "/org/incoming.debian.org/buildd/";
|   UrgencyLog "/org/ftp.debian.org/testing/urgencies/";
|   Queue
|   {  
|     Accepted "/org/ftp.debian.org/queue/accepted/";
|     Byhand "/org/ftp.debian.org/queue/byhand/";
|     Done "/org/ftp.debian.org/queue/done/";
|     Holding "/org/ftp.debian.org/queue/holding/";
|     New "/org/ftp.debian.org/queue/new/";
|     Reject "/org/ftp.debian.org/queue/reject/";
|     Unchecked "/org/ftp.debian.org/queue/unchecked/";
|   };
| };

Root (required): Specifies the path of the root of the FTP archive.

Pool (required): This variable specifies the path of the pool
directory.  Debian packages will be placed in the pool by 'dak
process-accepted' after they have been accepted by dak
process-unchecked.

Templates (required): dak sends various mails and uses templates from
this directory.

PoolRoot (required): This variable specifies the basename of the pool
directory.

Override (optional): This directory optionally stores override files (used
by 'dak make-overrides').

Lists (optional): This directory holds file lists used by apt-ftparchive to
generate Packages and Sources files (used by 'dak make-suite-file-list').

Log (required): Log files are put in this directory.

Morgue (required): Removed files are moved there.  The morgue has various
sub-directories, including (optionally) those defined by
Clean-Queues::MorgueSubDir and Clean-Suites::MorgueSubDir.

MorgueReject (required): if dak cannot move a rejected package to
Dir::Queue::Reject, it will try to move it to the Dir::MorgueReject
directory located under Dir::Morgue.

QueueBuild (optional): This variable is only relevant if any suites
are to be auto built, i.e. if Dinstall::QueueBuildSuites has any
values.

UrgencyLog (optional): If this directory is specified, 'dak
process-accepted' will store the urgency value of each upload.  This
is mainly used for britney (the testing script).

Queue (required): This sub-tree defines important directories for the
incoming queue.  The following variables have to be set: Accepted, Byhand
Done, Holding, New, Reject, Unchecked.  An explanation of the function of
these directores can be found in README.new-incoming.

Queue::BTSVersionTrack (optional): this directory holds the DebBugs
Version Tracking support files.

================================================================================

Suite
-----

Mandatory.  List of all suites, e.g. 

| Suite
| {
|   Unstable
|   {
| 	Components 
| 	{
| 	  main;
| 	};
| 	Architectures 
| 	{
| 	  source; 
| 	  all;
| 	  i386;
| 	};
| 	Announce "debian-devel-changes@lists.debian.org";
| 	Origin "Debian";
| 	Description "Debian Unstable - Not Released";
| 	CodeName "sid";
| 	OverrideCodeName "sid";
| 	Priority "5";
|   };
| };

Announce (optional): controls where "Installed foo" mails are sent.

CodeName, Origin and Description (optional): This settings are used by
'dak generate-releases' and put in the Release files.

OverrideCodeName (optional): used by 'dak make-overrides'.

Priority (optional) determines which suite is used for the Maintainers file
as generated by 'dak make-maintainers' (highest wins).

CopyChanges (optional): if this variable is present it should be a path
into the archive (i.e. "Dir::RootDir"); any upload targeted for a suite
with this config option present will have the .changes file copied into
that path.

CopyDotDak (optional): if this is present it should be an absolute path; any
upload targeted for a suite with this config option present will have the
.dak file copied into that path.  This option is similar to CopyChanges
and will most often be used with it; they're seperate because .changes
files are mirrored and .dak files aren't, so the paths will usually be
different.

There are more optional variables, such as VersionChecks.  Please see
dak.conf for examples.

================================================================================

SuiteMappings
-------------

Optional.  List of mappings for the Distribution file in a .changes file, e.g.:

| SuiteMappings
| {
|    "map stable proposed-updates";
|    "map frozen unstable";
|    "map-unreleased stable unstable";
|    "map-unreleased proposed-updates unstable";
|    "ignore testing";
| };

There are three mapping types:

(1) map <source> <dest>

      Any target suite of '<source>' is unconditionally overriden to
      '<dest>'.

(2) map-unreleased <source> <dest>

      Any upload targeted for suite '<source>' will be mapped to
      '<dest>' iff it contains uploads for an architecture that is not
      part of '<source>'.

(3) ignore <suite>

      Any target suite of '<suite>' is unconditionally removed from
      the list of target suites.  NB: if the upload had only one
      target suite this will lead to rejection.

NB: ordering is not guaranteed.

================================================================================

Dinstall
--------

Mandatory.  List of dinstall options, e.g.:

| Dinstall
| {
|    GPGKeyring {
|       "/org/keyring.debian.org/keyrings/debian-keyring.gpg";
|       "/org/keyring.debian.org/keyrings/debian-keyring.pgp";
|    };
|    SigningKeyring "/org/ftp.debian.org/s3kr1t/dot-gnupg/secring.gpg";
|    SendmailCommand "/usr/sbin/sendmail -odq -oi -t";
|    MyEmailAddress "Debian Installer <installer@ftp-master.debian.org>";
|    MyAdminAddress "ftpmaster@debian.org";
|    MyHost "debian.org";  // used for generating user@my_host addresses in e.g. manual_reject()
|    MyDistribution "Debian";
|    BugServer "bugs.debian.org";
|    PackagesServer "packages.debian.org";
|    TrackingServer "packages.qa.debian.org";
|    LockFile "/org/ftp.debian.org/dak/lock";
|    Bcc "archive@ftp-master.debian.org";
|    FutureTimeTravelGrace 28800; // 8 hours
|    PastCutoffYear "1984";
|    BXANotify "false";
|    QueueBuildSuites
|    {
|      unstable;
|    };
| };

GPGKeyring (required): filenames of the PGP and GnuPG
keyrings to be used by dak.

SigningKeyring (optional): this is the private keyring used by 'dak
generate-releases'.

SendmailCommand (required): command to call the MTA.

MyEmailAddress (required): this is used as the From: line for sending mails
as a script/daemon.

MyAdminAddress (required): used as a contact address in mails.

MyDistribution (required): this variable is used in emails sent out by
dak and others.  It should indicate the name of the distribution.

BugServer (required): is used by 'dak process-unchecked' and 'dak rm'
when closing bugs.

PackagesServer (requried): used by 'dak rm' when carbon-copying a bug
close mail to a package maintainer.

TrackingServer (optional): used by 'dak process-unchecked' and 'dak
rm' to send messages for the maintainer also to an alias for people
tracking a specific source package.

LockFile (required): contains the filename of the lockfile used by dinstall
when in action mode (i.e. not using -n/--no-action).

All sent mail is blind carbon copied to the email address in Bcc if it's
not blank.

FutureTimeTravelGrace (required): specifies how many seconds into the
future timestamps are allowed to be inside a deb before being rejected.

PastCutoffYear (required): specifies the cut-off year which is used when
deciding whether or not to reject packages based on the file timestamp.

BXANotify (optional): a boolean (default: no); if true (Debian-specific)
BXA notification is sent.  The template for the BXA notification is located
in Dir::Templates/process-new.bxa_notification and should be changed if this
option is set.

OverrideDisparityCheck (optional): a boolean (default: no); if true,
dak process-unchecked compares an uploads section/priority with the overrides and whines
at the maintainer if they differ.

CloseBugs (optional): a boolean (default: no); if true the automated bug
closing feature of dinstall is activated.

QueueBuildSuites (optional): a list of suites which should be auto
build.

QueueBuild is a boolean; if true it activates support
for auto-building from accepted.

OverrideMaintainer (optional): be used to globally override the
__MAINTAINER_TO__ and __MAINTAINER_FROM__ variables in template mails.
Use with caution.

SkipTime (required): an integer value which is the number of seconds that a
file must be older than (via it's last modified timestamp) before dak process-unchecked
will REJECT rather than SKIP the package.

KeyAutoFetch (optional): boolean (default: false), which if set (and
not overriden by explicit argument to check_signature()) will enable
auto key retrieval.  Requires KeyServer and SigningKeyIds variables be
set.  NB: you should only enable this variable on production systems
if you have strict control of your upload queue.

KeyServer (optional): keyserver used for key auto-retrieval
(c.f. KeyAutoFetch).

================================================================================

Archive
-------

Mandatory.  List of all archives, e.g.

| Archive
| {
|   ftp-master
|   {
|     OriginServer "ftp-master.debian.org";
|     PrimaryMirror "ftp.debian.org";
|     Description "Master Archive for the Debian project";
|   };
| };

OriginServer and PrimaryMirror (required): used 'dak rm's bug closing mail
templates.  The host name and it's OriginServer and Description are part of
the SQL database in the 'archive' table.

================================================================================

Architectures
-------------

Mandatory.  List of all architectures, e.g.

| Architectures
| {
|   source "Source";
|   all	   "Architecture Independent";
|   i386   "Intel ia32";
| };

Both values go into the SQL database's 'architecture' table.
The description is currently unused.

================================================================================

Component
---------

Mandatory.  List of all components, e.g.

| Component
| {
|   main
|   {
| 	Description "Main";
| 	MeetsDFSG "true";
|   };
| };

All three values go into the SQL database's 'component' table.
MeetsDFSG is currently unused.

================================================================================

Section
-------

Mandatory.  List of all valid sections, e.g.

| Section
| {
|   base;
| };

The section goes into the 'section' table in SQL database.

================================================================================

Priority
--------

Mandatory.  List of all valid priorities, e.g.

| Priority
| {
|   required 1;
|   important 2;
|   standard 3;
|   optional 4;
|   extra 5;
|   source 0; // i.e. unused
| };

The value is the sorting key.  Both the section and it's sorting key
go into the SQL database's 'priority' table.

================================================================================

OverrideType
------------

Mandatory.  List of al valid override types, e.g.

| OverrideType
| {
|   deb;
|   dsc;
|   udeb;
| };

The type goes into the 'override_type' table in the SQL database.

================================================================================

Location
--------

Mandatory.  List all locations, e.g.

| Location
| {
|   /org/ftp.debian.org/ftp/pool/
|     {
|       Archive "ftp-master";
|       Type "pool";
|	Suites
|	{
|	  Stable;
|	  Unstable;
|	};
|     };
| };

There are three valid values for 'Type': 'legacy', 'legacy-mixed' and
'pool'.  'legacy' and 'pool' are assumed to have sections for all
components listed in the Components section 'legacy-mixed' are assumed
to mix all components into one location.  The 'Archive' and 'Type'
sections go into the SQL database's 'location' table.  'Suites' is a
list of existent suites that should be used to populate the SQL
database.

Note that the archive value specified here must correspond to one defined
in Archive.

[Note: yes, this is horrible, it dates back to the original `import
       the existent archive into the SQL Database' script ('dak import-archive') and
       isn't otherwise used.  It should be revisted at some stage.]

================================================================================

Urgency
-------

Mandatory.

| Urgency
| {
|   Default "low";
|   Valid
|   {
|     low;
|     medium;
|     high;
|     emergency;
|     critical;
|   };
| };

This defines the valid and default urgency of an upload.  If a package is
uploaded with an urgency not listed here, it will be rejected.

================================================================================