add guide to configure email sending / relaying

_toc.yml

@@ -48,6 +48,7 @@ chapters:
           - file: admin-guide/configuration/alternative_desktops
           - file: admin-guide/configuration/ssh_host_hopping
           - file: admin-guide/configuration/citrix_vda
+          - file: admin-guide/configuration/configuration_email
       - file: admin-guide/guidelines
       - file: admin-guide/deployment
         sections:

admin-guide/configuration.md

@@ -24,3 +24,4 @@ Here starts a so far small collections of configuration guides for sysadmins of
 ## Special Installations
 - [SSH Host Hopping as Root (e.g. between cluster members)](configuration/ssh_host_hopping)
 - [Install Citrix VDA](configuration/citrix_vda)
+- [Sending / Relaying Emails](configuration/configuration_email)

admin-guide/configuration/configuration_email.md

@@ -0,0 +1,67 @@
+# Configuration to Send/Relay Emails
+
+## Sending Emails Via PSI Central Mail Gateway
+To be able to send emails, the server needs to be registered on the PSI mail gateways. 
+
+This can be done by this ServiceNow request:
+(Service Catalog > IT Systems & Data Storage > Register E-Mail Sender)
+
+https://psi.service-now.com/psisp?id=psi_new_sc_cat_item&sys_id=68d60ca74f8833407f7660fe0310c7e3
+
+The default PSI mail gateways for the different network segments are defined in the puppet common.yaml. Depending on the machines location a different default will take effect. The defaults are as follows:
+
+```
+mta::relays:
+  'default': 'smtpint.psi.ch'
+  'dmz': 'smtpdmz.psi.ch'
+  'extranet': 'smtpdmz.psi.ch'
+  'tier3': 'smtpdmz.psi.ch'
+```
+
+To enable the possibility to send emails from a machine to one of the standard gateways the flag `base::enable_mta` simply needs to be enabled. No other configuration is needed.
+
+```yaml
+base::enable_mta: true
+```
+
+## Sending Emails Via An Other SMTP Relay
+
+If your machine is in the default network zone (i.e. PSI intranet) sending via a differnet mail gateway than the default can be done like this:
+
+```yaml
+base::enable_mta: true
+mta::relays:
+  'default': 'test-smtp-relay.psi.ch'
+```
+
+Wether the email is accepted by the mail relay depends on the relays configuration. Contact the relay admin what the rules for his gateway are.
+
+
+## Configure Server as Mail Relay
+
+The following configuration is needed if you want to setup a email relay server accepting emails from clients.
+Depending on the rule where your relay should forward messages, your server/relay must be registered/authorized on the relay it forwardes messages to. (e.g. PSI default mail relay, procedure see above)
+
+```yaml
+base::enable_mta: true
+
+# if you want to use an other forward relay than the PSI defaults
+# mta::relays:
+#   'default': 'test-smtp-relay.psi.ch'
+
+# interfaces postfix should accept emails
+mta::inet_interfaces: # array[string] default: loopback-only
+# networks from which this relay should accept emails
+mta::mynetworks: # default: undefined
+```
+
+Example (assumption the servers ip address is 10.1.2.110):
+```yaml
+  mta::inet_interfaces:
+    - '10.1.2.110'
+    - 'localhost'
+  # mta::mynetworks_style: 'subnet'
+  mta::mynetworks:
+    - '10.1.2.0/24'
+    - '10.1.3.0/24'
+```