pfSense Monitor Agent

A Python-based monitoring agent that tracks pfSense CPU usage and load average, sending Gmail alerts when configured thresholds are exceeded.

Features

• Real-time Monitoring: Continuously monitors pfSense system metrics
• Configurable Thresholds: Set custom CPU and load average alert thresholds
• Gmail Alerts: Sends email notifications when thresholds are exceeded
• Alert Cooldown: Prevents spam by limiting alert frequency
• Comprehensive Logging: Detailed logging to file and console
• Easy Setup: Interactive configuration script

Quick Start

1. Install Dependencies

   pip3 install -r requirements.txt

2. Run Setup

   python3 setup.py

   This will guide you through configuring:

   • pfSense connection details
   • Alert thresholds
   • Gmail credentials
   • Monitoring intervals

3. Start Monitoring

   python3 pfsense_monitor.py

Configuration

The config.json file contains all settings:

{
  "pfsense": {
    "host": "192.168.1.1",
    "username": "admin",
    "password": "your_password",
    "verify_ssl": false
  },
  "thresholds": {
    "cpu_percent": 80,
    "load_avg": 2.0
  },
  "gmail": {
    "from_email": "your_email@gmail.com",
    "to_email": "alerts@example.com",
    "app_password": "your_app_password"
  },
  "check_interval_seconds": 300,
  "alert_cooldown_minutes": 30,
  "log_level": "INFO"
}

Gmail Setup

1. Enable 2-Factor Authentication on your Google account
2. Go to Google Account > Security > 2-Step Verification > App passwords
3. Generate an app password for "Mail"
4. Use this app password in the configuration (not your regular password)

Monitoring Metrics

• CPU Usage: Percentage of CPU utilization
• Load Average: System load average (1-minute)

Alert System

• Alerts are sent when metrics exceed configured thresholds
• Cooldown period prevents alert spam
• Email includes timestamp, host info, and specific threshold violations

Logging

Logs are written to:

• pfsense_monitor.log (file)
• Console output

Log levels: DEBUG, INFO, WARNING, ERROR

Troubleshooting

Connection Issues

• Verify pfSense credentials and network connectivity
• Check if pfSense web interface is accessible
• Ensure SSL settings match your pfSense configuration

Gmail Issues

• Confirm 2FA is enabled and app password is correct
• Check Gmail security settings
• Verify email addresses are correct

Testing

# Test pfSense connection only
python3 setup.py test

Customization

The monitor can be extended to track additional metrics by modifying:

• parse_system_stats() method for new metrics
• check_thresholds() method for new alert conditions
• Configuration file for new settings

Requirements

• Python 3.6+
• Network access to pfSense web interface
• Gmail account with app password
• pfSense with web interface enabled

License

MIT License - feel free to modify and distribute.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

If you encounter issues:

1. Check the logs in pfsense_monitor.log
2. Verify your configuration in config.json
3. Test connection with python3 setup.py test
4. Open an issue on GitHub with logs and configuration (remove sensitive data)

Changelog

v1.0.0

• Initial release
• CPU and load average monitoring
• Gmail alert system
• Configurable thresholds and intervals
• Systemd service support