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