Skip to content

mb-rpcd Service

The Mailborder RPC Daemon - core service handling all inter-process communication.

Overview

mb-rpcd is the central nervous system of Mailborder, providing:

  • RPC Interface - Remote procedure call handling
  • Database Abstraction - Centralized database access
  • Configuration Management - System-wide settings
  • Session Management - User authentication and sessions
  • Request Handling - Fork-per-request isolation
  • API Endpoints - Web interface backend
  • Service Coordination - Communication between daemons

All other Mailborder services communicate through mb-rpcd.

Architecture

Process Model

mb-rpcd (main process)
├── Master Process (PID 1234)
├── Worker 1 (handles requests)
├── Worker 2 (handles requests)
├── Worker 3 (handles requests)
└── Worker N (handles requests)

Fork-per-request isolation: 1. Request arrives (web interface or daemon) 2. Master process forks worker 3. Worker handles request in isolation 4. Worker completes and exits 5. Next request gets fresh worker

Benefits: - Memory leaks contained to single request - Crash isolation (worker crash doesn't affect master) - Clean state for each request - No shared state between requests

Communication

Inbound: - Unix socket: /var/run/mailborder/mb-rpcd.sock - TCP socket: 127.0.0.1:10040 (optional)

Outbound: - Database: MariaDB connection - Cache: Redis connection - Other services: Unix socket IPC

Configuration

Service File

Location: /etc/systemd/system/mb-rpcd.service

[Unit]
Description=Mailborder RPC Daemon
After=network.target mariadb.service redis-server.service
Requires=mariadb.service redis-server.service

[Service]
Type=forking
User=mailborder
Group=mailborder
ExecStart=/usr/libexec/mailborder/php_enc/mb-rpcd start
ExecStop=/usr/libexec/mailborder/php_enc/mb-rpcd stop
ExecReload=/usr/libexec/mailborder/php_enc/mb-rpcd reload
PIDFile=/var/run/mailborder/mb-rpcd.pid
Restart=always
RestartSec=10

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/run/mailborder /var/log/mailborder /var/spool/mailborder

# Resource limits
LimitNOFILE=65536
MemoryLimit=2G

[Install]
WantedBy=multi-user.target

Runtime Configuration

Worker pool settings: 

sudo mb-config set rpcd.max_workers 20
sudo mb-config set rpcd.min_workers 5
sudo mb-config set rpcd.max_requests_per_worker 500

Timeouts: 

sudo mb-config set rpcd.request_timeout 30
sudo mb-config set rpcd.idle_timeout 300

Apply changes: 

sudo mb-config reload
sudo systemctl reload mb-rpcd

Operations

Start/Stop/Restart

Start service: 

sudo systemctl start mb-rpcd

Stop service: 

sudo systemctl stop mb-rpcd

Restart service: 

sudo systemctl restart mb-rpcd

Reload configuration (no downtime): 

sudo systemctl reload mb-rpcd

Check status: 

sudo systemctl status mb-rpcd

Process Management

View processes: 

pgrep -a mb-rpcd

Example output: 

1234 /usr/libexec/mailborder/php_enc/mb-rpcd: master
1235 /usr/libexec/mailborder/php_enc/mb-rpcd: worker
1236 /usr/libexec/mailborder/php_enc/mb-rpcd: worker
1237 /usr/libexec/mailborder/php_enc/mb-rpcd: worker

Kill specific worker (emergency): 

sudo kill -TERM 1235
# Master will spawn new worker automatically

Graceful restart: 

sudo kill -USR1 $(cat /var/run/mailborder/mb-rpcd.pid)
# Signals: USR1=reload, HUP=restart workers, TERM=shutdown

Monitoring

Health Check

Quick health check: 

sudo mb-rpcd-check

Example output: 

Mailborder RPC Daemon Health Check
===================================

Process Status:
  Master PID: 1234 ✓
  Workers: 4 active ✓
  Socket: /var/run/mailborder/mb-rpcd.sock ✓

Connectivity:
  Database: Connected ✓
  Redis: Connected ✓

Performance:
  Average response time: 45ms
  Requests/sec: 127
  Memory usage: 412 MB / 2048 MB (20%)

Status: HEALTHY

Real-time Monitoring

Watch log: 

sudo tail -f /var/log/mailborder/mb-rpcd.log

Watch with journalctl: 

sudo journalctl -u mb-rpcd -f

Monitor requests: 

# Enable request logging
sudo mb-config set rpcd.log_requests true
sudo systemctl reload mb-rpcd

# Watch requests
sudo tail -f /var/log/mailborder/mb-rpcd.log | grep REQUEST

Example log entries: 

2025-01-13 14:23:45 [INFO] Worker 1235 handling request from web interface
2025-01-13 14:23:45 [DEBUG] REQUEST: user.login (192.168.1.50)
2025-01-13 14:23:45 [INFO] Request completed in 42ms
2025-01-13 14:23:46 [INFO] Worker 1235 exiting (handled 1 request)

Performance Metrics

View statistics: 

sudo mb-rpcd-stats

Example output: 

mb-rpcd Statistics
==================

Uptime: 5 days, 12 hours
Total Requests: 1,247,892
Current Load: 127 req/sec

Workers:
  Active: 4
  Idle: 1
  Total Spawned: 45,678
  Average Lifetime: 234 requests

Response Times:
  Average: 45ms
  Median: 32ms
  95th Percentile: 156ms
  99th Percentile: 289ms

Top Endpoints (last hour):
  1. user.authenticate - 4,567 calls
  2. email.check_spam - 3,234 calls
  3. quarantine.list - 1,890 calls
  4. settings.get - 1,234 calls

Performance over time: 

sudo mb-rpcd-stats --graph --period 24h

Logging

Log Files

Main log: 

/var/log/mailborder/mb-rpcd.log

Error log: 

/var/log/mailborder/mb-rpcd-error.log

Access log (if enabled): 

/var/log/mailborder/mb-rpcd-access.log

Log Levels

Set log level: 

sudo mb-config set rpcd.log_level info
# Levels: debug, info, warning, error, critical

Temporary debug mode: 

sudo mb-rpcd-debug enable
# Enables debug logging for 1 hour

# Disable early
sudo mb-rpcd-debug disable

Log Analysis

Recent errors: 

sudo grep ERROR /var/log/mailborder/mb-rpcd.log | tail -n 20

Request frequency: 

sudo grep REQUEST /var/log/mailborder/mb-rpcd.log | \
  awk '{print $4}' | sort | uniq -c | sort -rn

Slow requests (>1 second): 

sudo grep "completed in" /var/log/mailborder/mb-rpcd.log | \
  awk '$NF > 1000 {print}' | tail -n 20

Database Connection

Connection Pool

Configuration: 

sudo mb-config set rpcd.db_pool_min 5
sudo mb-config set rpcd.db_pool_max 50
sudo mb-config set rpcd.db_idle_timeout 300

Monitor connections: 

# Active connections
sudo mysql -u mailborder -p mailborder -e "SHOW PROCESSLIST"

# Connection count
sudo mysql -u mailborder -p mailborder -e "SHOW STATUS LIKE 'Threads_connected'"

Connection Issues

Test database connectivity: 

sudo mb-rpcd-db-test

Example output: 

Database Connection Test
========================

Host: localhost
Port: 3306
Database: mailborder

Connection: SUCCESS ✓
Query Test: SUCCESS ✓
Response Time: 12ms

Pool Status:
  Min Connections: 5
  Max Connections: 50
  Active: 8
  Idle: 2

Force reconnect: 

sudo systemctl reload mb-rpcd

Security

Socket Permissions

Check socket: 

ls -lh /var/run/mailborder/mb-rpcd.sock

Expected permissions: 

srw-rw---- 1 mailborder mailborder 0 Jan 13 14:23 mb-rpcd.sock

Fix permissions: 

sudo chown mailborder:mailborder /var/run/mailborder/mb-rpcd.sock
sudo chmod 660 /var/run/mailborder/mb-rpcd.sock

Authentication

API key validation:

All RPC requests require authentication: - User session (web interface) - API key (daemons and API clients) - Internal auth token (service-to-service)

Generate API key: 

sudo mb-api-key-generate --email admin@example.com --service mb-filter

Request Isolation

Fork-per-request model provides: - Memory isolation - No shared state - Crash containment - Security boundaries

Verify isolation: 

# Each request gets new worker
watch -n 1 'pgrep -a mb-rpcd | grep worker'

Troubleshooting

Service Won't Start

Check dependencies: 

sudo systemctl status mariadb
sudo systemctl status redis-server

Check logs: 

sudo journalctl -u mb-rpcd -n 50

Common issues:

  1. Database connection failed: 

    sudo mysql -u mailborder -p mailborder -e "SELECT 1"
# If fails, check /etc/mailborder/database.conf

  2. Redis connection failed: 

    redis-cli ping
# Expected: PONG

  3. Socket already in use: 

    sudo rm /var/run/mailborder/mb-rpcd.sock
sudo systemctl start mb-rpcd

  4. Permission error: 

    sudo chown -R mailborder:mailborder /var/run/mailborder/
sudo chmod 755 /var/run/mailborder/

Service Crashes

Check crash log: 

sudo journalctl -u mb-rpcd -n 100 | grep -i "segfault\|crash\|fatal"

Check core dumps: 

sudo coredumpctl list | grep mb-rpcd
sudo coredumpctl info <PID>

Enable core dumps: 

sudo systemctl edit mb-rpcd

Add: 

[Service]
LimitCORE=infinity

High Memory Usage

Check memory: 

sudo systemctl status mb-rpcd | grep Memory
ps aux | grep mb-rpcd

Reduce worker lifetime: 

sudo mb-config set rpcd.max_requests_per_worker 100
sudo systemctl reload mb-rpcd

Increase limits if legitimate: 

sudo systemctl edit mb-rpcd

Add: 

[Service]
MemoryLimit=4G

Slow Response Times

Check worker count: 

pgrep -a mb-rpcd | grep worker | wc -l

Increase workers: 

sudo mb-config set rpcd.max_workers 30
sudo systemctl reload mb-rpcd

Check database performance: 

sudo mysql -u mailborder -p mailborder -e "SHOW PROCESSLIST"

Enable query profiling: 

sudo mb-config set rpcd.profile_queries true
sudo tail -f /var/log/mailborder/mb-rpcd-slow.log

Connection Refused

Check if running: 

sudo systemctl status mb-rpcd

Check socket exists: 

ls -lh /var/run/mailborder/mb-rpcd.sock

Test connection: 

echo '{"method":"system.ping"}' | sudo nc -U /var/run/mailborder/mb-rpcd.sock
# Expected: {"result":"pong"}

API Reference

Core Methods

Authentication: - user.login - User authentication - user.logout - End session - user.validate_session - Check session validity

Configuration: - settings.get - Get setting value - settings.set - Update setting - settings.list - List all settings

Email Management: - email.check_spam - Spam score email - email.scan_virus - Virus scan email - email.apply_policy - Policy evaluation

Quarantine: - quarantine.list - List quarantine - quarantine.release - Release email - quarantine.delete - Delete email

Example Request

Via Unix socket: 

echo '{"method":"system.status","params":{}}' | \
  sudo nc -U /var/run/mailborder/mb-rpcd.sock

Response: 

{
  "status": "success",
  "result": {
    "version": "6.0.0",
    "uptime": 478923,
    "workers": 4,
    "requests_handled": 1247892
  }
}

Best Practices

Performance Optimization

  1. Worker Pool Sizing
  2. Start with CPU core count
  3. Monitor load and adjust

  4. Don't exceed 2x CPU cores

  5. Database Connection Pool

  6. Min: 5 connections
  7. Max: 50 connections (typical)

  8. Idle timeout: 5 minutes

  9. Request Timeout

  10. Default: 30 seconds
  11. Increase for slow operations
  12. Monitor slow query log

Reliability

  1. Monitor continuously 

    # Add to monitoring system
watch -n 10 'sudo mb-rpcd-check'

  2. Log rotation

  3. Automatic via logrotate
  4. Keep 30 days

  5. Compress old logs

  6. Regular restarts

  7. Weekly restart during maintenance window
  8. Clears accumulated state
  9. Fresh start for workers

Security

  1. Socket permissions
  2. Only mailborder group access

  3. Never world-readable

  4. API authentication

  5. Validate all requests
  6. Use API keys for services

  7. Rotate keys regularly

  8. Resource limits

  9. Memory limits prevent OOM
  10. File descriptor limits
  11. CPU time limits

See Also