MailScanner Installation Guide

MailScanner is a free and open-source Mail Security. Email security system for mail gateways

1. Prerequisites

Hardware Requirements:
- CPU: 2 cores minimum (4+ cores recommended)
- RAM: 2GB minimum (4GB+ recommended)
- Storage: 1GB for installation
- Network: 25 ports
Operating System:
- Linux: Any modern distribution (RHEL, Debian, Ubuntu, CentOS, Fedora, Arch, Alpine, openSUSE)
- macOS: 10.14+ (Mojave or newer)
- Windows: Windows Server 2016+ or Windows 10
- FreeBSD: 11.0+
Network Requirements:
- Port 25 (default mailscanner port)
Dependencies:
- perl, spamassassin, clamav
System Access: root or sudo privileges required

2. Supported Operating Systems

This guide supports installation on:

RHEL 8/9 and derivatives (CentOS Stream, Rocky Linux, AlmaLinux)
Debian 11/12
Ubuntu 20.04/22.04/24.04 LTS
Arch Linux (rolling release)
Alpine Linux 3.18+
openSUSE Leap 15.5+ / Tumbleweed
SUSE Linux Enterprise Server (SLES) 15+
macOS 12+ (Monterey and later)
FreeBSD 13+
Windows 10/11/Server 2019+ (where applicable)

3. Installation

RHEL/CentOS/Rocky Linux/AlmaLinux

# Install EPEL repository if needed
sudo dnf install -y epel-release

# Install mailscanner
sudo dnf install -y mailscanner perl, spamassassin, clamav

# Enable and start service
sudo systemctl enable --now mailscanner

# Configure firewall
sudo firewall-cmd --permanent --add-service=mailscanner
sudo firewall-cmd --reload

# Verify installation
mailscanner --version || systemctl status mailscanner

Debian/Ubuntu

# Update package index
sudo apt update

# Install mailscanner
sudo apt install -y mailscanner perl, spamassassin, clamav

# Enable and start service
sudo systemctl enable --now mailscanner

# Configure firewall
sudo ufw allow 25

# Verify installation
mailscanner --version || systemctl status mailscanner

Arch Linux

# Install mailscanner
sudo pacman -S mailscanner

# Enable and start service
sudo systemctl enable --now mailscanner

# Verify installation
mailscanner --version || systemctl status mailscanner

Alpine Linux

# Install mailscanner
apk add --no-cache mailscanner

# Enable and start service
rc-update add mailscanner default
rc-service mailscanner start

# Verify installation
mailscanner --version || rc-service mailscanner status

openSUSE/SLES

# Install mailscanner
sudo zypper install -y mailscanner perl, spamassassin, clamav

# Enable and start service
sudo systemctl enable --now mailscanner

# Configure firewall
sudo firewall-cmd --permanent --add-service=mailscanner
sudo firewall-cmd --reload

# Verify installation
mailscanner --version || systemctl status mailscanner

macOS

# Using Homebrew
brew install mailscanner

# Start service
brew services start mailscanner

# Verify installation
mailscanner --version

FreeBSD

# Using pkg
pkg install mailscanner

# Enable in rc.conf
echo 'mailscanner_enable="YES"' >> /etc/rc.conf

# Start service
service mailscanner start

# Verify installation
mailscanner --version || service mailscanner status

Windows

# Using Chocolatey
choco install mailscanner

# Or using Scoop
scoop install mailscanner

# Verify installation
mailscanner --version

Initial Configuration

Basic Configuration

# Create configuration directory if needed
sudo mkdir -p /etc/MailScanner

# Set up basic configuration
sudo tee /etc/MailScanner/mailscanner.conf << 'EOF'
# MailScanner Configuration
Max Children = 5
EOF

# Test configuration
sudo mailscanner -t || sudo mailscanner configtest

# Reload service
sudo systemctl reload mailscanner

Security Hardening

# Set appropriate permissions
sudo chown -R mailscanner:mailscanner /etc/MailScanner
sudo chmod 750 /etc/MailScanner

# Enable security features
# See security section for detailed hardening steps

5. Service Management

systemd (RHEL, Debian, Ubuntu, Arch, openSUSE)

# Enable service
sudo systemctl enable mailscanner

# Start service
sudo systemctl start mailscanner

# Stop service
sudo systemctl stop mailscanner

# Restart service
sudo systemctl restart mailscanner

# Reload configuration
sudo systemctl reload mailscanner

# Check status
sudo systemctl status mailscanner

# View logs
sudo journalctl -u mailscanner -f

OpenRC (Alpine Linux)

# Enable service
rc-update add mailscanner default

# Start service
rc-service mailscanner start

# Stop service
rc-service mailscanner stop

# Restart service
rc-service mailscanner restart

# Check status
rc-service mailscanner status

rc.d (FreeBSD)

# Enable in /etc/rc.conf
echo 'mailscanner_enable="YES"' >> /etc/rc.conf

# Start service
service mailscanner start

# Stop service
service mailscanner stop

# Restart service
service mailscanner restart

# Check status
service mailscanner status

launchd (macOS)

# Using Homebrew services
brew services start mailscanner
brew services stop mailscanner
brew services restart mailscanner

# Check status
brew services list | grep mailscanner

Windows Service Manager

# Start service
net start mailscanner

# Stop service
net stop mailscanner

# Using PowerShell
Start-Service mailscanner
Stop-Service mailscanner
Restart-Service mailscanner

# Check status
Get-Service mailscanner

Advanced Configuration

Performance Optimization

# Configure performance settings
cat >> /etc/MailScanner/mailscanner.conf << 'EOF'
Max Children = 5
EOF

# Apply system tuning
sudo sysctl -w net.core.somaxconn=65535
sudo sysctl -w net.ipv4.tcp_max_syn_backlog=65535

# Restart service
sudo systemctl restart mailscanner

Clustering and High Availability

# Configure clustering (if supported)
# See official documentation for cluster setup

# Basic load balancing setup example
# Configure multiple instances on different ports

Reverse Proxy Setup

nginx Configuration

upstream mailscanner_backend {
    server 127.0.0.1:25;
    server 127.0.0.1:{default_port}1 backup;
}

server {
    listen 80;
    server_name mailscanner.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name mailscanner.example.com;

    ssl_certificate /etc/ssl/certs/mailscanner.example.com.crt;
    ssl_certificate_key /etc/ssl/private/mailscanner.example.com.key;

    location / {
        proxy_pass http://mailscanner_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket support (if needed)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Apache Configuration

<VirtualHost *:80>
    ServerName mailscanner.example.com
    Redirect permanent / https://mailscanner.example.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName mailscanner.example.com
    
    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/mailscanner.example.com.crt
    SSLCertificateKeyFile /etc/ssl/private/mailscanner.example.com.key
    
    ProxyRequests Off
    ProxyPreserveHost On
    
    ProxyPass / http://127.0.0.1:25/
    ProxyPassReverse / http://127.0.0.1:25/
    
    # WebSocket support (if needed)
    RewriteEngine on
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) "ws://127.0.0.1:25/$1" [P,L]
</VirtualHost>

HAProxy Configuration

frontend mailscanner_frontend
    bind *:80
    bind *:443 ssl crt /etc/ssl/certs/mailscanner.pem
    redirect scheme https if !{ ssl_fc }
    default_backend mailscanner_backend

backend mailscanner_backend
    balance roundrobin
    option httpchk GET /health
    server mailscanner1 127.0.0.1:25 check
    server mailscanner2 127.0.0.1:{default_port}1 check backup

Security Configuration

Basic Security Setup

# Set appropriate permissions
sudo chown -R mailscanner:mailscanner /etc/MailScanner
sudo chmod 750 /etc/MailScanner

# Configure firewall
sudo firewall-cmd --permanent --add-service=mailscanner
sudo firewall-cmd --reload

# Enable SELinux policies (if applicable)
sudo setsebool -P httpd_can_network_connect on

# Configure fail2ban
sudo tee /etc/fail2ban/jail.d/mailscanner.conf << 'EOF'
[mailscanner]
enabled = true
port = 25
filter = mailscanner
logpath = /var/log/mailscanner/*.log
maxretry = 5
bantime = 3600
EOF

SSL/TLS Configuration

# Generate SSL certificates
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout /etc/ssl/private/mailscanner.key \
    -out /etc/ssl/certs/mailscanner.crt

# Configure SSL in mailscanner
# See official documentation for SSL configuration

Database Setup

PostgreSQL Backend (if applicable)

# Create database and user
sudo -u postgres psql << EOF
CREATE DATABASE mailscanner_db;
CREATE USER mailscanner_user WITH ENCRYPTED PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE mailscanner_db TO mailscanner_user;
EOF

# Configure mailscanner to use PostgreSQL
# See official documentation for database configuration

MySQL/MariaDB Backend (if applicable)

# Create database and user
sudo mysql << EOF
CREATE DATABASE mailscanner_db;
CREATE USER 'mailscanner_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON mailscanner_db.* TO 'mailscanner_user'@'localhost';
FLUSH PRIVILEGES;
EOF

Performance Optimization

System Tuning

# Kernel parameters
sudo tee -a /etc/sysctl.conf << EOF
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.ip_local_port_range = 1024 65535
net.core.netdev_max_backlog = 5000
vm.swappiness = 10
EOF

sudo sysctl -p

# MailScanner specific tuning
Max Children = 5

Resource Limits

# Configure system limits
sudo tee -a /etc/security/limits.conf << EOF
mailscanner soft nofile 65535
mailscanner hard nofile 65535
mailscanner soft nproc 32768
mailscanner hard nproc 32768
EOF

Monitoring

Prometheus Integration

# prometheus.yml configuration
scrape_configs:
  - job_name: 'mailscanner'
    static_configs:
      - targets: ['localhost:25']
    metrics_path: '/metrics'

Health Checks

# Basic health check script
#!/bin/bash
if systemctl is-active --quiet mailscanner; then
    echo "MailScanner is running"
    exit 0
else
    echo "MailScanner is not running"
    exit 1
fi

Log Monitoring

# Configure log rotation
sudo tee /etc/logrotate.d/mailscanner << 'EOF'
/var/log/mailscanner/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    create 0640 mailscanner mailscanner
    postrotate
        systemctl reload mailscanner > /dev/null 2>&1 || true
    endscript
}
EOF

9. Backup and Restore

Backup Script

#!/bin/bash
# MailScanner backup script
BACKUP_DIR="/backup/mailscanner"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

# Stop service (if required)
systemctl stop mailscanner

# Backup configuration
tar -czf "$BACKUP_DIR/mailscanner-config-$DATE.tar.gz" /etc/MailScanner

# Backup data (adjust paths as needed)
tar -czf "$BACKUP_DIR/mailscanner-data-$DATE.tar.gz" /var/lib/mailscanner

# Start service
systemctl start mailscanner

# Clean old backups (keep 30 days)
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete

echo "Backup completed: $BACKUP_DIR"

Restore Procedure

# Stop service
sudo systemctl stop mailscanner

# Restore configuration
sudo tar -xzf /backup/mailscanner/mailscanner-config-*.tar.gz -C /

# Restore data
sudo tar -xzf /backup/mailscanner/mailscanner-data-*.tar.gz -C /

# Set permissions
sudo chown -R mailscanner:mailscanner /etc/MailScanner
sudo chown -R mailscanner:mailscanner /var/lib/mailscanner

# Start service
sudo systemctl start mailscanner

6. Troubleshooting

Common Issues

Service won't start:

# Check logs
sudo journalctl -u mailscanner -n 100
sudo tail -f /var/log/mailscanner/*.log

# Check configuration
sudo mailscanner -t || sudo mailscanner configtest

# Check permissions
ls -la /etc/MailScanner
ls -la /var/lib/mailscanner

Connection refused:

# Check if service is listening
sudo ss -tlnp | grep 25
sudo netstat -tlnp | grep 25

# Check firewall
sudo firewall-cmd --list-all
sudo iptables -L -n

# Test connection
telnet localhost 25
nc -zv localhost 25

Performance issues:

# Check resource usage
top -p $(pgrep MailScanner)
htop -p $(pgrep MailScanner)

# Check connections
ss -ant | grep :25 | wc -l

# Monitor I/O
iotop -p $(pgrep MailScanner)

Debug Mode

# Run in debug mode
sudo mailscanner -d
# or
sudo mailscanner debug

# Increase log verbosity
# Edit configuration to enable debug logging

Integration Examples

Docker Compose

version: '3.8'
services:
  mailscanner:
    image: mailscanner:latest
    container_name: mailscanner
    ports:
      - "25:25"
    volumes:
      - ./config:/etc/MailScanner
      - ./data:/var/lib/mailscanner
    environment:
      - mailscanner_CONFIG=/etc/MailScanner/mailscanner.conf
    restart: unless-stopped
    networks:
      - mailscanner_net

networks:
  mailscanner_net:
    driver: bridge

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mailscanner
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mailscanner
  template:
    metadata:
      labels:
        app: mailscanner
    spec:
      containers:
      - name: mailscanner
        image: mailscanner:latest
        ports:
        - containerPort: 25
        volumeMounts:
        - name: config
          mountPath: /etc/MailScanner
      volumes:
      - name: config
        configMap:
          name: mailscanner-config
---
apiVersion: v1
kind: Service
metadata:
  name: mailscanner
spec:
  selector:
    app: mailscanner
  ports:
  - port: 25
    targetPort: 25
  type: LoadBalancer

Ansible Playbook

---
- name: Install and configure MailScanner
  hosts: all
  become: yes
  tasks:
    - name: Install mailscanner
      package:
        name: mailscanner
        state: present
    
    - name: Configure mailscanner
      template:
        src: mailscanner.conf.j2
        dest: /etc/MailScanner/mailscanner.conf
        owner: mailscanner
        group: mailscanner
        mode: '0640'
      notify: restart mailscanner
    
    - name: Start and enable mailscanner
      systemd:
        name: mailscanner
        state: started
        enabled: yes
  
  handlers:
    - name: restart mailscanner
      systemd:
        name: mailscanner
        state: restarted

Maintenance

Update Procedures

# RHEL/CentOS/Rocky/AlmaLinux
sudo dnf update mailscanner

# Debian/Ubuntu
sudo apt update && sudo apt upgrade mailscanner

# Arch Linux
sudo pacman -Syu mailscanner

# Alpine Linux
apk update && apk upgrade mailscanner

# openSUSE
sudo zypper update mailscanner

# FreeBSD
pkg update && pkg upgrade mailscanner

# Always backup before updates
tar -czf /backup/mailscanner-pre-update-$(date +%Y%m%d).tar.gz /etc/MailScanner

# Restart after updates
sudo systemctl restart mailscanner

Regular Maintenance Tasks

# Clean logs
find /var/log/mailscanner -name "*.log" -mtime +30 -delete

# Verify integrity
sudo mailscanner --verify || sudo mailscanner check

# Update databases (if applicable)
sudo mailscanner-update-db

# Optimize performance
sudo mailscanner-optimize

# Check for security updates
sudo mailscanner --security-check

Additional Resources

Official Documentation: https://docs.mailscanner.org/
GitHub Repository: https://github.com/mailscanner/mailscanner
Community Forum: https://forum.mailscanner.org/
Wiki: https://wiki.mailscanner.org/
Comparison vs Amavisd-new, MIMEDefang, ASSP: https://docs.mailscanner.org/comparison

Note: This guide is part of the HowToMgr collection. Always refer to official documentation for the most up-to-date information.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE.md		LICENSE.md
META.json		META.json
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

MailScanner Installation Guide

Table of Contents

1. Prerequisites

2. Supported Operating Systems

3. Installation

RHEL/CentOS/Rocky Linux/AlmaLinux

Debian/Ubuntu

Arch Linux

Alpine Linux

openSUSE/SLES

macOS

FreeBSD

Windows

Initial Configuration

Basic Configuration

Security Hardening

5. Service Management

systemd (RHEL, Debian, Ubuntu, Arch, openSUSE)

OpenRC (Alpine Linux)

rc.d (FreeBSD)

launchd (macOS)

Windows Service Manager

Advanced Configuration

Performance Optimization

Clustering and High Availability

Reverse Proxy Setup

nginx Configuration

Apache Configuration

HAProxy Configuration

Security Configuration

Basic Security Setup

SSL/TLS Configuration

Database Setup

PostgreSQL Backend (if applicable)

MySQL/MariaDB Backend (if applicable)

Performance Optimization

System Tuning

Resource Limits

Monitoring

Prometheus Integration

Health Checks

Log Monitoring

9. Backup and Restore

Backup Script

Restore Procedure

6. Troubleshooting

Common Issues

Debug Mode

Integration Examples

Docker Compose

Kubernetes Deployment

Ansible Playbook

Maintenance

Update Procedures

Regular Maintenance Tasks

Additional Resources

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages