Merge branch 'dev'

docs/tutorials/multiple-domains.md

@@ -1,56 +0,0 @@
-# Multiple domains configuration
-
-## Separate account namespaces
-
-Given two domains, example.org and example.com. foo@example.org and
-foo@example.com are different and completely independent accounts.
-
-All changes needed to make it work is to make sure all domains are specified in
-the `$(local_domains)` macro in the main configuration file. Note that you need
-to pick one domain as a "primary" for use in auto-generated messages.
-```
-$(primary_domain) = example.org
-$(local_domains) = $(primary_domain) example.com
-```
-
-The base configuration is done. You can create accounts using maddyctl using
-both domains in the name, send and receive messages and so on.  Do not forget
-to configure corresponding SPF, DMARC and MTA-STS records as was
-recommended in the [introduction tutorial](setting-up.md).
-
-## Single account namespace
-
-Lets say you want to handle messages for domains example.org and example.com
-and make that foo@example.org and foo@example.com are the same accounts.
-Sadly, this case is not very well-supported by maddy, but it still can be
-implemented.
-
-You already should have the primary domain set for autogenerated messages and
-so on. The idea is to redirect all messages from non-primary domains to the
-primary one.
-
-For each handled domain, the following line should be added to the
-`modify` block that gets applied for local recipients:
-```
-replace_rcpt regexp /(.+)@example.com/ $1@$(primary_domain)
-```
-It does regexp replacement, turning anything@example.com into
-anything@$(primary_domain) where $(primary_domain) in our case is example.org.
-
-E.g.
-```
-$(primary_domain) = example.org
-
-# Probably somewhere in local_routing
-modify {
-    replace_rcpt regexp /(.+)@example.net/ $1@$(primary_domain)
-    replace_rcpt regexp /(.+)@example.com/ $1@$(primary_domain)
-}
-```
-With that configuration, all messages for foo@example.net and foo@example.com
-will end up in the foo@example.org mailbox.
-
-Note, however, no account credentials aliasing is done. Users should always use
-the account name with the primary domain to access IMAP mailboxes.
-
-**Note 1**: All domains should still be listed in the `$(local_domains)` macro.

docs/tutorials/pam.md

@@ -0,0 +1,98 @@
+# Using PAM authentication
+
+maddy supports user authentication using PAM infrastructure via `auth.pam`
+module.
+
+In order to use it, however, either maddy itself should be compiled
+with libpam support or a helper executable should be built and 
+installed into an appropriate directory.
+
+It is recommended to use builtin libpam support if you are using
+PAM as an intermediate for authentication provider not directly
+supported by maddy.
+
+If PAM authentication requires privileged access on the host system
+(e.g. pam_unix.so aka /etc/shadow) then it is recommended to use
+a privileged helper executable since maddy process itself won't 
+have access to it.
+
+## Built-in PAM support
+
+Binary artifacts provided for releases do not come with
+libpam support. You should build maddy from source.
+
+See [here](../building-from-source) for detailed instructions.
+
+You should have libpam development files installed (`libpam-dev` 
+package on Ubuntu/Debian).
+
+Then add `--tags 'libpam'` to the build command:
+```
+./build.sh --tags 'libpam'
+```
+
+Then you should be able to replace `local_authdb` implementation
+in default configuration with `auth.pam`:
+```
+auth.pam local_authdb {
+    use_helper no
+}
+```
+
+## Helper executable
+
+TL;DR
+```
+git clone https://github.com/foxcpp/maddy
+cd maddy/cmd/maddy-pam-helper
+gcc pam.c main.c -lpam -o maddy-pam-helper
+```
+
+Copy the resulting executable into /usr/lib/maddy/ and make 
+it setuid-root so it can read /etc/shadow (if that's necessary):
+``` 
+chown root:maddy /usr/lib/maddy/maddy-pam-helper
+chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-pam-helper
+```
+
+Then you should be able to replace `local_authdb` implementation
+in default configuration with `auth.pam`:
+```
+auth.pam local_authdb {
+    use_helper yes
+}
+```
+
+## Account names
+
+Since PAM does not use emails for authentication you should also
+switch storage backend to using usernames for authentication:
+```
+storage.imapsql local_mailboxes {
+    ...
+    delivery_map email_localpart
+    auth_normalize precis_casefold
+}
+```
+(See [Multiple domains](../../multiple-domains) for details)
+
+## PAM service
+
+You should create a PAM configuration file for maddy to use.
+Place it into /etc/pam.d/maddy.
+Here is the minimal example using pam_unix (shadow database).
+``` 
+#%PAM-1.0
+auth	required	pam_unix.so
+account	required	pam_unix.so
+```
+
+Here is the configuration example you could use on Ubuntu
+to use the authentication config system itself uses:
+``` 
+#%PAM-1.0
+
+@include common-auth
+@include common-account
+@include common-session
+```