]> git.decadent.org.uk Git - dak.git/blob - docs/README.config
dak/control_suite.py (main): Handle SystemError exception in case of a incompatible...
[dak.git] / 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 (requried): used by 'dak rm' when carbon-copying a bug
247 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 ================================================================================