Docs / Obsidian Mail Server / Reference
Configuration file
Most things are set in this admin center. The rest (host name, listening ports, certificates, limits) lives in one file on the server:
/etc/obsidian-mailserver/appsettings.jsonEdit it with sudo nano /etc/obsidian-mailserver/appsettings.json, then apply the change with sudo systemctl restart obsidian-mailserver. The file is JSON: keep the quotes, braces and commas intact, and check it with python3 -m json.tool /etc/obsidian-mailserver/appsettings.json before restarting. Updates add new sections with their defaults but never change what you set.
Durations are written as "days.hours:minutes:seconds", for example "2.00:00:00" for two days or "00:05:00" for five minutes. Sizes are in bytes (37748736 is 36 MB).
General (Oms)
| Setting | Default | Meaning |
|---|---|---|
Hostname | set by the setup | The server's public name (mail.example.com), used in greetings, message headers and certificates |
Database | set by the setup | PostgreSQL connection. Leave as is. |
DataRoot | /var/lib/obsidian-mailserver | Where mail content and generated certificates are kept |
Tls.CertificatePath | none (self-signed) | Certificate: a PEM file with the chain, or a .pfx file. See Certificates. |
Tls.KeyPath | none | Private key, when the certificate is a PEM file |
Tls.PfxPassword | none | Password of a .pfx file |
Listeners for mail from other servers and apps
Oms.Transport.ReceiveConnectors is a list; each entry opens one SMTP port. The installed defaults are:
"ReceiveConnectors": [
{ "Name": "Default Frontend", "Bind": "[::]:25", "Usage": "Internet" },
{ "Name": "Client Frontend", "Bind": "[::]:587", "Usage": "Client", "MaxRecipientsPerMessage": 200 },
{ "Name": "Client Proxy TLS", "Bind": "[::]:465", "Usage": "Client", "ImplicitTls": true, "MaxRecipientsPerMessage": 200 }
]| Setting | Default | Meaning |
|---|---|---|
Name | A label, shown in logs and on the home page | |
Bind | 0.0.0.0:25 | Address and port. [::]:25 listens on all IPv4 and IPv6 addresses. |
Usage | Internet | Internet: mail from other servers, no sign-in, only for your domains. Client: apps, sign-in required, sender must be the signed-in person (or someone they may send as). |
ImplicitTls | false | Encrypt from the first byte (port 465) instead of upgrading with STARTTLS |
AllowPlaintextAuth | false | Allow sign-in without encryption. Only for listeners on 127.0.0.1. |
RelayFrom | empty | IP ranges that may send to any destination without signing in (see Mail flow) |
RemoteRanges | empty (everyone) | IP ranges allowed to connect at all |
MaxMessageSize | 37748736 (36 MB) | Largest message accepted |
MaxRecipientsPerMessage | 5000 | Recipients per message |
MaxConnectionsPerIp | 20 | Simultaneous connections from one address |
MaxProtocolErrors | 10 | Errors before the connection is closed |
CommandTimeout | 00:05:00 | Idle time before the connection is closed |
Banner | Obsidian Mail Server ready | Text in the greeting after the host name |
Delivery and the queue (Oms.Transport)
| Setting | Default | Meaning |
|---|---|---|
MessageExpiration | 2.00:00:00 | How long to keep retrying before returning mail to the sender |
DelayNotification | 04:00:00 | When to tell the sender that delivery is delayed |
QueueWorkers | 4 | Deliveries in parallel |
OutboundTimeout | 00:02:00 | Time to wait for another mail server |
OpportunisticTlsAcceptAnyCertificate | true | Encrypt to servers with invalid certificates rather than send unencrypted (standard for mail servers). Routes with Only send encrypted always check certificates. |
MaxHopCount | 60 | Mail that passed through more servers than this is treated as a loop |
IMAP and POP3 (Oms.Imap, Oms.Pop3)
Each has an Endpoints list. The installed defaults listen on 143 and 993 (IMAP) and 110 and 995 (POP3):
"Imap": { "Endpoints": [ { "Name": "IMAP4", "Bind": "[::]:143" }, { "Name": "IMAP4 SSL", "Bind": "[::]:993", "ImplicitTls": true } ] }| Setting | Default | Meaning |
|---|---|---|
Endpoints[].Bind, ImplicitTls, AllowPlaintextAuth, RemoteRanges | As for SMTP listeners above | |
Endpoints[].MaxConnectionsPerIp | 50 | Simultaneous connections from one address |
Imap.MaxMessageSize | 37748736 | Largest message an app may upload |
Imap.IdleTimeout | 00:30:00 | Idle time before an IMAP connection is closed |
Pop3.IdleTimeout | 00:10:00 | Idle time before a POP3 connection is closed |
To switch POP3 off, empty its list: "Pop3": { "Endpoints": [] }, and set ClientAccess.AdvertisePop3 to false.
Web, phones and automatic setup (Oms.ClientAccess)
| Setting | Default | Meaning |
|---|---|---|
HttpEndpoints | [::]:443 (HTTPS) and [::]:80 (HTTP) | Web listeners: { "Bind": "[::]:443", "Https": true } |
PublicHost | the host name | The name apps are told to connect to, if it differs from Hostname |
ImapPort, Pop3Port, SmtpPort, HttpsPort | 993, 995, 587, 443 | Ports apps are told to use, for example when a firewall forwards other port numbers |
AdvertisePop3 | true | Offer POP3 in automatic setup |
Outlook sign-in (Oms.Ntlm)
Whether NTLM is offered at all is switched with sudo oms ntlm enable|disable (see NTLM sign-in for Outlook).
| Setting | Default | Meaning |
|---|---|---|
ChannelBinding | WhenSupplied | Extended Protection. WhenSupplied: when Outlook ties its sign-in to the certificate (it always does over HTTPS), it must be this server's. Required: refuse clients that do not. None: only when a proxy in front of the server handles HTTPS. |
Phones (Oms.ActiveSync)
| Setting | Default | Meaning |
|---|---|---|
RequireProvisioning | true | Phones must accept the security rules before syncing |
MinHeartbeatSeconds, MaxHeartbeatSeconds | 60, 3540 | Range for push connections. Lower the maximum if a firewall closes idle connections sooner. |
MaxWindowSize | 512 | Items per sync request |
Logging
"Logging": { "LogLevel": { "Default": "Information" } }Set Default to Debug temporarily when investigating a problem, and back to Information afterwards. Logs go to the system journal: sudo journalctl -u obsidian-mailserver -f.