Automated backup and monitoring tool for pfSense firewalls. Built for homelabs.
pfSentinel connects to your pfSense devices over SSH or HTTPS and backs up configuration files, RRD data, package configs, DHCP leases, certificates, logs, ZFS snapshots, and full filesystem archives. It includes change detection, compression, scheduled backups, and notifications via Telegram, Slack, or Windows toast.
- Full config backup via SSH (SFTP) or HTTPS with CSRF-aware login
- Extended backup targets -- RRD graphs, package configs, DHCP leases, alias files, certificates, system logs
- ZFS snapshots with incremental send (pfSense 2.5+)
- Filesystem archives (tar.gz) as a non-ZFS fallback
- Change detection -- only saves when config sections actually change
- SHA-256 verification for every backup file
- Scheduled backups via Windows Task Scheduler or cron
- Notifications -- Telegram, Slack, Windows toast, Windows Event Log
- SSH key authentication -- no password required
- Credential security -- passwords stored in OS keyring, never in config files
- Self-update -- check for and install new releases from GitHub
- Cross-platform -- Windows, Linux, macOS
Download a pre-built binary (no Python required):
Or install with pip (Python 3.13+):
pip install pfsentinelThen:
pfs setup # guided first-time wizard
pfs device add # add your pfSense device
pfs backup run # run your first backupSee the Installation Guide for all installation methods.
| Document | Description |
|---|---|
| Installation Guide | pip, pre-built binary, and from-source installation |
| Usage Guide | CLI reference, configuration, scheduling, notifications |
| Extended Backups | RRD, packages, DHCP, certs, logs, ZFS, archives |
| Security Policy | Vulnerability reporting, design decisions, credential storage |
| Contributing | Development setup, code style, pull requests |
| Changelog | Version history |
| Target | Method | Description |
|---|---|---|
| XML Config | SSH / HTTPS | Full pfSense configuration (config.xml) |
| RRD Data | SSH | Traffic and performance graphs |
| Package Configs | SSH | Installed package settings |
| DHCP Leases | SSH | Active DHCP lease table |
| Alias Files | SSH | URL tables and external alias files |
| Certificates | SSH | SSL/TLS certs from the filesystem |
| System Logs | SSH | Filter log, system log, custom log files |
| ZFS Snapshot | SSH | Full or incremental ZFS snapshot stream |
| Filesystem Archive | SSH | Tar archive of critical directories |
pfSentinel is built on these open-source libraries:
| Library | License | Purpose |
|---|---|---|
| Typer | MIT | CLI framework |
| Rich | MIT | Terminal formatting |
| Pydantic | MIT | Data validation |
| Paramiko | LGPL-2.1 | SSH/SFTP connections |
| httpx | BSD-3-Clause | HTTPS requests |
| cryptography | Apache-2.0 / BSD-3-Clause | SSH key handling |
| Loguru | MIT | Logging |
| PyYAML | MIT | YAML parsing |
| Requests | Apache-2.0 | HTTP client |
| Packaging | Apache-2.0 / BSD-2-Clause | Version parsing |
Paramiko is the only runtime dependency with a copyleft license (LGPL-2.1). When installed via pip, users can freely replace it. For binary releases, pfSentinel uses --onedir bundling so Paramiko remains replaceable. See docs/LICENSE_AUDIT.md for the full dependency license audit.
Contributions are welcome! Please read the Contributing Guide before submitting a pull request.
If you find a bug or have a feature request, open an issue.