Common Issues¶

This guide covers the most frequently encountered issues in Mailborder V6 and their solutions.

Email Issues¶

Email Not Arriving at Mailborder¶

Symptoms: - No email reaching Mailborder - Dashboard shows zero message counts - Mailq is empty

Diagnosis:

Check MX records:
```
dig yourdomain.com MX +short
```
Should return Mailborder server hostname/IP.
Check port 25 open:
```
sudo netstat -tlnp | grep :25
```
Should show Postfix listening.
Test external connectivity:
```
telnet mail border.example.com 25
```
From external machine.

Check firewall:

sudo iptables -L -n | grep 25
sudo ufw status

Solutions:

MX not pointing to Mailborder: Update DNS MX record
Firewall blocking: Allow port 25 inbound
Postfix not running: sudo systemctl start postfix
Wrong interface: Check Postfix inet_interfaces setting

Email Not Being Delivered¶

Symptoms: - Email accepted but never reaches users - Growing mail queue - Delivery errors in logs

Diagnosis:

Check mail queue:
```
sudo mailq
```
View deferred messages:
```
sudo mailq | grep MAILER-DAEMON
```
Check relay host configuration:
```
sudo postconf relayhost
```
Test relay connectivity:
```
telnet your-mail-server.com 25
```

Check virtuoso logs:

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

Solutions:

Relay host unreachable: Check network, firewall, DNS
Relay rejecting: Add Mailborder IP to relay's allowed senders
Authentication failure: Verify relay credentials
TLS required: Enable TLS in relay configuration
Wrong relay host: Update relay host setting

Force queue flush:

sudo postqueue -f

All Email Going to Quarantine¶

Symptoms: - Every email quarantined - High spam scores on legitimate email - User complaints about missing email

Diagnosis:

Check spam thresholds: Web Interface → Email Security → Spam Filtering
Review quarantine: Web Interface → Email Security → Quarantine
Check recent config changes:
```
sudo mb-audit --type config --last 24h
```
Test with known-good email: Send from trusted source, check score.

Check Rspamd status:

sudo systemctl status rspamd
sudo rspamc stat

Solutions:

Thresholds too low: Increase spam threshold (6.0 → 8.0)
RBL false positives: Disable aggressive RBLs
Rspamd misconfigured: Check Rspamd logs
Recent policy change: Revert to previous settings
DNS issues: Test DNS resolution

Temporary workaround:

# Disable spam filtering temporarily
sudo mb-config set spam.enabled false
sudo systemctl reload mb-filter

Legitimate Email Marked as Spam¶

Symptoms: - Specific senders always quarantined - Business partners' email blocked - False positive rate high

Diagnosis:

Check spam score breakdown: View email in quarantine, see detailed score.
Identify triggering rules: Look for high-scoring tests.
Check sender authentication: SPF, DKIM, DMARC results.

Solutions:

Whitelist sender:

sudo mb-whitelist add sender@example.com

Or via Web Interface: Email Security → Whitelist/Blacklist → Add Entry

Adjust thresholds: Increase spam threshold for specific domain:

sudo mb-policy add-exception --domain example.com --threshold 10.0

Train Bayesian filter: Mark false positives as ham (legitimate).

Spam Getting Through¶

Symptoms: - Obvious spam delivered - Low spam scores on spam - User complaints

Diagnosis:

Review spam samples: Check why they scored low.
Check enabled engines: Verify Rspamd, RBLs enabled.
Check blacklists: Are known spam sources whitelisted?

Solutions:

Lower thresholds:

sudo mb-config set spam.threshold.quarantine 5.0
sudo mb-config set spam.threshold.reject 12.0

Enable additional engines: - Enable SpamAssassin - Add more RBLs - Enable greylisting

Blacklist persistent spammers:

sudo mb-blacklist add spammer@spam.com

Update signatures:

sudo mb-update --signatures

Service Issues¶

Service Won't Start¶

Symptoms: - systemctl start mb-rpcd fails - Service immediately stops - Error in logs

Diagnosis:

Check service status:
```
sudo systemctl status mb-rpcd
```

View detailed logs:

sudo journalctl -u mb-rpcd -n 100 --no-pager

Check dependencies:

sudo systemctl list-dependencies mb-rpcd

Verify configuration:
```
sudo mb-config --verify
```

Check permissions:

ls -la /run/mailborder/
ls -la /var/log/mailborder/

Solutions:

Dependency not running:

# Check MariaDB
sudo systemctl status mariadb
sudo systemctl start mariadb

# Check Redis
sudo systemctl status redis
sudo systemctl start redis

Configuration error:

# Restore previous config
sudo mb-config restore

# Or reset to defaults
sudo mb-config reset --section services

Permission issue:

# Fix ownership
sudo chown -R mailborder:mailborder /run/mailborder
sudo chown -R mailborder:mailborder /var/log/mailborder

# Recreate socket directory
sudo systemctl restart mb-rpcd

Port already in use:

# Find conflicting process
sudo lsof -i :9001

# Kill or reconfigure

Services Keep Restarting¶

Symptoms: - Services cycling (start, crash, restart) - mb-status shows fluctuating states - High restart counts in SystemD

Diagnosis:

Check crash logs:

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

Monitor in real-time:

watch -n 1 "sudo systemctl status mb-filter | head -20"

Check resource limits:

sudo systemctl status mb-filter | grep -i memory
sudo systemctl status mb-filter | grep -i oom

Check system resources:
```
free -h
df -h
top
```

Solutions:

Out of memory:

# Increase memory limit
sudo systemctl edit mb-filter

Add:

[Service]
MemoryLimit=1024M

Then:

sudo systemctl daemon-reload
sudo systemctl restart mb-filter

Configuration error:

# Disable auto-restart to diagnose
sudo systemctl edit mb-filter

Add:

[Service]
Restart=no

Fix issue, then re-enable restart.

Dependency failure: Check if Rspamd, ClamAV, MariaDB are stable.

High CPU Usage¶

Symptoms: - Server load high - Slow email processing - Web interface sluggish

Diagnosis:

Identify CPU hog:
```
top -u mailborder
```
Check process counts:
```
ps aux | grep mb- | wc -l
```

Review scanning times:

sudo grep "scan_time" /var/log/mailborder/filter.log | tail -20

Check email queue:
```
sudo mailq | wc -l
```

Solutions:

Too many concurrent scans:

# Reduce concurrent processes
sudo mb-config set system.max_concurrent_scans 8
sudo systemctl reload mb-filter

Large emails:

# Reduce max message size
sudo mb-config set system.max_message_size 25M

ClamAV scanning:

# Reduce ClamAV scan depth
sudo mb-config set antivirus.max_recursion 10

Rspamd learning:

# Reduce Bayesian learning frequency
sudo rspamc -h /run/rspamd/rspamd.sock learn_cache

High Memory Usage¶

Symptoms: - RAM usage >90% - Swapping active - OOM kills

Diagnosis:

Check memory usage:
```
free -h
top
```
Identify memory hog:
```
ps aux --sort=-%mem | head -20
```

Check for leaks:

sudo systemctl status mb-rpcd | grep "Memory:"

Solutions:

Reduce PHP memory:

sudo mb-config set system.php_memory_limit 256M
sudo systemctl reload php8.1-fpm

Reduce concurrent processes:

sudo mb-config set system.max_concurrent_scans 4

Add swap space:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Upgrade RAM: Physical upgrade or increase VM allocation.

Web Interface Issues¶

Cannot Access Web Interface¶

Symptoms: - Browser shows "Connection refused" - Timeout connecting - SSL error

Diagnosis:

Check Nginx:
```
sudo systemctl status nginx
```
Check port 443:
```
sudo netstat -tlnp | grep :443
```
Test locally:
```
curl -k https://localhost/
```
Check firewall:
```
sudo iptables -L -n | grep 443
```
Check SSL certificate:
```
sudo nginx -t
```

Solutions:

Nginx not running:

sudo systemctl start nginx

Firewall blocking:

sudo ufw allow 443/tcp

SSL certificate error:

# Check certificate
sudo ls -la /etc/mailborder/ssl/

# Regenerate self-signed
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/mailborder/ssl/mailborder.key \
  -out /etc/mailborder/ssl/mailborder.crt

sudo systemctl reload nginx

Wrong interface: Check Nginx listen directive in /etc/nginx/sites-available/mailborder.

Symptoms: - Credentials rejected - "Invalid password" error - 2FA code not accepted

Diagnosis:

Verify username/email:
```
sudo mb-admin-list
```
Check account enabled:
```
sudo mb-admin-show admin@example.com
```
Check mb-rpcd:
```
sudo systemctl status mb-rpcd
```

Check logs:

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

Solutions:

Forgot password:

sudo mb-admin-reset --email admin@example.com

Account locked:

sudo mb-admin-unlock --email admin@example.com

2FA sync issue: Check device time:

timedatectl status

Temporarily disable 2FA:

sudo mb-admin-disable-2fa --email admin@example.com

Database connection:

# Test database
sudo mysql -u mailborder -p mailborder -e "SELECT 1"

Web Interface Slow¶

Symptoms: - Pages take >5 seconds to load - AJAX requests timeout - Timeouts in browser console

Diagnosis:

Check Redis:

sudo systemctl status redis
redis-cli ping

Check database:
```
sudo mysql -e "SHOW PROCESSLIST;"
```
Check PHP-FPM:
```
sudo systemctl status php8.1-fpm
```
Check mb-rpcd:
```
sudo systemctl status mb-rpcd
```

Solutions:

Redis not running:

sudo systemctl start redis

Database slow queries:

# Optimize tables
sudo mb-maintenance --optimize-db

PHP-FPM pool size:

# Increase workers
sudo nano /etc/php/8.1/fpm/pool.d/mailborder.conf

Change:

pm.max_children = 20

sudo systemctl reload php8.1-fpm

Clear cache:

sudo redis-cli FLUSHALL

Authentication Issues¶

Two-Factor Authentication Problems¶

Symptoms: - TOTP code always invalid - "Code expired" error - Cannot login with 2FA

Diagnosis:

Check time sync:
```
timedatectl status
```
Check time difference:
```
date
```
Compare with authenticator app time.

Solutions:

Time not synced:

sudo timedatectl set-ntp true
sudo systemctl restart systemd-timesyncd

Large time difference:

# Sync immediately
sudo ntpdate pool.ntp.org

Disable 2FA (emergency):

sudo mb-admin-disable-2fa --email admin@example.com

Passkey Not Working¶

Symptoms: - Passkey prompt doesn't appear - "Invalid passkey" error - Browser compatibility issue

Diagnosis:

Check browser support: Must be Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
Check HTTPS: Passkeys require HTTPS (not HTTP)

Check logs:

sudo tail -f /var/log/mailborder/rpcd.log | grep passkey

Solutions:

Browser outdated: Update to latest version.

HTTP instead of HTTPS: Always use https:// URL.

Passkey deleted: Remove and re-register passkey.

Database issue:

# Check credentials table
sudo mysql mailborder -e "SELECT COUNT(*) FROM users_admin_credentials;"

Database Issues¶

Database Connection Failed¶

Symptoms: - Services can't start - "Can't connect to MySQL" errors - Web interface shows database error

Diagnosis:

Check MariaDB:
```
sudo systemctl status mariadb
```
Test connection:
```
sudo mysql -u root -p
```

Check credentials:

sudo grep db_pass /etc/mailborder/engine.cf

Solutions:

MariaDB not running:

sudo systemctl start mariadb

Wrong password:

# Reset password
sudo mysql

ALTER USER 'mailborder'@'localhost' IDENTIFIED BY 'new-password';
FLUSH PRIVILEGES;

Update config:

sudo mb-config set database.password 'new-password'

Corrupt tables:

sudo mysqlcheck -u root -p mailborder --auto-repair

Database Performance Issues¶

Symptoms: - Slow queries - High CPU usage by MariaDB - Timeouts

Diagnosis:

Check slow queries:
```
sudo mysql -e "SHOW PROCESSLIST;"
```

Check table sizes:

sudo mysql mailborder -e "
SELECT table_name,
       ROUND(((data_length + index_length) / 1024 / 1024), 2) AS 'Size (MB)'
FROM information_schema.TABLES
WHERE table_schema = 'mailborder'
ORDER BY (data_length + index_length) DESC;"

Solutions:

Optimize tables:

sudo mb-maintenance --optimize-db

Rebuild indexes:

sudo mysql mailborder -e "ANALYZE TABLE email_logs;"

Increase buffer pool:

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Add:

innodb_buffer_pool_size = 1G

sudo systemctl restart mariadb

Next Steps¶

For specific issue types, see:

Common Issues¶

Email Issues¶

Email Not Arriving at Mailborder¶

Email Not Being Delivered¶

All Email Going to Quarantine¶

Legitimate Email Marked as Spam¶

Spam Getting Through¶

Service Issues¶

Service Won't Start¶

Services Keep Restarting¶

High CPU Usage¶

High Memory Usage¶

Web Interface Issues¶

Cannot Access Web Interface¶

Login Not Working¶

Web Interface Slow¶

Authentication Issues¶

Two-Factor Authentication Problems¶

Passkey Not Working¶

Database Issues¶

Database Connection Failed¶

Database Performance Issues¶

Next Steps¶