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 ================================================================================
 295
 296 Archive
 297 -------
 298
 299 Mandatory.  List of all archives, e.g.
 300
 301 | Archive
 302 | {
 303 |   ftp-master
 304 |   {
 305 |     OriginServer "ftp-master.debian.org";
 306 |     PrimaryMirror "ftp.debian.org";
 307 |     Description "Master Archive for the Debian project";
 308 |   };
 309 | };
 310
 311 OriginServer and PrimaryMirror (required): used 'dak rm's bug closing mail
 312 templates.  The host name and it's OriginServer and Description are part of
 313 the SQL database in the 'archive' table.
 314
 315 ================================================================================
 316
 317 Architectures
 318 -------------
 319
 320 Mandatory.  List of all architectures, e.g.
 321
 322 | Architectures
 323 | {
 324 |   source "Source";
 325 |   all    "Architecture Independent";
 326 |   i386   "Intel ia32";
 327 | };
 328
 329 Both values go into the SQL database's 'architecture' table.
 330 The description is currently unused.
 331
 332 ================================================================================
 333
 334 Component
 335 ---------
 336
 337 Mandatory.  List of all components, e.g.
 338
 339 | Component
 340 | {
 341 |   main
 342 |   {
 343 |       Description "Main";
 344 |       MeetsDFSG "true";
 345 |   };
 346 | };
 347
 348 All three values go into the SQL database's 'component' table.
 349 MeetsDFSG is currently unused.
 350
 351 ================================================================================
 352
 353 Section
 354 -------
 355
 356 Mandatory.  List of all valid sections, e.g.
 357
 358 | Section
 359 | {
 360 |   base;
 361 | };
 362
 363 The section goes into the 'section' table in SQL database.
 364
 365 ================================================================================
 366
 367 Priority
 368 --------
 369
 370 Mandatory.  List of all valid priorities, e.g.
 371
 372 | Priority
 373 | {
 374 |   required 1;
 375 |   important 2;
 376 |   standard 3;
 377 |   optional 4;
 378 |   extra 5;
 379 |   source 0; // i.e. unused
 380 | };
 381
 382 The value is the sorting key.  Both the section and it's sorting key
 383 go into the SQL database's 'priority' table.
 384
 385 ================================================================================
 386
 387 OverrideType
 388 ------------
 389
 390 Mandatory.  List of al valid override types, e.g.
 391
 392 | OverrideType
 393 | {
 394 |   deb;
 395 |   dsc;
 396 |   udeb;
 397 | };
 398
 399 The type goes into the 'override_type' table in the SQL database.
 400
 401 ================================================================================
 402
 403 Location
 404 --------
 405
 406 Mandatory.  List all locations, e.g.
 407
 408 | Location
 409 | {
 410 |   /org/ftp.debian.org/ftp/pool/
 411 |     {
 412 |       Archive "ftp-master";
 413 |       Type "pool";
 414 |       Suites
 415 |       {
 416 |         Stable;
 417 |         Unstable;
 418 |       };
 419 |     };
 420 | };
 421
 422 There are three valid values for 'Type': 'legacy', 'legacy-mixed' and
 423 'pool'.  'legacy' and 'pool' are assumed to have sections for all
 424 components listed in the Components section 'legacy-mixed' are assumed
 425 to mix all components into one location.  The 'Archive' and 'Type'
 426 sections go into the SQL database's 'location' table.  'Suites' is a
 427 list of existent suites that should be used to populate the SQL
 428 database.
 429
 430 Note that the archive value specified here must correspond to one defined
 431 in Archive.
 432
 433 [Note: yes, this is horrible, it dates back to the original `import
 434        the existent archive into the SQL Database' script ('dak import-archive') and
 435        isn't otherwise used.  It should be revisted at some stage.]
 436
 437 ================================================================================
 438
 439 Urgency
 440 -------
 441
 442 Mandatory.
 443
 444 | Urgency
 445 | {
 446 |   Default "low";
 447 |   Valid
 448 |   {
 449 |     low;
 450 |     medium;
 451 |     high;
 452 |     emergency;
 453 |     critical;
 454 |   };
 455 | };
 456
 457 This defines the valid and default urgency of an upload.  If a package is
 458 uploaded with an urgency not listed here, it will be rejected.
 459
 460 ================================================================================