docs/README.config

   1 Explanation of configuration files options for dak
   2 ==================================================
   3
   4 DB
   5 --
   6
   7 Essential.  List of database details, e.g.
   8
   9 | DB
  10 | {
  11 |   Name "projectb";
  12 |   Host "";
  13 |   Port -1;
  14 | };
  15
  16 Name (required): The name of the PostgreSQL database which has been created
  17 for dak.
  18
  19 Host (required): The name of the host on which the database is located.  If
  20 the database is local, Host should be blank.
  21
  22 Port (required): The port of the database.  If the port is the default
  23 value (5432), this option should be set to -1.
  24
  25 ================================================================================
  26
  27 Dir
  28 ---
  29
  30 Mandatory.  List of directory locations, e.g.
  31
  32 | Dir
  33 | {
  34 |   Root "/org/ftp.debian.org/ftp/";
  35 |   Pool "/org/ftp.debian.org/ftp/pool/";
  36 |   Templates "/org/ftp.debian.org/dak/templates/";
  37 |   PoolRoot "pool/";
  38 |   Override "/org/ftp.debian.org/scripts/override/";
  39 |   Lists "/org/ftp.debian.org/database/dists/";
  40 |   Log "/org/ftp.debian.org/log/";
  41 |   Morgue "/org/ftp.debian.org/morgue/";
  42 |   QueueBuild "/org/incoming.debian.org/buildd/";
  43 |   UrgencyLog "/org/ftp.debian.org/testing/urgencies/";
  44 |   Queue
  45 |   {
  46 |     Accepted "/org/ftp.debian.org/queue/accepted/";
  47 |     Byhand "/org/ftp.debian.org/queue/byhand/";
  48 |     Done "/org/ftp.debian.org/queue/done/";
  49 |     Holding "/org/ftp.debian.org/queue/holding/";
  50 |     New "/org/ftp.debian.org/queue/new/";
  51 |     Reject "/org/ftp.debian.org/queue/reject/";
  52 |     Unchecked "/org/ftp.debian.org/queue/unchecked/";
  53 |   };
  54 | };
  55
  56 Root (required): Specifies the path of the root of the FTP archive.
  57
  58 Pool (required): This variable specifies the path of the pool
  59 directory.  Debian packages will be placed in the pool by 'dak
  60 process-accepted' after they have been accepted by dak
  61 process-unchecked.
  62
  63 Templates (required): dak sends various mails and uses templates from
  64 this directory.
  65
  66 PoolRoot (required): This variable specifies the basename of the pool
  67 directory.
  68
  69 Override (optional): This directory optionally stores override files (used
  70 by 'dak make-overrides').
  71
  72 Lists (optional): This directory holds file lists used by apt-ftparchive to
  73 generate Packages and Sources files (used by 'dak make-suite-file-list').
  74
  75 Log (required): Log files are put in this directory.
  76
  77 Morgue (required): Removed files are moved there.  The morgue has various
  78 sub-directories, including (optionally) those defined by
  79 Clean-Queues::MorgueSubDir and Clean-Suites::MorgueSubDir.
  80
  81 UrgencyLog (optional): If this directory is specified, 'dak
  82 process-accepted' will store the urgency value of each upload.  This
  83 is mainly used for britney (the testing script).
  84
  85 Queue (required): This sub-tree defines important directories for the
  86 incoming queue.  The following variables have to be set: Accepted, Byhand
  87 Done, Holding, New, Reject, Unchecked.  An explanation of the function of
  88 these directores can be found in README.new-incoming.
  89
  90 Queue::BTSVersionTrack (optional): this directory holds the DebBugs
  91 Version Tracking support files.
  92
  93 ================================================================================
  94
  95 Suite
  96 -----
  97
  98 Mandatory.  List of all suites, e.g.
  99
 100 | Suite
 101 | {
 102 |   Unstable
 103 |   {
 104 |       Components
 105 |       {
 106 |         main;
 107 |       };
 108 |       Architectures
 109 |       {
 110 |         source;
 111 |         all;
 112 |         i386;
 113 |       };
 114 |       Announce "debian-devel-changes@lists.debian.org";
 115 |       Origin "Debian";
 116 |       Description "Debian Unstable - Not Released";
 117 |       CodeName "sid";
 118 |       OverrideCodeName "sid";
 119 |       Priority "5";
 120 |   };
 121 | };
 122
 123 Announce (optional): controls where "Installed foo" mails are sent.
 124
 125 CodeName, Origin and Description (optional): This settings are used by
 126 'dak generate-releases' and put in the Release files.
 127
 128 OverrideCodeName (optional): used by 'dak make-overrides'.
 129
 130 Priority (optional) determines which suite is used for the Maintainers file
 131 as generated by 'dak make-maintainers' (highest wins).
 132
 133 CopyChanges (optional): if this variable is present it should be a path
 134 into the archive (i.e. "Dir::RootDir"); any upload targeted for a suite
 135 with this config option present will have the .changes file copied into
 136 that path.
 137
 138 CopyDotDak (optional): if this is present it should be an absolute path; any
 139 upload targeted for a suite with this config option present will have the
 140 .dak file copied into that path.  This option is similar to CopyChanges
 141 and will most often be used with it; they're seperate because .changes
 142 files are mirrored and .dak files aren't, so the paths will usually be
 143 different.
 144
 145 There are more optional variables, such as VersionChecks.  Please see
 146 dak.conf for examples.
 147
 148 ================================================================================
 149
 150 SuiteMappings
 151 -------------
 152
 153 Optional.  List of mappings for the Distribution file in a .changes file, e.g.:
 154
 155 | SuiteMappings
 156 | {
 157 |    "map stable proposed-updates";
 158 |    "map frozen unstable";
 159 |    "map-unreleased stable unstable";
 160 |    "map-unreleased proposed-updates unstable";
 161 |    "ignore testing";
 162 | };
 163
 164 There are three mapping types:
 165
 166 (1) map <source> <dest>
 167
 168       Any target suite of '<source>' is unconditionally overriden to
 169       '<dest>'.
 170
 171 (2) map-unreleased <source> <dest>
 172
 173       Any upload targeted for suite '<source>' will be mapped to
 174       '<dest>' iff it contains uploads for an architecture that is not
 175       part of '<source>'.
 176
 177 (3) ignore <suite>
 178
 179       Any target suite of '<suite>' is unconditionally removed from
 180       the list of target suites.  NB: if the upload had only one
 181       target suite this will lead to rejection.
 182
 183 NB: ordering is not guaranteed.
 184
 185 ================================================================================
 186
 187 Dinstall
 188 --------
 189
 190 Mandatory.  List of dinstall options, e.g.:
 191
 192 | Dinstall
 193 | {
 194 |    GPGKeyring {
 195 |       "/org/keyring.debian.org/keyrings/debian-keyring.gpg";
 196 |       "/org/keyring.debian.org/keyrings/debian-keyring.pgp";
 197 |    };
 198 |    SigningKeyring "/org/ftp.debian.org/s3kr1t/dot-gnupg/secring.gpg";
 199 |    SendmailCommand "/usr/sbin/sendmail -odq -oi -t";
 200 |    MyEmailAddress "Debian Installer <installer@ftp-master.debian.org>";
 201 |    MyAdminAddress "ftpmaster@debian.org";
 202 |    MyHost "debian.org";  // used for generating user@my_host addresses in e.g. manual_reject()
 203 |    MyDistribution "Debian";
 204 |    BugServer "bugs.debian.org";
 205 |    PackagesServer "packages.debian.org";
 206 |    TrackingServer "packages.qa.debian.org";
 207 |    LockFile "/org/ftp.debian.org/dak/lock";
 208 |    Bcc "archive@ftp-master.debian.org";
 209 |    FutureTimeTravelGrace 28800; // 8 hours
 210 |    PastCutoffYear "1984";
 211 |    BXANotify "false";
 212 | };
 213
 214 GPGKeyring (required): filenames of the PGP and GnuPG
 215 keyrings to be used by dak.
 216
 217 SigningKeyring (optional): this is the private keyring used by 'dak
 218 generate-releases'.
 219
 220 SendmailCommand (required): command to call the MTA.
 221
 222 MyEmailAddress (required): this is used as the From: line for sending mails
 223 as a script/daemon.
 224
 225 MyAdminAddress (required): used as a contact address in mails.
 226
 227 MyDistribution (required): this variable is used in emails sent out by
 228 dak and others.  It should indicate the name of the distribution.
 229
 230 BugServer (required): is used by 'dak process-unchecked' and 'dak rm'
 231 when closing bugs.
 232
 233 PackagesServer (required): used by 'dak rm' and 'dak override' when
 234 carbon-copying a bug close mail to a package maintainer.
 235
 236 TrackingServer (optional): used by 'dak process-unchecked' and 'dak
 237 rm' to send messages for the maintainer also to an alias for people
 238 tracking a specific source package.
 239
 240 LockFile (required): contains the filename of the lockfile used by dinstall
 241 when in action mode (i.e. not using -n/--no-action).
 242
 243 All sent mail is blind carbon copied to the email address in Bcc if it's
 244 not blank.
 245
 246 FutureTimeTravelGrace (required): specifies how many seconds into the
 247 future timestamps are allowed to be inside a deb before being rejected.
 248
 249 PastCutoffYear (required): specifies the cut-off year which is used when
 250 deciding whether or not to reject packages based on the file timestamp.
 251
 252 BXANotify (optional): a boolean (default: no); if true (Debian-specific)
 253 BXA notification is sent.  The template for the BXA notification is located
 254 in Dir::Templates/process-new.bxa_notification and should be changed if this
 255 option is set.
 256
 257 OverrideDisparityCheck (optional): a boolean (default: no); if true,
 258 dak process-unchecked compares an uploads section/priority with the overrides and whines
 259 at the maintainer if they differ.
 260
 261 CloseBugs (optional): a boolean (default: no); if true the automated bug
 262 closing feature of dinstall is activated.
 263
 264 QueueBuild is a boolean; if true it activates support
 265 for auto-building from accepted.
 266
 267 OverrideMaintainer (optional): be used to globally override the
 268 __MAINTAINER_TO__ and __MAINTAINER_FROM__ variables in template mails.
 269 Use with caution.
 270
 271 SkipTime (required): an integer value which is the number of seconds that a
 272 file must be older than (via it's last modified timestamp) before dak process-unchecked
 273 will REJECT rather than SKIP the package.
 274
 275 KeyAutoFetch (optional): boolean (default: false), which if set (and
 276 not overriden by explicit argument to check_signature()) will enable
 277 auto key retrieval.  Requires KeyServer and SigningKeyIds variables be
 278 set.  NB: you should only enable this variable on production systems
 279 if you have strict control of your upload queue.
 280
 281 KeyServer (optional): keyserver used for key auto-retrieval
 282 (c.f. KeyAutoFetch).
 283
 284 ================================================================================
 285
 286 Archive
 287 -------
 288
 289 Mandatory.  List of all archives, e.g.
 290
 291 | Archive
 292 | {
 293 |   ftp-master
 294 |   {
 295 |     OriginServer "ftp-master.debian.org";
 296 |     PrimaryMirror "ftp.debian.org";
 297 |     Description "Master Archive for the Debian project";
 298 |   };
 299 | };
 300
 301 OriginServer and PrimaryMirror (required): used 'dak rm's bug closing mail
 302 templates.  The host name and it's OriginServer and Description are part of
 303 the SQL database in the 'archive' table.
 304
 305 ================================================================================
 306
 307 Architectures
 308 -------------
 309
 310 Mandatory.  List of all architectures, e.g.
 311
 312 | Architectures
 313 | {
 314 |   source "Source";
 315 |   all    "Architecture Independent";
 316 |   i386   "Intel ia32";
 317 | };
 318
 319 Both values go into the SQL database's 'architecture' table.
 320 The description is currently unused.
 321
 322 ================================================================================
 323
 324 Section
 325 -------
 326
 327 Mandatory.  List of all valid sections, e.g.
 328
 329 | Section
 330 | {
 331 |   base;
 332 | };
 333
 334 The section goes into the 'section' table in SQL database.
 335
 336 ================================================================================
 337
 338 Priority
 339 --------
 340
 341 Mandatory.  List of all valid priorities, e.g.
 342
 343 | Priority
 344 | {
 345 |   required 1;
 346 |   important 2;
 347 |   standard 3;
 348 |   optional 4;
 349 |   extra 5;
 350 |   source 0; // i.e. unused
 351 | };
 352
 353 The value is the sorting key.  Both the section and it's sorting key
 354 go into the SQL database's 'priority' table.
 355
 356 ================================================================================
 357
 358 Location
 359 --------
 360
 361 Mandatory.  List all locations, e.g.
 362
 363 | Location
 364 | {
 365 |   /org/ftp.debian.org/ftp/pool/
 366 |     {
 367 |       Archive "ftp-master";
 368 |       Type "pool";
 369 |       Suites
 370 |       {
 371 |         Stable;
 372 |         Unstable;
 373 |       };
 374 |     };
 375 | };
 376
 377 There are three valid values for 'Type': 'legacy', 'legacy-mixed' and
 378 'pool'.  'legacy' and 'pool' are assumed to have sections for all
 379 components listed in the Components section 'legacy-mixed' are assumed
 380 to mix all components into one location.  The 'Archive' and 'Type'
 381 sections go into the SQL database's 'location' table.  'Suites' is a
 382 list of existent suites that should be used to populate the SQL
 383 database.
 384
 385 Note that the archive value specified here must correspond to one defined
 386 in Archive.
 387
 388 [Note: yes, this is horrible, it dates back to the original `import
 389        the existent archive into the SQL Database' script ('dak import-archive') and
 390        isn't otherwise used.  It should be revisted at some stage.]
 391
 392 ================================================================================
 393
 394 Urgency
 395 -------
 396
 397 Mandatory.
 398
 399 | Urgency
 400 | {
 401 |   Default "low";
 402 |   Valid
 403 |   {
 404 |     low;
 405 |     medium;
 406 |     high;
 407 |     emergency;
 408 |     critical;
 409 |   };
 410 | };
 411
 412 This defines the valid and default urgency of an upload.  If a package is
 413 uploaded with an urgency not listed here, it will be rejected.
 414
 415 ================================================================================