Obsidian SuiteDocumentation
Obsidian Mail Server: all chapters

Docs / Obsidian Mail Server / Reference

Command-line reference

The oms command on the server does everything the admin center does, and is handy for scripts, bulk changes and recovery. Sign in to the server (console or SSH) and run it with sudo. sudo oms help lists every command. Changes made with it appear in Change history as cli:<linux user>.

Wherever a password is needed and not given with --password, oms asks for it without showing it, or reads it from standard input in scripts.

Organizations and domains

sudo oms org new <name> [--display "Display Name"]
sudo oms org list
sudo oms domain add <org> <domain> [--type Authoritative|InternalRelay|ExternalRelay] [--default] [--alias-of <domain>]
sudo oms domain list [org]

Authoritative is all addresses on this server, InternalRelay shared with another mail server, ExternalRelay relay only (see Domains).

Users, mailboxes and groups

sudo oms mailbox new <org> <address> [--name "Display Name"] [--first F] [--last L] [--password X] [--hidden] [--alias a]
sudo oms shared new <org> <address> [--name "Display Name"] [--alias a]
sudo oms room new <org> <address> [--name "Display Name"] [--alias a]
sudo oms equipment new <org> <address> [--name "Display Name"] [--alias a]
sudo oms group new <org> <address> [--name "Display Name"] [--alias a]
sudo oms contact new <org> <outside-address> [--name "Display Name"] [--alias a]
sudo oms recipient list <org>
sudo oms recipient show <address>
sudo oms recipient disable <address>
sudo oms recipient enable <address>
sudo oms recipient remove <address> --confirm
sudo oms recipient move <address> <org> [--address new@domain] [--alias a] [--no-forwarder] [--unlink] [--preview]
sudo oms password set <address> [--password X]
sudo oms address add <recipient> <address> [--primary]
sudo oms address remove <recipient> <address>
sudo oms address primary <recipient> <address>
sudo oms group add <group> <member>
sudo oms group remove <group> <member>
sudo oms quota set <address> [--warn 9GB] [--send 10GB] [--receive 11GB]
sudo oms folder list <address> [--items] [--all]
sudo oms folder empty <address> <folder> [--subject "prefix"] --confirm
sudo oms archive enable <address>
sudo oms archive policy <address> 730
sudo oms archive policy <address> never
sudo oms archive disable <address>

The alias is unique within an organization and defaults to the part of the address before the @. When it is taken (support@ in a second domain while support@ of the first already exists, or a contact [email protected] holding sales), give another with --alias.

Wherever a command asks for a recipient, group, member or mailbox, you can give any of its email addresses, its id (first column of recipient list), or for a contact its outside address. So a contact goes into a group with sudo oms group add [email protected] [email protected]. When several contacts share the same outside address, use the id.

quota set with unlimited clears a limit. recipient remove deletes all mail of the recipient and needs --confirm. folder empty deletes a folder's items for good (not its subfolders; cached Outlook drops them too); without --confirm it only counts them.

Example: many users at once

A file people.csv with lines first,last,address,password:

while IFS=, read -r first last address password; do
  printf '%s\n' "$password" | sudo oms mailbox new <org> "$address" --first "$first" --last "$last" --name "$first $last"
done < people.csv

Public folders

sudo oms publicfolder list <org>
sudo oms publicfolder new <org> <name> [--parent <folder-id>]
sudo oms publicfolder permission <org> <folder-id> <address>|Default <role>
sudo oms publicfolder address <org> <folder-id> <address>

Roles: Owner, PublishingEditor, Editor, Author, Reviewer, Contributor, None. publicfolder list shows the folder ids. See Public folders.

Access and administrators

sudo oms permission add <mailbox> <user-or-group> FullAccess|SendAs|SendOnBehalf
sudo oms permission remove <mailbox> <user-or-group> FullAccess|SendAs|SendOnBehalf
sudo oms permission list <mailbox>
sudo oms role add <address> GlobalAdmin|OrgAdmin|HelpdeskAdmin|ViewOnlyAdmin
sudo oms role remove <address> <role>
sudo oms role list [org]
sudo oms mapihttp enable|disable|status <address>
sudo oms ntlm enable|disable|status|purge
sudo oms directory status|preview|sync <org> [--force]
sudo oms migration endpoint list|set|test|remove <org> ...
sudo oms migration batch list|new|show|start|stop|complete|remove <org> ...
sudo oms migration batch remove-mailbox <org> <batch> <mailbox>
sudo oms outlook gpo-script [--name "GPO name"] [--link "OU=a,DC=x;OU=b,DC=x"] [--out obsidian-outlook-gpo.ps1]
sudo oms outlook reg-file prepare-outlook.reg
sudo oms pst import <address> <file.pst|file.omsbox> [--folder "Imported/Old"]     sudo oms pst export <address> [--bundle]
sudo oms pst list <org>     sudo oms pst cancel|retry|remove <id>     sudo oms pst check <file.pst>

mapihttp offers Outlook for Windows its Exchange connection for one person; ntlm turns Windows sign-in on for Outlook (see NTLM sign-in for Outlook). migration moves mailboxes from Exchange (see Migration from Exchange). outlook writes the Group Policy script and the per-person file that keep Outlook for Windows away from Microsoft 365's Autodiscover (see Outlook and Microsoft 365).

Mail flow

sudo oms connector new <name> [--spaces "*"] [--smarthost host:port,...] [--port 25] [--require-tls] [--user u --password p]
sudo oms connector list
sudo oms connector remove <name>
sudo oms queue
sudo oms track [--msgid "<id>"] [--rcpt address] [--limit 50]

Connectors are the outgoing routes of the admin center: --spaces is Use for, --smarthost Relay servers, --require-tls Only send encrypted.

sudo oms emailsecurity status
sudo oms emailsecurity gateway <address|range> [...]     (or --clear)
sudo oms emailsecurity key new <org> [--name "..."]
sudo oms emailsecurity key list [org]
sudo oms emailsecurity key revoke <id>

emailsecurity gateway sets which addresses are Obsidian Email Security (only their X-Obsidian-... headers count); key new makes a key for its Obsidian Mail Server connector and prints it once. See Obsidian Email Security.

sudo oms relay list
sudo oms relay add <address|range> [...]
sudo oms relay remove <address|range> [...]
sudo oms relay set <address|range> [...]     (or --clear)

The addresses that may send to anyone on port 25 without signing in (printers, websites, panels): Apps and devices that send mail on the Mail flow & queue page. The running server picks changes up within a minute. See Mail flow.

Phones

sudo oms device list <address>
sudo oms device block <address> <device-id>
sudo oms device allow <address> <device-id>
sudo oms device wipe <address> <device-id> --confirm
sudo oms device cancel-wipe <address> <device-id>
sudo oms device remove <address> <device-id>
sudo oms mobilepolicy show <org>
sudo oms mobilepolicy set <org> Name=Value ...

device wipe erases the whole phone at its next connection (see Phones and tablets).

Mailbox databases

CommandDoes
sudo oms database listThe mailbox databases, what each holds, and moves in progress
sudo oms database create <name> [--path /folder]A new mailbox database (its stored mail in the data folder, or --path)
sudo oms database default <name>New mailboxes go there
sudo oms mailbox move <address> <database> [--no-archive]Move a mailbox (and its archive) to another database; it stays in use
sudo oms move list / sudo oms move cancel <id>Moves with their state; cancel one before its final switch

The server itself

CommandDoes
sudo obsidian-setupRe-run the first-boot setup: host name, network, time zone, firewall
sudo systemctl restart obsidian-mailserverRestart the mail server
sudo systemctl status obsidian-mailserverIs it running?
sudo journalctl -u obsidian-mailserver -fFollow the log
sudo apt update && sudo apt upgradeInstall updates