]> err.no Git - dak/commitdiff
Update example configuration file
authorMark Hymers <mhy@debian.org>
Thu, 28 Jul 2011 06:57:15 +0000 (07:57 +0100)
committerMark Hymers <mhy@debian.org>
Thu, 28 Jul 2011 06:57:15 +0000 (07:57 +0100)
Signed-off-by: Mark Hymers <mhy@debian.org>
docs/README.config

index a6b71206056e6142b457944cd8c60854498196cc..760427e1f4510907740c9c6c7fd8253883c6bf92 100644 (file)
-Explanation of configuration files options for dak
-==================================================
+///////////////////////////////////////////////////////////
+// Example annotated configuration file for dak
+///////////////////////////////////////////////////////////
 
+///////////////////////////////////////////////////////////
+// Essential.  List of database details.
+///////////////////////////////////////////////////////////
 DB
---
-
-Essential.  List of database details, e.g.
-
-| DB
-| {
-|   Name "projectb";
-|   Host ""; 
-|   Port -1;
-| };
-
-Name (required): The name of the PostgreSQL database which has been created
-for dak.
-
-Host (required): The name of the host on which the database is located.  If
-the database is local, Host should be blank.
-
-Port (required): The port of the database.  If the port is the default
-value (5432), this option should be set to -1.
-
-================================================================================
-
+{
+    //// Name (required): The name of the PostgreSQL database which has been
+    //// created for dak.
+    Name "projectb";
+
+    //// Host (optional): The name of the host on which the database is located.
+    //// Not necessary if the the database is local.
+    //Host "";
+
+    //// Port (optional): The port of the database if it is remote.  If the port
+    //// is the default value (5432), this option can be set to -1.
+    //Port -1;
+
+    //// PoolSize (optional): should be at least ThreadCount + 1
+    PoolSize 5;
+
+    //// MaxOverflow (optional): shouldn't exceed postgresql.conf's
+    //// max_connections - PoolSize
+    MaxOverflow 13;
+
+    //// Unicode (optional but seriously suggested).  Should be false for
+    //// encoding == SQL_ASCII which is highly recommended.  Do not set this to
+    //// anything else unless you really know what you're doing.
+    Unicode "false";
+};
+
+///////////////////////////////////////////////////////////
+// Common settings
+///////////////////////////////////////////////////////////
+Common
+{
+    //// ThreadCount (optional):  Maximum number of threads to use.  Defaults to 1
+    ThreadCount 1;
+};
+
+///////////////////////////////////////////////////////////
+// Dinstall general settings
+///////////////////////////////////////////////////////////
+Dinstall
+{
+    //// SigningKeyring (optional): this is the private keyring used by
+    //// 'dak generate-releases'.
+    SigningKeyring "/srv/dak/s3kr1t/dot-gnupg/secring.gpg";
+
+    //// SigningPubKeyring (optional): this is the public keyring used by
+    //// 'dak generate-releases'.
+    SigningPubKeyring "/srv/dak/s3kr1t/dot-gnupg/pubring.gpg";
+
+    //// Options::No-Mail (optional): Highly recommended.  This prevents dak
+    //// from spamming people you didn't mean it to.  If you're not using this,
+    //// you almost certainly want to use the MailWhiteList option
+    Options::No-Mail "true";
+
+    //// MailWhiteList (optional).  If you're not using No-Mail, this provides
+    //// a list of email addresses or regular expressions, one per line which
+    //// dak is allowed to email.  Regular expressions need to be prefixed by "RE:".
+    //// Examples: "jane.doe@domain.com" or "RE:jane[^@]@domain.com", where the first will
+    //// only allow to mail jane.doe@domain.com while the second will mail all of jane*@domain.com
+    //// MailWhiteList "/some/path/to/a/file";
+
+    //// SendmailCommand (required unless No-Mail is set): command to call the MTA.
+    // SendmailCommand "/usr/sbin/sendmail -oi -t";
+
+    //// MyEmailAddress (required): this is used as the From: line for sending mails
+    //// as a script/daemon.
+    MyEmailAddress "FTP Masters <ftpmaster@example.org>";
+
+    //// MyAdminAddress (required): used as a contact address in mails.
+    MyAdminAddress "ftpmaster@example.org";
+
+    //// MyDistribution (required): this variable is used in emails sent out by
+    //// dak and others.  It should indicate the name of the distribution.
+    MyDistribution "MyDistro";
+
+    //// BugServer (optional): is used by 'dak process-upload' and 'dak rm'
+    //// when closing bugs.
+    // BugServer "bugs.example.org";
+
+    //// CloseBugs (optional): a boolean (default: no); if true the automated bug
+    //// closing feature of dinstall is activated.  Must have BugServer set
+    //// for this to work.
+    CloseBugs "true";
+
+    //// PackagesServer (optional): used by 'dak rm' and 'dak override' when
+    //// carbon-copying a bug close mail to a package maintainer.
+    // PackagesServer "packages.example.org";
+
+    //// TrackingServer (optional): used by 'dak process-upload' and 'dak
+    //// rm' to send messages for the maintainer also to an alias for people
+    //// tracking a specific source package.
+    // TrackingServer "packages.qa.example.org";
+
+    //// All sent mail is blind carbon copied to the email address in Bcc if it's
+    //// not blank.
+    // Bcc "archive@example.org";
+
+    //// BXANotify (optional): a boolean (default: false); if true (Debian-specific)
+    //// BXA notification is sent.  The template for the BXA notification is located
+    //// in Dir::Templates/process-new.bxa_notification and should be changed if this
+    //// option is set.
+    // BXANotify "true";
+
+    //// FutureTimeTravelGrace (required): specifies how many seconds into the
+    //// future timestamps are allowed to be inside a deb before being rejected.
+    //// 28800 = 8 hours
+    FutureTimeTravelGrace 28800;
+
+    //// PastCutoffYear (required): specifies the cut-off year which is used when
+    //// deciding whether or not to reject packages based on the file timestamp.
+    PastCutoffYear "1984";
+
+    //// SkipTime (required): an integer value which is the number of seconds
+    //// that a file must be older than (via it's last modified timestamp)
+    //// before dak process-upload will REJECT rather than SKIP the package.
+    SkipTime 300;
+
+    //// OverrideDisparityCheck (optional): a boolean (default: false); if true,
+    //// dak process-upload compares an uploads section/priority with the overrides and whines
+    //// at the maintainer if they differ.
+    OverrideDisparityCheck "false";
+
+    //// OverrideMaintainer (optional): be used to globally override the
+    //// __MAINTAINER_TO__ and __MAINTAINER_FROM__ variables in template mails.
+    //// Use with caution.
+    // OverrideMaintainer "";
+
+    //// DefaultSuite (optional): which suite to default to where one isn't
+    //// specified.  Defaults to "unstable" if not set.
+    // DefaultSuite "unstable";
+
+    //// LintianTags (optional): A set of lintian tags on which to reject
+    //// packages at upload time.  Format is a YAML file; see the ftp-master
+    //// version for an example.
+    // LintianTags "/srv/dak/dak/config/debian/lintian.tags";
+
+    //// ReleaseTransitions (optional): YAML File for blocking uploads to unstable
+    // ReleaseTransitions "/srv/dak/web/transitions.yaml";
+
+    //// KeyAutoFetch (optional): boolean (default: false), which if set (and
+    //// not overriden by explicit argument to check_signature()) will enable
+    //// auto key retrieval.  Requires KeyServer and SigningKeyIds variables be
+    //// set.  NB: you should only enable this variable on production systems
+    //// if you have strict control of your upload queue.
+    // KeyAutoFetch "false";
+
+    //// KeyServer (optional): keyserver used for key auto-retrieval
+    //// (c.f. KeyAutoFetch).
+    // KeyServer "wwwkeys.eu.pgp.net";
+};
+
+
+///////////////////////////////////////////////////////////
+// Dir (mandatory).  List of directory locations, e.g.
+///////////////////////////////////////////////////////////
 Dir
----
-
-Mandatory.  List of directory locations, e.g.
-
-| Dir
-| {
-|   Root "/org/ftp.debian.org/ftp/";
-|   Pool "/org/ftp.debian.org/ftp/pool/";
-|   Templates "/org/ftp.debian.org/dak/templates/";
-|   PoolRoot "pool/";
-|   Override "/org/ftp.debian.org/scripts/override/";
-|   Lists "/org/ftp.debian.org/database/dists/";
-|   Log "/org/ftp.debian.org/log/";
-|   Morgue "/org/ftp.debian.org/morgue/";
-|   QueueBuild "/org/incoming.debian.org/buildd/";
-|   UrgencyLog "/org/ftp.debian.org/testing/urgencies/";
-|   Queue
-|   {  
-|     Accepted "/org/ftp.debian.org/queue/accepted/";
-|     Byhand "/org/ftp.debian.org/queue/byhand/";
-|     Done "/org/ftp.debian.org/queue/done/";
-|     Holding "/org/ftp.debian.org/queue/holding/";
-|     New "/org/ftp.debian.org/queue/new/";
-|     Reject "/org/ftp.debian.org/queue/reject/";
-|     Unchecked "/org/ftp.debian.org/queue/unchecked/";
-|   };
-| };
-
-Root (required): Specifies the path of the root of the FTP archive.
-
-Pool (required): This variable specifies the path of the pool
-directory.  Debian packages will be placed in the pool by 'dak
-process-accepted' after they have been accepted by dak
-process-unchecked.
-
-Templates (required): dak sends various mails and uses templates from
-this directory.
-
-PoolRoot (required): This variable specifies the basename of the pool
-directory.
-
-Override (optional): This directory optionally stores override files (used
-by 'dak make-overrides').
-
-Lists (optional): This directory holds file lists used by apt-ftparchive to
-generate Packages and Sources files (used by 'dak make-suite-file-list').
-
-Log (required): Log files are put in this directory.
-
-Morgue (required): Removed files are moved there.  The morgue has various
-sub-directories, including (optionally) those defined by
-Clean-Queues::MorgueSubDir and Clean-Suites::MorgueSubDir.
-
-UrgencyLog (optional): If this directory is specified, 'dak
-process-accepted' will store the urgency value of each upload.  This
-is mainly used for britney (the testing script).
-
-Queue (required): This sub-tree defines important directories for the
-incoming queue.  The following variables have to be set: Accepted, Byhand
-Done, Holding, New, Reject, Unchecked.  An explanation of the function of
-these directores can be found in README.new-incoming.
-
-Queue::BTSVersionTrack (optional): this directory holds the DebBugs
-Version Tracking support files.
-
-================================================================================
-
-Suite
------
-
-Mandatory.  List of all suites, e.g. 
-
-| Suite
-| {
-|   Unstable
-|   {
-|      Components 
-|      {
-|        main;
-|      };
-|      Architectures 
-|      {
-|        source; 
-|        all;
-|        i386;
-|      };
-|      Announce "debian-devel-changes@lists.debian.org";
-|      Origin "Debian";
-|      Description "Debian Unstable - Not Released";
-|      CodeName "sid";
-|      OverrideCodeName "sid";
-|      Priority "5";
-|   };
-| };
-
-Announce (optional): controls where "Installed foo" mails are sent.
-
-CodeName, Origin and Description (optional): This settings are used by
-'dak generate-releases' and put in the Release files.
-
-OverrideCodeName (optional): used by 'dak make-overrides'.
-
-Priority (optional) determines which suite is used for the Maintainers file
-as generated by 'dak make-maintainers' (highest wins).
-
-CopyChanges (optional): if this variable is present it should be a path
-into the archive (i.e. "Dir::RootDir"); any upload targeted for a suite
-with this config option present will have the .changes file copied into
-that path.
-
-CopyDotDak (optional): if this is present it should be an absolute path; any
-upload targeted for a suite with this config option present will have the
-.dak file copied into that path.  This option is similar to CopyChanges
-and will most often be used with it; they're seperate because .changes
-files are mirrored and .dak files aren't, so the paths will usually be
-different.
-
-There are more optional variables, such as VersionChecks.  Please see
-dak.conf for examples.
-
-================================================================================
+{
+    //// Root (required): Specifies the path of the root of the FTP archive.
+    Root "/srv/dak/ftp/";
+
+    //// Pool (required): This variable specifies the path of the pool
+    //// directory.  Debian packages will be placed in the pool by
+    //// 'dak process-upload'
+    Pool "/srv/dak/ftp/pool/";
+
+    //// Templates (required): dak sends various mails and uses templates from
+    //// this directory.
+    Templates "/srv/dak/dak/templates/";
+
+    //// Override (optional): This directory optionally stores override files (used
+    //// by 'dak make-overrides').
+    // Override "/src/dak/scripts/override/";
+
+    //// Lists (optional): This directory holds file lists used by apt-ftparchive to
+    //// generate Packages and Sources files (used by 'dak make-suite-file-list').
+    //// Deprecated in favour of use of generate-packages-sources2
+    // Lists "/srv/dak/database/dists/";
+
+    //// Log (required): Directory to store dak logs in
+    Log "/srv/dak/log/";
+
+    //// Morgue (required): Removed files are moved there.  The morgue has various
+    //// sub-directories, including (optionally) those defined by
+    //// Clean-Queues::MorgueSubDir and Clean-Suites::MorgueSubDir.
+    Morgue "/srv/dak/morgue/";
+
+    //// UrgencyLog (optional): If this directory is specified, 'dak
+    //// process-upload' will store the urgency value of each upload.  This
+    //// is mainly used for britney (the testing script).
+    // UrgencyLog "/srv/dak/testing/urgencies/";
+
+    //// Holding (required): Directory to use for temporary storage during
+    //// process-upload
+    Holding "/srv/dak/queue/holding/";
+
+    //// Done (required): Directory in which to store processed .changes files
+    Done "/srv/dak/queue/done/";
+
+    //// BTSVersionTrack (optional): this directory holds the DebBugs
+    //// Version Tracking support files.
+    // BTSVersionTrack "/srv/dak/btsversiontrack";
+
+    //// Queue (required): This sub-tree defines important directories for the
+    //// incoming queue.  The following variables have to be set: Byhand, New
+    //// NewStage, Reject, Unchecked.  An explanation of the function of
+    //// these directores can be found in README.new-incoming.
+    Queue
+    {  
+        Byhand "/srv/dak/queue/byhand/";
+        New "/srv/dak/queue/new/";
+        NewStage "/srv/dak/queue/newstage/";
+        Reject "/srv/dak/queue/reject/";
+        Unchecked "/srv/dak/queue/unchecked/";
+    };
+};
+
+///////////////////////////////////////////////////////////
+// SuiteMappings: (optional).  List of mappings for the Distribution file in a
+// .changes file, e.g.:
+///////////////////////////////////////////////////////////
+
+// There are three mapping types:
+//
+// (1) map <source> <dest>
+// Any target suite of '<source>' is unconditionally overriden to '<dest>'.
+// (2) map-unreleased <source> <dest>
+// Any upload targeted for suite '<source>' will be mapped to '<dest>' iff it
+// contains uploads for an architecture that is not part of '<source>'.
+// (3) ignore <suite>
+// Any target suite of '<suite>' is unconditionally removed from the list of
+// target suites.  NB: if the upload had only one target suite this will lead
+// to rejection.
 
 SuiteMappings
--------------
-
-Optional.  List of mappings for the Distribution file in a .changes file, e.g.:
-
-| SuiteMappings
-| {
-|    "map stable proposed-updates";
-|    "map frozen unstable";
-|    "map-unreleased stable unstable";
-|    "map-unreleased proposed-updates unstable";
-|    "ignore testing";
-| };
-
-There are three mapping types:
-
-(1) map <source> <dest>
-
-      Any target suite of '<source>' is unconditionally overriden to
-      '<dest>'.
-
-(2) map-unreleased <source> <dest>
-
-      Any upload targeted for suite '<source>' will be mapped to
-      '<dest>' iff it contains uploads for an architecture that is not
-      part of '<source>'.
-
-(3) ignore <suite>
-
-      Any target suite of '<suite>' is unconditionally removed from
-      the list of target suites.  NB: if the upload had only one
-      target suite this will lead to rejection.
-
-NB: ordering is not guaranteed.
-
-================================================================================
-
-Dinstall
---------
-
-Mandatory.  List of dinstall options, e.g.:
-
-| Dinstall
-| {
-|    SigningKeyring "/org/ftp.debian.org/s3kr1t/dot-gnupg/secring.gpg";
-|    SendmailCommand "/usr/sbin/sendmail -odq -oi -t";
-|    MyEmailAddress "Debian Installer <installer@ftp-master.debian.org>";
-|    MyAdminAddress "ftpmaster@debian.org";
-|    MyDistribution "Debian";
-|    BugServer "bugs.debian.org";
-|    PackagesServer "packages.debian.org";
-|    TrackingServer "packages.qa.debian.org";
-|    LockFile "/org/ftp.debian.org/dak/lock";
-|    Bcc "archive@ftp-master.debian.org";
-|    FutureTimeTravelGrace 28800; // 8 hours
-|    PastCutoffYear "1984";
-|    BXANotify "false";
-| };
-
-SigningKeyring (optional): this is the private keyring used by 'dak
-generate-releases'.
-
-SendmailCommand (required): command to call the MTA.
-
-MyEmailAddress (required): this is used as the From: line for sending mails
-as a script/daemon.
-
-MyAdminAddress (required): used as a contact address in mails.
-
-MyDistribution (required): this variable is used in emails sent out by
-dak and others.  It should indicate the name of the distribution.
-
-BugServer (required): is used by 'dak process-unchecked' and 'dak rm'
-when closing bugs.
-
-PackagesServer (required): used by 'dak rm' and 'dak override' when
-carbon-copying a bug close mail to a package maintainer.
-
-TrackingServer (optional): used by 'dak process-unchecked' and 'dak
-rm' to send messages for the maintainer also to an alias for people
-tracking a specific source package.
-
-LockFile (required): contains the filename of the lockfile used by dinstall
-when in action mode (i.e. not using -n/--no-action).
-
-All sent mail is blind carbon copied to the email address in Bcc if it's
-not blank.
-
-FutureTimeTravelGrace (required): specifies how many seconds into the
-future timestamps are allowed to be inside a deb before being rejected.
-
-PastCutoffYear (required): specifies the cut-off year which is used when
-deciding whether or not to reject packages based on the file timestamp.
-
-BXANotify (optional): a boolean (default: no); if true (Debian-specific)
-BXA notification is sent.  The template for the BXA notification is located
-in Dir::Templates/process-new.bxa_notification and should be changed if this
-option is set.
-
-OverrideDisparityCheck (optional): a boolean (default: no); if true,
-dak process-unchecked compares an uploads section/priority with the overrides and whines
-at the maintainer if they differ.
-
-CloseBugs (optional): a boolean (default: no); if true the automated bug
-closing feature of dinstall is activated.
-
-QueueBuild is a boolean; if true it activates support
-for auto-building from accepted.
-
-OverrideMaintainer (optional): be used to globally override the
-__MAINTAINER_TO__ and __MAINTAINER_FROM__ variables in template mails.
-Use with caution.
-
-SkipTime (required): an integer value which is the number of seconds that a
-file must be older than (via it's last modified timestamp) before dak process-unchecked
-will REJECT rather than SKIP the package.
-
-KeyAutoFetch (optional): boolean (default: false), which if set (and
-not overriden by explicit argument to check_signature()) will enable
-auto key retrieval.  Requires KeyServer and SigningKeyIds variables be
-set.  NB: you should only enable this variable on production systems
-if you have strict control of your upload queue.
-
-KeyServer (optional): keyserver used for key auto-retrieval
-(c.f. KeyAutoFetch).
-
-================================================================================
-
-Archive
--------
-
-Mandatory.  List of all archives, e.g.
-
-| Archive
-| {
-|   ftp-master
-|   {
-|     OriginServer "ftp-master.debian.org";
-|     PrimaryMirror "ftp.debian.org";
-|     Description "Master Archive for the Debian project";
-|   };
-| };
-
-OriginServer and PrimaryMirror (required): used 'dak rm's bug closing mail
-templates.  The host name and it's OriginServer and Description are part of
-the SQL database in the 'archive' table.
-
-================================================================================
-
-Architectures
--------------
-
-Mandatory.  List of all architectures, e.g.
-
-| Architectures
-| {
-|   source "Source";
-|   all           "Architecture Independent";
-|   i386   "Intel ia32";
-| };
-
-Both values go into the SQL database's 'architecture' table.
-The description is currently unused.
-
-================================================================================
-
-Section
--------
-
-Mandatory.  List of all valid sections, e.g.
-
-| Section
-| {
-|   base;
-| };
-
-The section goes into the 'section' table in SQL database.
-
-================================================================================
-
-Priority
---------
-
-Mandatory.  List of all valid priorities, e.g.
-
-| Priority
-| {
-|   required 1;
-|   important 2;
-|   standard 3;
-|   optional 4;
-|   extra 5;
-|   source 0; // i.e. unused
-| };
-
-The value is the sorting key.  Both the section and it's sorting key
-go into the SQL database's 'priority' table.
-
-================================================================================
-
-Location
---------
-
-Mandatory.  List all locations, e.g.
-
-| Location
-| {
-|   /org/ftp.debian.org/ftp/pool/
-|     {
-|       Archive "ftp-master";
-|       Type "pool";
-|      Suites
-|      {
-|        Stable;
-|        Unstable;
-|      };
-|     };
-| };
-
-There are three valid values for 'Type': 'legacy', 'legacy-mixed' and
-'pool'.  'legacy' and 'pool' are assumed to have sections for all
-components listed in the Components section 'legacy-mixed' are assumed
-to mix all components into one location.  The 'Archive' and 'Type'
-sections go into the SQL database's 'location' table.  'Suites' is a
-list of existent suites that should be used to populate the SQL
-database.
-
-Note that the archive value specified here must correspond to one defined
-in Archive.
-
-[Note: yes, this is horrible, it dates back to the original `import
-       the existent archive into the SQL Database' script ('dak import-archive') and
-       isn't otherwise used.  It should be revisted at some stage.]
-
-================================================================================
+{
+   "map stable proposed-updates";
+   "map frozen unstable";
+   "map-unreleased stable unstable";
+   "map-unreleased proposed-updates unstable";
+   "ignore testing";
+};
+
+///////////////////////////////////////////////////////////
+// Urgency (mandatory) This defines the valid and default urgency of an upload.
+// If a package is uploaded with an urgency not listed here, it will be
+// rejected.
+///////////////////////////////////////////////////////////
 
 Urgency
--------
-
-Mandatory.
-
-| Urgency
-| {
-|   Default "low";
-|   Valid
-|   {
-|     low;
-|     medium;
-|     high;
-|     emergency;
-|     critical;
-|   };
-| };
-
-This defines the valid and default urgency of an upload.  If a package is
-uploaded with an urgency not listed here, it will be rejected.
-
-================================================================================
+{
+  Default "low";
+  Valid
+  {
+    low;
+    medium;
+    high;
+    emergency;
+    critical;
+  };
+};
+