5 files changed, 50 insertions, 3 deletions

diff --git a/src/mailman/commands/cli_info.py b/src/mailman/commands/cli_info.py
index 4909ca00c..cc4f6fe5e 100644
--- a/src/mailman/commands/cli_info.py
+++ b/src/mailman/commands/cli_info.py
@@ -69,7 +69,7 @@ class Info:
         print('Python', sys.version, file=output)
         print('config file:', config.filename, file=output)
         print('db url:', config.db.url, file=output)
-        print('devmode:', 
+        print('devmode:',
               'ENABLED' if as_boolean(config.devmode.enabled) else 'DISABLED',
               file=output)
         print('REST root url:', path_to('/'), file=output)
diff --git a/src/mailman/commands/docs/info.rst b/src/mailman/commands/docs/info.rst
index 59801f234..2a5e691ae 100644
--- a/src/mailman/commands/docs/info.rst
+++ b/src/mailman/commands/docs/info.rst
@@ -54,7 +54,8 @@ system paths that Mailman is using.
     >>> cleanups.append((config.pop, 'fhs'))
     >>> config.create_paths = True
 
-The File System Hierarchy layout is the same every by definition.
+The `Filesystem Hierarchy Standard`_ layout is the same everywhere by
+definition.
 
     >>> command.process(args)
     GNU Mailman 3...
@@ -75,3 +76,6 @@ The File System Hierarchy layout is the same every by definition.
         QUEUE_DIR                = /var/spool/mailman
         TEMPLATE_DIR             = .../mailman/templates
         VAR_DIR                  = /var/lib/mailman
+
+
+.. _`Filesystem Hierarchy Standard`: http://www.pathname.com/fhs/
diff --git a/src/mailman/config/config.py b/src/mailman/config/config.py
index 7249c6d92..74931c029 100644
--- a/src/mailman/config/config.py
+++ b/src/mailman/config/config.py
@@ -31,6 +31,7 @@ import os
 import sys
 
 from ConfigParser import SafeConfigParser
+from flufl.lock import Lock
 from lazr.config import ConfigSchema, as_boolean
 from pkg_resources import resource_filename, resource_stream, resource_string
 from string import Template
@@ -50,6 +51,21 @@ from mailman.utilities.modules import call_name
 
 SPACE = ' '
 
+MAILMAN_CFG_TEMPLATE = """\
+# AUTOMATICALLY GENERATED BY MAILMAN ON {}
+#
+# This is your GNU Mailman 3 configuration file.  You can edit this file to
+# configure Mailman to your needs, and Mailman will never overwrite it.
+# Additional configuration information is (for now) available in the
+# schema.cfg file <http://tinyurl.com/cm5rtqe> and the base mailman.cfg file
+# <http://tinyurl.com/dx9b8eg>.
+#
+# For example, uncomment the following lines to run Mailman in developer mode.
+#
+# [devmode]
+# enabled: yes
+# recipient: your.address@your.domain"""
+
 
 
 @implementer(IConfiguration)
@@ -211,6 +227,19 @@ class Configuration:
         if self.create_paths:
             for variable, directory in self.paths.items():
                 makedirs(directory)
+            # Avoid circular imports.
+            from mailman.utilities.datetime import now
+            # Create a mailman.cfg template file if it doesn't already exist.
+            # LBYL: <boo hiss>, but it's probably okay because the directories
+            # likely didn't exist before the above loop, and we'll create a
+            # temporary lock.
+            lock_file = os.path.join(self.LOCK_DIR, 'mailman-cfg.lck')
+            mailman_cfg = os.path.join(self.ETC_DIR, 'mailman.cfg')
+            with Lock(lock_file):
+                if not os.path.exists(mailman_cfg):
+                    with open(mailman_cfg, 'w') as fp:
+                        print(MAILMAN_CFG_TEMPLATE.format(
+                            now().replace(microsecond=0)), file=fp)
 
     @property
     def runner_configs(self):
diff --git a/src/mailman/core/initialize.py b/src/mailman/core/initialize.py
index 4c02df53a..2e5a4238f 100644
--- a/src/mailman/core/initialize.py
+++ b/src/mailman/core/initialize.py
@@ -68,7 +68,13 @@ def search_for_configuration_file():
     # ./mailman.cfg
     config_path = os.path.abspath('mailman.cfg')
     if os.path.exists(config_path):
-        return os.path.abspath(config_path)
+        return config_path
+    # As a special case, look in ./var/etc/mailman.cfg.  We can't do this in
+    # the Configuration.load() method because that depends on the
+    # configuration system, which of course is not set up at that time!
+    config_path = os.path.abspath(os.path.join('var', 'etc', 'mailman.cfg'))
+    if os.path.exists(config_path):
+        return config_path
     # ~/.mailman.cfg
     config_path = os.path.join(os.getenv('HOME'), '.mailman.cfg')
     if os.path.exists(config_path):
diff --git a/src/mailman/docs/NEWS.rst b/src/mailman/docs/NEWS.rst
index 47998fbab..eb946a9ca 100644
--- a/src/mailman/docs/NEWS.rst
+++ b/src/mailman/docs/NEWS.rst
@@ -19,6 +19,14 @@ Bugs
  * Creation of lists with upper case names should be coerced to lower case.
    (LP: #1117176)
 
+Configuration
+-------------
+ * When creating the initial file system layout in ``var``, e.g. via
+   ``bin/mailman info``, add an ``var/etc/mailman.cfg`` file if one does not
+   already exist.  Also, when initializing the system, look for that file as
+   the configuration file, just after ``./mailman.cfg`` and before
+   ``~/.mailman.cfg``.  (LP: #1157861)
+
 
 3.0 beta 3 -- "Here Again"
 ==========================