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