SMS Forwarder

A systemd service that forwards SMS messages from a GSM modem to email. Useful for monitoring and alerting systems, remote locations, or any scenario where you need to receive SMS notifications via email.

Hardware Requirements

• GSM modem compatible with ModemManager (Quectel, Sierra Wireless, etc.)
• USB connection to host system
• Active SIM card with SMS capability
• Linux system with systemd

Quick Start

1. Installation

git clone https://github.com/The1TrueJoe/sms-forwarder.git
cd sms-forwarder
sudo ./install.sh

The installer will:

• Install system dependencies (ModemManager, Python 3, etc.)
• Create dedicated system user
• Set up Python virtual environment in /opt/sms-forwarder
• Install systemd service
• Create command line tools

2. Configuration

Configure SMTP settings using the interactive tool:

sudo sms-forwarder-config

This opens a curses interface where you can set:

• Email recipient and sender addresses
• SMTP server settings (supports Gmail, Zoho, etc.)
• Test SMTP connection with real-time feedback

3. Start the Service

# Enable auto-start on boot
sudo systemctl enable sms-forwarder

# Start the service
sudo systemctl start sms-forwarder

# Check status
sudo systemctl status sms-forwarder

Available Commands

After installation, these commands are available:

Core Commands

• sms-forwarder - Run the SMS forwarder (manual mode shows fancy output)
• sms-forwarder-config - Configure SMTP settings (requires sudo)

Command Options

# Show modem and configuration info
sudo sms-forwarder --info

# Send test email
sudo sms-forwarder --email

# List recent SMS messages
sudo sms-forwarder --list-sms [count]

# Wait for incoming SMS (interactive mode)
sudo sms-forwarder --wait-sms

Service Management

# Enable auto-start
sudo systemctl enable sms-forwarder

# Start/stop/restart service
sudo systemctl start sms-forwarder
sudo systemctl stop sms-forwarder
sudo systemctl restart sms-forwarder

# Check status and logs
sudo systemctl status sms-forwarder
sudo journalctl -u sms-forwarder -f

Configuration Details

Configuration is stored in /etc/sms-forwarder/config.env:

# Email settings
EMAIL_TO=your-email@domain.com
EMAIL_FROM=sender@domain.com
EMAIL_SMTP_SERVER=smtp.zoho.com
EMAIL_SMTP_PORT=465
EMAIL_PASSWORD=your-app-password

# Optional logging
LOG_LEVEL=INFO

Supported SMTP Providers

The system automatically detects SSL vs STARTTLS:

• Port 465: SSL from start (Zoho, Gmail SSL)
• Port 587: STARTTLS (Gmail, most providers)

Popular configurations:

• Gmail: smtp.gmail.com:587 (use app password)
• Zoho: smtp.zoho.com:465 (use regular password)
• Outlook: smtp-mail.outlook.com:587

SMS Processing

1. Detection: Monitors ModemManager for new SMS messages
2. Deduplication: Prevents duplicate processing of same message
3. Email Formatting: Creates readable email with sender, time, and content
4. Delivery: Sends via configured SMTP with proper SSL/STARTTLS
5. Logging: Records all activity for monitoring

Hardware Setup

Modem Detection

Check if your modem is detected:

# List modems
mmcli --list-modems

# Get modem details (replace X with modem number)
mmcli --modem=X

Common Modem Types

Quectel Series (EC25, EG25, etc.):

• Usually appears as /dev/ttyUSB0-3
• ModemManager automatically detects
• Excellent Linux compatibility

Sierra Wireless:

• Well supported by ModemManager
• Various form factors available

Huawei USB Dongles:

• May require usb_modeswitch
• Check vendor documentation

Troubleshooting Modem Issues

# Check USB devices
lsusb | grep -i modem

# Check ModemManager status
sudo systemctl status ModemManager

# Check for device conflicts
sudo fuser /dev/ttyUSB*

# Restart ModemManager if needed
sudo systemctl restart ModemManager

Monitoring and Troubleshooting

Service Status

# Quick status check
sudo systemctl is-active sms-forwarder

# Detailed status
sudo systemctl status sms-forwarder

# Recent logs
sudo journalctl -u sms-forwarder -n 50

# Follow logs in real-time
sudo journalctl -u sms-forwarder -f

Testing Components

# Test modem connection
sudo sms-forwarder --info

# Test email configuration
sudo sms-forwarder --email

# View recent SMS messages
sudo sms-forwarder --list-sms 5

Common Issues

No modem detected:

# Check ModemManager
sudo systemctl status ModemManager
mmcli --list-modems

# Check SIM card
mmcli --modem=0 --simple-status

Email delivery fails:

# Test SMTP settings
sudo sms-forwarder --email

# Check configuration
sudo sms-forwarder --info

# Reconfigure if needed
sudo sms-forwarder-config

Service won't start:

# Check detailed error
sudo journalctl -u sms-forwarder -n 50

# Check file permissions
ls -la /opt/sms-forwarder/
ls -la /etc/sms-forwarder/

# Reinstall if needed
sudo ./install.sh

Security Considerations

• Service runs as dedicated parkeze user (not root)
• Configuration files protected with appropriate permissions
• SSL/TLS encryption for email transmission
• Modem access via dialout group membership
• No network ports opened

Uninstallation

To remove the service:

# Stop and disable service
sudo systemctl stop sms-forwarder
sudo systemctl disable sms-forwarder

# Remove files
sudo rm -rf /opt/sms-forwarder
sudo rm -rf /etc/sms-forwarder
sudo rm -f /etc/systemd/system/sms-forwarder.service
sudo rm -f /usr/local/bin/sms-forwarder*

# Remove user (optional)
sudo userdel parkeze

# Reload systemd
sudo systemctl daemon-reload

Local Testing

# Clone repository
git clone https://github.com/The1TrueJoe/sms-forwarder.git
cd sms-forwarder

# Install in development mode
sudo ./install.sh

# Test configuration
sudo sms-forwarder-config

# Run interactively for testing
sudo sms-forwarder --info
sudo sms-forwarder --wait-sms

License

This project is licensed under the MIT License - see the LICENSE file for details.