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