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 |    FutureTimeTravelGrace 28800; // 8 hours
 217 |    PastCutoffYear "1984";
 218 |    BXANotify "false";
 219 |    QueueBuildSuites
 220 |    {
 221 |      unstable;
 222 |    };
 223 | };
 224
 225 PGPKeyring and GPGKeyring (required): filenames of the PGP and GnuPG
 226 keyrings to be used by dak respectively.
 227
 228 SigningKeyring (optional): this is the private keyring used by 'dak
 229 generate-releases'.
 230
 231 SendmailCommand (required): command to call the MTA.
 232
 233 MyEmailAddress (required): this is used as the From: line for sending mails
 234 as a script/daemon.
 235
 236 MyAdminAddress (required): used as a contact address in mails.
 237
 238 MyDistribution (required): this variable is used in emails sent out by
 239 dak and others.  It should indicate the name of the distribution.
 240
 241 BugServer (required): is used by 'dak process-unchecked' and 'dak rm'
 242 when closing bugs.
 243
 244 PackagesServer (requried): used by 'dak rm' when carbon-copying a bug
 245 close mail to a package maintainer.
 246
 247 TrackingServer (optional): used by 'dak process-unchecked' and 'dak
 248 rm' to send messages for the maintainer also to an alias for people
 249 tracking a specific source package.
 250
 251 LockFile (required): contains the filename of the lockfile used by dinstall
 252 when in action mode (i.e. not using -n/--no-action).
 253
 254 All sent mail is blind carbon copied to the email address in Bcc if it's
 255 not blank.
 256
 257 FutureTimeTravelGrace (required): specifies how many seconds into the
 258 future timestamps are allowed to be inside a deb before being rejected.
 259
 260 PastCutoffYear (required): specifies the cut-off year which is used when
 261 deciding whether or not to reject packages based on the file timestamp.
 262
 263 BXANotify (optional): a boolean (default: no); if true (Debian-specific)
 264 BXA notification is sent.  The template for the BXA notification is located
 265 in Dir::Templates/process-new.bxa_notification and should be changed if this
 266 option is set.
 267
 268 OverrideDisparityCheck (optional): a boolean (default: no); if true,
 269 dak process-unchecked compares an uploads section/priority with the overrides and whines
 270 at the maintainer if they differ.
 271
 272 CloseBugs (optional): a boolean (default: no); if true the automated bug
 273 closing feature of dinstall is activated.
 274
 275 QueueBuildSuites (optional): a list of suites which should be auto
 276 build.
 277
 278 QueueBuild is a boolean; if true it activates support
 279 for auto-building from accepted.
 280
 281 OverrideMaintainer (optional): be used to globally override the
 282 __MAINTAINER_TO__ and __MAINTAINER_FROM__ variables in template mails.
 283 Use with caution.
 284
 285 SkipTime (required): an integer value which is the number of seconds that a
 286 file must be older than (via it's last modified timestamp) before dak process-unchecked
 287 will REJECT rather than SKIP the package.
 288
 289 KeyAutoFetch (optional): boolean (default: false), which if set (and
 290 not overriden by explicit argument to check_signature()) will enable
 291 auto key retrieval.  Requires KeyServer and SigningKeyIds variables be
 292 set.  NB: you should only enable this variable on production systems
 293 if you have strict control of your upload queue.
 294
 295 KeyServer (optional): keyserver used for key auto-retrieval
 296 (c.f. KeyAutoFetch).
 297
 298 ================================================================================
 299
 300 Archive
 301 -------
 302
 303 Mandatory.  List of all archives, e.g.
 304
 305 | Archive
 306 | {
 307 |   ftp-master
 308 |   {
 309 |     OriginServer "ftp-master.debian.org";
 310 |     PrimaryMirror "ftp.debian.org";
 311 |     Description "Master Archive for the Debian project";
 312 |   };
 313 | };
 314
 315 OriginServer and PrimaryMirror (required): used 'dak rm's bug closing mail
 316 templates.  The host name and it's OriginServer and Description are part of
 317 the SQL database in the 'archive' table.
 318
 319 ================================================================================
 320
 321 Architectures
 322 -------------
 323
 324 Mandatory.  List of all architectures, e.g.
 325
 326 | Architectures
 327 | {
 328 |   source "Source";
 329 |   all    "Architecture Independent";
 330 |   i386   "Intel ia32";
 331 | };
 332
 333 Both values go into the SQL database's 'architecture' table.
 334 The description is currently unused.
 335
 336 ================================================================================
 337
 338 Component
 339 ---------
 340
 341 Mandatory.  List of all components, e.g.
 342
 343 | Component
 344 | {
 345 |   main
 346 |   {
 347 |       Description "Main";
 348 |       MeetsDFSG "true";
 349 |   };
 350 | };
 351
 352 All three values go into the SQL database's 'component' table.
 353 MeetsDFSG is currently unused.
 354
 355 ================================================================================
 356
 357 Section
 358 -------
 359
 360 Mandatory.  List of all valid sections, e.g.
 361
 362 | Section
 363 | {
 364 |   base;
 365 | };
 366
 367 The section goes into the 'section' table in SQL database.
 368
 369 ================================================================================
 370
 371 Priority
 372 --------
 373
 374 Mandatory.  List of all valid priorities, e.g.
 375
 376 | Priority
 377 | {
 378 |   required 1;
 379 |   important 2;
 380 |   standard 3;
 381 |   optional 4;
 382 |   extra 5;
 383 |   source 0; // i.e. unused
 384 | };
 385
 386 The value is the sorting key.  Both the section and it's sorting key
 387 go into the SQL database's 'priority' table.
 388
 389 ================================================================================
 390
 391 OverrideType
 392 ------------
 393
 394 Mandatory.  List of al valid override types, e.g.
 395
 396 | OverrideType
 397 | {
 398 |   deb;
 399 |   dsc;
 400 |   udeb;
 401 | };
 402
 403 The type goes into the 'override_type' table in the SQL database.
 404
 405 ================================================================================
 406
 407 Location
 408 --------
 409
 410 Mandatory.  List all locations, e.g.
 411
 412 | Location
 413 | {
 414 |   /org/ftp.debian.org/ftp/pool/
 415 |     {
 416 |       Archive "ftp-master";
 417 |       Type "pool";
 418 |       Suites
 419 |       {
 420 |         Stable;
 421 |         Unstable;
 422 |       };
 423 |     };
 424 | };
 425
 426 There are three valid values for 'Type': 'legacy', 'legacy-mixed' and
 427 'pool'.  'legacy' and 'pool' are assumed to have sections for all
 428 components listed in the Components section 'legacy-mixed' are assumed
 429 to mix all components into one location.  The 'Archive' and 'Type'
 430 sections go into the SQL database's 'location' table.  'Suites' is a
 431 list of existent suites that should be used to populate the SQL
 432 database.
 433
 434 Note that the archive value specified here must correspond to one defined
 435 in Archive.
 436
 437 [Note: yes, this is horrible, it dates back to the original `import
 438        the existent archive into the SQL Database' script ('dak import-archive') and
 439        isn't otherwise used.  It should be revisted at some stage.]
 440
 441 ================================================================================
 442
 443 Urgency
 444 -------
 445
 446 Mandatory.
 447
 448 | Urgency
 449 | {
 450 |   Default "low";
 451 |   Valid
 452 |   {
 453 |     low;
 454 |     medium;
 455 |     high;
 456 |     emergency;
 457 |     critical;
 458 |   };
 459 | };
 460
 461 This defines the valid and default urgency of an upload.  If a package is
 462 uploaded with an urgency not listed here, it will be rejected.
 463
 464 ================================================================================