Command line & services

For administrators with SSH access to the gateway.

obsidian-admin

Run it as the obsidian user with the configuration path. A shell alias saves typing:

alias oa='sudo -u obsidian env OBSIDIAN_CONFIG=/etc/obsidian/obsidian.toml /opt/obsidian/venv/bin/obsidian-admin'

oa selftest: Checks clamd, the Spamhaus test entries, the AI model and the database in one go.
oa scan FILE.eml [--rcpt ADDR] [--ip IP] [--from ADDR]: Same as Test a message: prints verdict, action, score and every rule.
oa test-llm: Model health plus a live phishing sample; prints the model's JSON answer and timing.
oa create-admin EMAIL [--password PW]: Creates an MSP administrator, or resets the password / unlocks an existing one.
oa train spam|ham FILE.eml [--org ID]: Train Bayes from a saved message (org 0 = global corpus).
oa get KEY: Print a runtime setting.
oa set KEY VALUE: Change a runtime setting; VALUE is JSON ('"text"', 42, true, '["a","b"]').
oa render-postfix: Rebuild the Postfix routing tables.
oa init-db: Create any missing database tables (the installer does this).

Services

sudo systemctl status obsidian-milter obsidian-worker obsidian-web
sudo systemctl restart obsidian-worker

Server tools

The Server pages of the console and the console menu do the same things through one root helper:

sudo obsidian-console: The server menu (it also opens by itself when an administrator signs in on the VM's own screen). Network, firewall, storage, updates, time, services, logs, support bundles, backup and restore; it works while the scanner, the database or the web console is down.
sudo obsidian-os OPERATION ['JSON']: One operation, answer as JSON: sudo obsidian-os overview, sudo obsidian-os network.test, sudo obsidian-os backup.run, sudo obsidian-os jobs. sudo obsidian-os help lists them all.
obsidian-os.socket: Where the console asks (/run/obsidian-os.sock, group obsidian). Long operations run as their own units, obsidian-os-job-*; journalctl -u 'obsidian-os*' shows them.
obsidian-backup.timer: The daily backup, switched on by Server › Backup.

Logs

journalctl -u obsidian-milter -f: One line per message: queue ID, message ID, direction, sender, verdict, score, action and scan time.
journalctl -u obsidian-worker -f: AI reviews, digests, syncs, API polls, job errors.
journalctl -u obsidian-web: Console errors.
journalctl -u postfix@- -f: SMTP connections, postscreen decisions, deliveries.
/var/log/obsidian-install.log: Last installer run.

Files

/etc/obsidian/obsidian.toml: Bootstrap configuration (see Settings).
/etc/obsidian/setup-code: The one-time code the /setup wizard asks for. Exists only while the gateway has no account; sudo obsidian-os setup.screen makes it (and shows it on the server's screen through /etc/issue.d/obsidian-setup.issue) or, once an account exists, removes both.
/etc/obsidian/tls/: Certificate links used by Postfix and nginx.
/var/lib/obsidian/store/: Raw messages (gzip), by date.
/var/lib/obsidian-maps/: Generated Postfix tables - do not edit.
/opt/obsidian/: Application code and Python environment.
/usr/local/sbin/obsidian-postfix-sync: Helper the console runs (via sudo) to apply Postfix settings.
/usr/local/sbin/obsidian-certbot: Helper the console runs (via sudo) to request / renew the Let's Encrypt certificate; can be run by hand as root.
/usr/local/sbin/obsidian-cert-deploy: certbot deploy hook: copies the certificate into /etc/obsidian/tls and reloads Postfix and nginx.
/usr/local/sbin/obsidian-os: The server tools' root helper (Server pages, console menu); validates every request itself.
/etc/obsidian/backup.json, network.json: Backup destination and schedule (root only: it holds the share's password), and the network configuration made with the server tools (written to /etc/netplan/90-obsidian.yaml).
/var/lib/obsidian-os/: The server tools' state: jobs, update list, network snapshots for undo.
/var/lib/obsidian/support/: Support bundles.
/etc/letsencrypt/: certbot's store (certificate lineage "obsidian"); sudo certbot certificates lists it.