This README is the one indexed from the repository at its latest ref, not from the tag for this version.

exu

Exu Virtual Mail Administration Suite for CentOS Stream 10

---

exu is a lightweight, statically-compiled Crystal web daemon and CLI administration suite providing secure, sovereign virtual mail administration for Exim, Dovecot, and Caddy on CentOS Stream 10.

Key Capabilities

• 🌐 Web Dashboard SPA: Fast, modern web control plane with clean session login and logout.
• ⚡ Standalone CLI (eum): Native, statically linked command-line administration tool sharing exact RBAC parity.
• 🔐 Session-Based mTLS: Decoupled transport client certificate authentication with encrypted HMAC-SHA256 session cookies.
• 📁 FHS 3.0 & YAML 1.2: Standardized /etc/exu/ configuration hierarchy and human-readable exu.yaml database.
• 🛡️ Zero-.rpmnew Churn: Non-invasive modular Exim includes (/etc/exim/exu-*.conf) and Dovecot drop-ins (/etc/dovecot/local.conf).
• 🔒 Multi-Process Advisory Locking: POSIX flock synchronization preventing race conditions across concurrent Web and CLI operations.
• 🔑 DKIM, DMARC & DNS: Automatic RSA-2048 key generation, on-demand rotation, and copy-paste ready DNS records.
• 👥 Multi-Recipient Aliases: Comma-, semicolon-, or space-delimited forwarding with atomic single-recipient removal.
• 📋 Creation Seed Templates: Configurable default alias templates (defaults.aliases) in exu.yaml automatically seeded on domain creation.
• 🎨 Customizable Branding: Site title and slogan custom configurable via branding block in exu.yaml.
• 💾 Storage Retention: Domain decommissioning preserves mailbox spools (/var/mail/virtual/<domain>) by default.

---

Quick Start

1. Build Static Release Binaries

make release

2. Automated Host Setup

Run the idempotent setup script as root to configure dependencies, services, SELinux policies, and certificates:

sudo bash resources/usr/local/libexec/exu/setup.bash mail.example.com

3. CLI Management (eum)

# Provision a virtual domain and DKIM keypair
eum domain create example.com

# Create a virtual mailbox
eum user create admin@example.com

# Create a multi-recipient alias
eum alias create example.com support alice@example.com bob@example.com

# Display complete DNS configuration (MX, SPF, DKIM, DMARC)
eum domain dns example.com

---

Documentation

Comprehensive guides, specifications, and architecture records are available in the Sphinx Documentation Suite:

Section	Description
Getting Started	Host installation, prerequisite setup, and initial configuration.
Web Dashboard Manual	SPA walkthrough, session authentication, and mailbox operations.
CLI Reference (eum)	Complete command-line syntax and option reference.
mTLS & PKI Setup Guide	Client certificate generation, CA trust, and browser installation.
Client Auto-Configuration	Mozilla Thunderbird and Microsoft Outlook autodiscover protocols.
Troubleshooting Playbook	Permission diagnoses, lock contention, and SELinux resolutions.
Functional Specifications	Formal functional requirements ([FUNC-001] to [FUNC-019]).
Technical Blueprints	Filesystem layouts, concurrency locking, and MTA integrations.
Architecture Decision Records	Immutable design decisions (YAML standard, mTLS, storage retention).
Project Roadmap	Completed v0.1.0 capabilities and future milestones (v0.2.0 Quotas).
Crystal API Reference	Source code class hierarchy and API docstrings.

---

Development

# Compile development binaries locally
make build

# Run unit & integration test suite
make test

# Run Flaw security static analyzer
make lint

# Build unified Sphinx documentation & Crystal API reference
make docs

---

Contributing & Code of Honor

This project adheres to the Universal Code of Honor. Please review the Contributing Guidelines before submitting contributions. All changes are logged in the Changelog.

Authors

• Rénich Bon Ćirić (@renich) — Creator & Lead Architect
• Gemini AI — Pair Programmer & Co-developer