From 91d952c29321c925201766365bd9fb44e5ca0d38 Mon Sep 17 00:00:00 2001
From: nd <git@notandy.de>
Date: Fri, 12 Mar 2021 23:11:44 +0100
Subject: [PATCH] added readme

---
 README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..73c2cba
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# Mailman (3)
+
+## Parameters and defaults
+
+
+All configuration is to be placed inside the `mailman` dict.
+
+```
+# mail address for the site owner
+site_owner: changeme@example.com
+
+# domain used for lists
+default_domain: example.com
+
+# all settings regarding the mailman api
+api:
+	# settings for listen addresses
+	hostname: localhost
+	port: 8001
+	# api version to use, only "3.1" was tested
+	version: "3.1"
+	# api account setting
+	admin:
+		# should not be changed
+		name: restadmin
+		pw: "{{ lookup('password', '/dev/null length=32') }}"
+
+# webinterface settings
+web:
+	# django secret key
+	secretkey: "{{ lookup('password', '/dev/null length=128') }}"
+	# activate remote auth in django
+	remote_user: False
+	# enable signup
+	signup: True
+	# allow users to change their password
+	change_pw: True
+	# dict with ldap settings or "False" to disable
+	ldap: False
+		# Ldap server url. Can  be ldap:// or ldaps://
+#		url: "ldaps://example.com"
+		# enable account and list membership sync. Membership sync musst be explicitly configured per list
+#		sync: true
+		# use a bind user to connect to the ldap. If it is not specified, sync will not work.
+#		bind_dn: "cn=mailman,ou=system,dc=example,dc=com"
+#		bind_password: "{{ lookup('passwordstore', '/dev/null length=64 nosymbols=true') }}"
+		# LDAP Search to find all groups. See https://django-auth-ldap.readthedocs.io/en/latest/
+#		group_search: 'LDAPSearch("ou=groups,dc=example,dc=com", ldap.SCOPE_ONELEVEL, "(objectClass=groupOfUniqueNames)")'
+#		group_type: 'GroupOfUniqueNamesType()'
+		# a search that musst return **all** users and select the attribute containing the user name. Only used for ldap sync
+#		user_search_all_name: 'LDAPSearch("ou=users,dc=cccv,dc=de", ldap.SCOPE_ONELEVEL, "(&(objectClass=posixAccount)(memberOf=cn=service_mailman_access,ou=groups,dc=cccv,dc=de))", ["uid"])'
+		# see https://django-auth-ldap.readthedocs.io/en/latest/
+#		user_filter: 'uid=%(user)s,ou=users,dc=cccv,dc=de'
+		# optionaly set a ca cert or other connection settings
+#		options: "{ ldap.OPT_X_TLS_CACERTFILE: '/etc/ssl/myfancy.ca', ldap.OPT_X_TLS_REQUIRE_CERT: True, ldap.OPT_X_TLS_NEWCTX: 0 }"
+		# map django roles
+#		mappings:
+#			"is_active": "cn=service_mailman_access,ou=groups,dc=example,dc=com"
+#			"is_staff": "cn=service_mailman_admin,ou=groups,dc=example,dc=com"
+#			"is_superuser": "cn=service_mailman_admin,ou=groups,dc=example,dc=com"
+#		group_require: "cn=service_mailman_access,ou=groups,dc=example,dc=com"
+	# logged in session timeout in seconds
+	session_timeout: 3600
+
+# hypperkitty settings
+archiver:
+	# api key
+	key: "{{ lookup('password', '/dev/null length=128') }}"
+
+# default settings used for all lists
+list_defaults:
+	# Mailman settings to set for this list. See https://docs.mailman3.org/projects/mailmanclient/en/latest/_modules/mailmanclient/restobjects/settings.html#Settings
+	settings: {}
+	# ldap sync settings
+	ldap:
+		member:
+			# enable syncing for this role type
+			enabled: False
+			# basedn to search
+			dn: "ou=users,dc=example,dc=com"
+			# ldap filter to use
+			filter: "(&(objectClass=posixAccount)(memberOf=cn=my_fancy_list,ou=groups,dc=example,dc=com))"
+			# attribute to read the user name from
+			username_attr: "uid"
+		moderator: # see **member** description
+		owner: # see **member** description
+
+# Mailing lists to setup. The key is the list name, the value the per list settings
+lists: {}
+#	'list@example.com': {
+		# See https://docs.mailman3.org/projects/mailmanclient/en/latest/_modules/mailmanclient/restobjects/settings.html#Settings
+#		settings: {
+#			'description': 'foobar',
+#		}
+		# See description in **list_defaults**
+#		ldap: {..}
+#	}
+```