Service Architecture¶

Mailborder V6 uses a modular, service-based architecture where specialized daemons work together to provide email security. This document explains the architecture and how services interact.

Architecture Overview¶

┌──────────────────────────────────────────────────────────────┐
│                      Mailborder V6                           │
│                  Service Architecture                        │
└──────────────────────────────────────────────────────────────┘

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   mb-milter     │────▶│   mb-eval       │────▶│   mb-filter     │
│  Policy Hook    │     │ Policy Engine   │     │  Email Scanner  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                                                 │
        │                                                 │
        ▼                                                 ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Postfix MTA   │────▶│  mb-virtuoso    │────▶│   mb-scribe     │
│  Mail Transfer  │     │ Queue Manager   │     │  Log Service    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                │                         │
                                │                         │
                                ▼                         ▼
                        ┌─────────────────┐     ┌─────────────────┐
                        │   mb-cron       │     │   MariaDB       │
                        │ Scheduled Tasks │     │   Database      │
                        └─────────────────┘     └─────────────────┘
                                │
                                │
                        ┌───────▼─────────┐
                        │  mb-guardian    │
                        │    Watchdog     │
                        └─────────────────┘

                        ┌─────────────────┐
                        │   mb-rpcd       │
                        │  RPC Daemon     │
                        │  (Web Backend)  │
                        └─────────────────┘

Core Services¶

mb-milter - Policy Hook¶

Purpose: SMTP-level policy enforcement before message acceptance

Function: - Integrates with Postfix via milter protocol - Performs early checks (sender validation, rate limiting) - Can reject before message fully received - Reduces bandwidth and processing load

Communication: - Listens on Unix socket: /run/mailborder/mb-milter.sock - Postfix connects via milter protocol - Queries mb-eval for policy decisions

Resource Usage: - Very lightweight (minimal CPU/memory) - One process per connection

Configuration: - /etc/mailborder/services/mb-milter.conf

Logs: - /var/log/mailborder/milter.log

mb-eval - Policy Evaluation Engine¶

Purpose: Evaluate email against policy rules

Function: - Recipient validation - Sender blacklist/whitelist checks - Rate limiting enforcement - GeoIP filtering - Custom policy rules

Communication: - Listens on Unix socket: /run/mailborder/mb-eval.sock - Called by mb-milter and mb-virtuoso - Queries database for policies

Resource Usage: - Low CPU usage - Memory: ~50-100 MB - Database queries can be bottleneck

Configuration: - /etc/mailborder/services/mb-eval.conf

Logs: - /var/log/mailborder/eval.log

mb-filter - Email Scanner¶

Purpose: Comprehensive content analysis for spam and viruses

Function: - Rspamd integration (spam scoring) - ClamAV integration (virus scanning) - RBL queries - SPF/DKIM/DMARC validation - Content filtering

Communication: - Listens on Unix socket: /run/mailborder/mb-filter.sock - Called by mb-virtuoso - Calls Rspamd and ClamAV

Resource Usage: - High CPU usage (scanning is intensive) - Memory: 256-512 MB per process - Multiple parallel processes

Configuration: - /etc/mailborder/services/mb-filter.conf

Logs: - /var/log/mailborder/filter.log

mb-virtuoso - Queue Manager¶

Purpose: Orchestrate email processing and delivery

Function: - Poll email queue - Send messages to mb-filter for scanning - Apply verdicts (deliver, quarantine, reject) - Manage retries - Deliver to relay host

Communication: - Reads from: /var/spool/mailborder/ - Calls mb-filter via Unix socket - Delivers via SMTP to relay host - Logs to mb-scribe

Resource Usage: - Moderate CPU usage - Memory: 100-200 MB - I/O intensive (queue operations)

Configuration: - /etc/mailborder/services/mb-virtuoso.conf

Logs: - /var/log/mailborder/virtuoso.log

mb-scribe - Logging Service¶

Purpose: Centralized logging and statistics collection

Function: - Collect logs from all services - Write to database - Generate statistics - Log rotation - Retention management

Communication: - Listens on Unix socket: /run/mailborder/mb-scribe.sock - All services send logs here - Writes to MariaDB

Resource Usage: - Low CPU usage - Memory: 50-100 MB - Database writes can be intensive

Configuration: - /etc/mailborder/services/mb-scribe.conf

Logs: - /var/log/mailborder/scribe.log

mb-cron - Scheduled Tasks¶

Purpose: Execute periodic maintenance tasks

Function: - Database cleanup - Log rotation - Quarantine expiration - Signature updates - Report generation - Backup execution

Communication: - Standalone daemon - Queries database - Calls system utilities

Resource Usage: - Minimal when idle - Spikes during task execution

Configuration: - /etc/mailborder/services/mb-cron.conf - Schedule: /etc/mailborder/cron.d/

Logs: - /var/log/mailborder/cron.log

mb-guardian - Service Watchdog¶

Purpose: Monitor service health and auto-restart failures

Function: - Ping all services periodically - Check resource usage - Detect crashes - Auto-restart failed services - Alert administrators

Communication: - Queries all service sockets - Checks SystemD status - Monitors system resources

Resource Usage: - Very low (runs checks every 30 seconds) - Memory: ~20 MB

Configuration: - /etc/mailborder/services/mb-guardian.conf

Logs: - /var/log/mailborder/guardian.log

mb-rpcd - RPC Daemon¶

Purpose: Backend for web interface

Function: - Handle web interface API requests - Execute administrative commands - Query and update database - Manage configuration - User authentication

Communication: - Listens on Unix socket: /run/mailborder/mb-rpcd.sock - Nginx → PHP-FPM → mb-rpcd socket - Fork-per-request model

Resource Usage: - Variable (based on web traffic) - Each request: 20-50 MB - Parent process: ~30 MB

Configuration: - /etc/mailborder/services/mb-rpcd.conf

Logs: - /var/log/mailborder/rpcd.log

Service Dependencies¶

Services start in this order:

1. MariaDB (database)
2. Redis (cache)
3. mb-scribe (logging - needs database)
4. mb-eval (policy - needs database)
5. mb-filter (scanner - needs Rspamd, ClamAV)
6. mb-milter (needs mb-eval)
7. mb-virtuoso (needs mb-filter, mb-scribe)
8. mb-rpcd (needs database, Redis)
9. mb-cron (needs database)
10. mb-guardian (monitors all services)

SystemD handles dependencies automatically.

Inter-Service Communication¶

Unix Sockets¶

Primary communication method (fast, secure, local only).

Socket Locations:

/run/mailborder/mb-rpcd.sock
/run/mailborder/mb-milter.sock
/run/mailborder/mb-eval.sock
/run/mailborder/mb-filter.sock
/run/mailborder/mb-scribe.sock

Permissions: - Owner: mailborder:mailborder - Mode: 0770

Advantages: - No network exposure - File system permissions provide access control - Lower latency than TCP - No authentication needed

TCP Sockets (Optional)¶

For distributed/clustered deployments only.

Ports: - mb-filter: 9001 (configurable) - mb-eval: 9002 (configurable)

Security: - Bind to localhost by default - TLS encryption recommended for remote - API key authentication required

Database¶

Shared data store.

Tables Used: - Email logs - Quarantine metadata - Configuration - User accounts - Policy rules - Statistics

Connection Pooling: - Persistent connections - Pool size: 20 (configurable)

Redis Cache¶

Shared cache for performance.

Cached Data: - Language files - User metadata - Configuration - RBL results (5-minute TTL) - Session data

Eviction Policy: - allkeys-lru (least recently used)

Service Lifecycle¶

Starting Services¶

Via SystemD:

# Start all services
sudo systemctl start mb-*

# Start specific service
sudo systemctl start mb-rpcd

Start Order: SystemD handles dependencies automatically.

Stopping Services¶

Graceful Shutdown:

# Stop all services
sudo systemctl stop mb-*

# Stop specific service
sudo systemctl stop mb-rpcd

Process: 1. Service receives SIGTERM 2. Finish current operations 3. Close connections 4. Flush buffers 5. Exit cleanly

Timeout: 90 seconds (then SIGKILL)

Restarting Services¶

Full Restart:

sudo systemctl restart mb-rpcd

Reload Configuration (No Downtime):

sudo systemctl reload mb-rpcd

Resource Management¶

Memory Limits¶

Each service has memory limits enforced by SystemD.

Limits: - mb-rpcd: 512 MB per child, 2 GB total - mb-filter: 512 MB per process - mb-virtuoso: 1 GB total - mb-scribe: 256 MB - mb-milter: 128 MB - mb-eval: 256 MB - mb-cron: 512 MB - mb-guardian: 128 MB

Exceeded Limit: - Process killed (OOM) - Guardian detects and restarts - Alert generated

CPU Limits¶

No hard CPU limits by default (would impact performance).

Priority: - mb-filter: Normal (email scanning priority) - mb-rpcd: Normal (user-facing) - mb-cron: Low (background tasks) - Others: Normal

I/O Priority¶

Best Effort Class: - mb-filter, mb-virtuoso: High - mb-rpcd: Normal - mb-cron: Low

Security Boundaries¶

Process Isolation¶

Each service runs as mailborder user (non-root).

SystemD Hardening:

[Service]
User=mailborder
Group=mailborder
NoNewPrivileges=true
ProtectSystem=full
ProtectHome=true
PrivateDevices=true
PrivateTmp=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6

Encrypted Code Execution¶

Critical services use encrypted PHP code: - mb-rpcd - mb-filter - mb-virtuoso - mb-scribe - mb-cron

Benefits: - IP protection - Tamper resistance - Air-gapped deployment support

See Encryption Architecture

Service Health Monitoring¶

Automated Monitoring¶

mb-guardian Checks: - Socket responsiveness (ping test) - Process existence - Memory usage - CPU usage - Restart count

Check Interval: 30 seconds

Actions on Failure: - Log failure - Attempt restart - Alert after 3 restart attempts

Manual Health Checks¶

# Overall status
sudo mb-status

# Service-specific status
sudo systemctl status mb-rpcd

# Check logs
sudo journalctl -u mb-rpcd -n 50

# Socket connectivity test
sudo mb-test-socket /run/mailborder/mb-rpcd.sock

Troubleshooting¶

Service Won't Start¶

1. Check dependencies:

   sudo systemctl list-dependencies mb-rpcd
   

2. Check logs:

   sudo journalctl -u mb-rpcd -n 50
   

3. Test configuration:

   sudo mb-config --verify
   

4. Check permissions:

   ls -la /run/mailborder/
   

Service Crashes Repeatedly¶

1. Check resource limits:

   sudo systemctl status mb-rpcd
   

2. Review crash logs:

   sudo journalctl -u mb-rpcd --since "1 hour ago"
   

3. Check system resources:

   free -h
   df -h
   

4. Disable auto-restart temporarily:

   sudo systemctl stop mb-guardian
   

High Resource Usage¶

1. Identify culprit:

   top -u mailborder
   

2. Check service-specific logs:

   sudo tail -f /var/log/mailborder/*.log
   

3. Adjust resource limits:

   sudo systemctl edit mb-filter
   

4. Restart service:

   sudo systemctl restart mb-filter
   

Next Steps¶

• Service Management - Start/stop/restart procedures
• mb-rpcd - RPC daemon details
• mb-filter - Email scanner details
• mb-virtuoso - Queue processor details
• Performance Monitoring - Monitor resources