Settings

Manage › Settings (MSP administrators) holds platform-wide configuration. Each section has its own Save button. Changes reach every service within about 10 seconds; saving General, Mail flow or Spamhaus also re-applies the Postfix configuration automatically.

General

Product name shown to usersgeneral.brand_name

Name shown in the console header, browser titles, digest emails and the authenticator app entry. Change it to white-label Obsidian for your clients. Default: Obsidian

Gateway hostname (HELO / MX target)general.hostname

The gateway's fully-qualified host name. Used as the Postfix HELO / banner name, in Authentication-Results headers and in every setup instruction (MX targets, smart hosts). It must resolve in public DNS to the gateway and match the TLS certificate. Saving re-syncs Postfix (myhostname) automatically; values without a dot are ignored by Postfix. Default: obsidian.local

Gateway public IPsgeneral.public_ips

The public IP address(es) mail leaves and arrives from. Only used to fill in setup instructions (M365 inbound connector IP restriction, Google inbound gateway list, SPF records). One per line. List. Default: (none)

Administrator alert addressgeneral.admin_email

Where administrator alerts should go. Informational today; also a sensible place to point the postmaster alias. Default: (empty)

Time zonegeneral.timezone

IANA time zone (e.g. America/Chicago) used for every timestamp in the console and for the digest schedule. Default: America/Chicago

Mail flow

Maximum message size (MB)smtp.max_message_size_mb

Largest message Postfix accepts, in MB. Larger messages are refused at SMTP time with a 552 error. Saving re-syncs Postfix. Default: 50

Outbound relay clientssmtp.relay_clients

IP addresses / CIDR ranges allowed to relay OUTBOUND mail through the gateway: your on-premises Exchange servers, and - when a Microsoft 365 or Google tenant sends outbound through Obsidian - that platform's sending ranges. Relay is only granted for envelope senders in domains that have 'Allow outbound relay' on, and these hosts skip the postscreen DNSBL test. Pair shared-platform ranges with a per-domain relay key. List. Default: (none)

Reject unknown recipientssmtp.reject_unknown_recipients

When on, RCPT TO for an address that is not a known user or alias is rejected (550 5.1.1) - but only for domains with 'Reject unknown recipients' enabled. Requires a directory sync so the user list is complete. Checkbox. Default: on

Trusted internal networkssmtp.internal_networks

LAN address ranges (CIDR, one per line) of your own servers that send mail as your domains - web servers' cron jobs, applications, scanners/copiers, monitoring. Their mail is still virus, attachment, link and content scanned, but skips SPF/DKIM/DMARC, the internal-domain spoof check, impersonation and AI review (those only make sense for internet senders). Typical value: 192.168.0.0/16 and 10.0.0.0/8. Only list ranges internet mail can never appear from - check that your router does not masquerade inbound connections (a message from an internet sender must show its real public IP in Message trace). List. Default: (none)

Spamhaus

Enable Spamhaus checksspamhaus.enabled

Master switch for all Spamhaus lookups (ZEN in postscreen and in the scanner, DBL, ZRD, HBL). Checkbox. Default: on

Data Query Service keyspamhaus.dqs_key

Your Spamhaus Data Query Service key. With a key Obsidian queries <key>.zen.dq.spamhaus.net etc. and enables ZRD and HBL; postscreen switches to the DQS zone automatically and the key is hidden from SMTP replies. Without a key the free public mirrors are used, which are licensed for non-commercial, low-volume use only. Enter '-' to clear a stored key. Secret. Default: (empty)

Antivirus (ClamAV)

Enable ClamAVclamav.enabled

Master switch for antivirus scanning. Checkbox. Default: on

clamd socketclamav.socket

Where clamd listens: a Unix socket path (default /var/run/clamav/clamd.ctl) or host:port for a remote clamd. Default: /var/run/clamav/clamd.ctl

Largest message to scan (MB)clamav.max_scan_mb

Messages larger than this are not sent to ClamAV (rule AV_TOO_LARGE is recorded instead). Keep it at or below clamd's StreamMaxLength (100 MB as installed). Default: 60

When clamd is downclamav.fail_action

What happens when clamd cannot be reached. 'tempfail' (recommended) answers 451 so the sending server retries later - nothing is lost and nothing unscanned gets through. 'accept' delivers unscanned mail with an X-Obsidian-Error header. One of: tempfail, accept. Default: tempfail

AI analysis (local LLM)

Enable AI analysisllm.enabled

Master switch for AI analysis. When off, no message is ever held for the model and policies' AI settings are ignored. Checkbox. Default: on

Ollama endpointllm.endpoint

Base URL of the Ollama server (e.g. http://192.168.6.195:11434). The gateway must be able to reach TCP 11434 on it. Default: http://192.168.6.195:11434

Modelllm.model

Exact Ollama model name (as listed by `ollama list`). System health shows whether it exists and is resident in memory. Default: qwen3:30b-a3b-instruct-2507-q4_K_M

Background review timeout (s)llm.timeout_seconds

How long the background worker waits for one AI review. CPU-only hosts need generous values (240 s default). Default: 240

Inline (SMTP-time) timeout (s)llm.inline_timeout_seconds

Maximum time a policy in 'inline' AI mode may hold the SMTP connection waiting for the model. If exceeded the rule verdict is used. Default: 20

Context window (tokens)llm.num_ctx

Context window passed to Ollama. The dossier Obsidian sends is small (usually 500-1500 tokens); 4096 leaves ample room. Default: 4096

Body characters sent to the modelllm.max_body_chars

How much of the message body is included in the AI dossier. Prompt processing dominates CPU inference time, so smaller is faster. Default: 3500

Parallel requestsllm.concurrency

Parallel AI requests from the worker. Match OLLAMA_NUM_PARALLEL on the model host (1 on lsllm1); more than the host allows just queues. Default: 1

Score weightllm.weight

Multiplier applied to the score the AI verdict contributes. 1.0 = default; lower it to make the model advisory, raise it to let the model dominate. Default: 1.0

Bayesian learning

Enable Bayesbayes.enabled

Master switch for the Bayesian filter. Checkbox. Default: on

Messages of each class before Bayes scoresbayes.min_messages

Bayes stays silent until both the spam and the ham corpus have at least this many trained messages - an undertrained filter does more harm than good. Default: 50

Auto-learn from confident verdictsbayes.autolearn

Automatically train on confident verdicts: score at or above the autolearn spam score as spam, and clean mail at or below the autolearn ham score as ham. Checkbox. Default: on

Retention

Message log (days)retention.log_days

How long message records (the trace) are kept. Older records and their raw copies are deleted by the retention job (runs every 6 hours). Default: 90

Quarantine (days)retention.quarantine_days

Quarantined and held messages older than this expire: the raw copy is deleted and their status becomes 'expired'. Default: 30

Raw copy of delivered mail (days)retention.raw_clean_days

How long a raw copy of DELIVERED mail is kept. Needed for clawback, 'Report spam' training and async AI review. 0 = keep raw copies only for quarantined mail. Default: 3

Quarantine digests

Send digestsdigest.enabled

Master switch for quarantine digest emails. Checkbox. Default: on

Send at hours (local time)digest.hours

Local hours (0-23, comma separated) at which digests go out, e.g. 8, 16. Each user receives only messages not included in an earlier digest. List. Default: 8, 16

From addressdigest.from_address

Sender address of digests and sign-in links. Default quarantine@<hostname>. Use an address your tenants will not treat as spoofed. Default: (empty)

TLS certificate (Let's Encrypt)

Certificate hostnamestls.names

Host names the certificate covers, one per line - typically the MX host (e.g. mx1.obsidiansuite.net) and the console name if it differs (e.g. portal.obsidiansuite.net). Empty = just the gateway hostname. Wildcards (*.example.com) need the Cloudflare method. List. Default: (none)

Let's Encrypt contact emailtls.email

Contact address registered with Let's Encrypt; it receives expiry warnings if automatic renewal ever fails. Default: (empty)

Validation methodtls.method

How Let's Encrypt verifies you control the names. 'cloudflare' (recommended when the domain's DNS is on Cloudflare) creates a temporary TXT record through the Cloudflare API - the gateway does not need to be reachable from the internet. 'http' serves a file on port 80, so the names must already point at the gateway and TCP 80 must be forwarded to it. One of: cloudflare, http. Default: cloudflare

Cloudflare API tokentls.cloudflare_token

A Cloudflare API token with Zone > DNS > Edit permission, limited to the zone(s) of the certificate names. Stored encrypted; only the root certificate helper can read it back. Enter '-' to clear. Default: (empty)

Use the Let's Encrypt staging server (testing)tls.staging

Use Let's Encrypt's staging server: certificates are not trusted by browsers or mail servers, but there are no rate limits. Use it to test a new setup, then untick it and request again for a real certificate. Checkbox. Default: off

Security

Session length (hours)security.session_hours

How long a sign-in lasts before the user must sign in again. Default: 12

Require MFA for administratorssecurity.require_mfa_admins

When on, administrators who have not enrolled two-factor authentication are sent to the enrolment page right after signing in. (SSO sign-ins are exempt - enforce MFA in Entra ID / Google instead.) Checkbox. Default: off

Failed logins before lockoutsecurity.max_failed_logins

Consecutive failed password attempts before the account is locked. Default: 8

Lockout (minutes)security.lockout_minutes

How long a locked account stays locked. An administrator saving the user record clears the lock immediately. Default: 15

Allow email sign-in links for userssecurity.magic_link_login

Lets end users (role 'user') request a one-time sign-in link by email instead of a password. Links expire after 15 minutes and require a click on a confirmation page. Checkbox. Default: on

Advanced settings (command line)

A few rarely-changed values are not on the page. Set them with obsidian-admin set KEY VALUE (value in JSON; see Command line):

spamhaus.zones

Which Spamhaus lists are queried, e.g. {"zen": true, "dbl": true, "zrd": true, "hbl": true} (not on the Settings page). Turn one off to stop its lookups; ZRD and HBL only work with a DQS key anyway.Default: {'zen': True, 'dbl': True, 'zrd': True, 'hbl': True}

llm.temperature

Sampling temperature for the model (not on the Settings page; set with obsidian-admin). Keep it low (0.1) for consistent verdicts.Default: 0.1

bayes.autolearn_spam_score

Score at or above which a message is auto-learned as spam (not on the Settings page; default 15).Default: 15.0

bayes.autolearn_ham_score

Score at or below which clean mail is auto-learned as ham (not on the Settings page; default -2).Default: -2.0

digest.include_admin_only

Whether admin-only items (viruses, malware, phishing) are listed in users' digests (without release links). Off by default (not on the Settings page).Default: False

The default policy is edited on Policies, not here.

Server-only configuration

/etc/obsidian/obsidian.toml holds what must exist before the database is reachable. Edit it as root and restart the three obsidian services.

database_url

PostgreSQL connection (written by the installer).

secret_key

Signs sessions, digest and sign-in links. Changing it signs everyone out and invalidates all outstanding links.

data_key

Encrypts connector secrets, DKIM keys and TOTP secrets. Never change it on a running system; back it up.

data_dir

Where the quarantine store lives (default /var/lib/obsidian).

postfix_map_dir

Where Postfix routing tables are written (/var/lib/obsidian-maps).

dns_resolver

Resolver for scanning lookups, normally the local unbound 127.0.0.1:5335.

public_url

Console address used in digest and sign-in links.

setup_token

Required by the first-run /setup page.

web_host, web_port, milter_socket, reinject_host, reinject_port

Internal listeners (127.0.0.1:8440 web, 127.0.0.1:11332 milter, 127.0.0.1:10026 re-injection). Change only together with the systemd units / Postfix configuration.