OPNsense ZFS Boot Environment Automation 🔄

Automated ZFS Boot Environment (snapshot) creation and retention management for OPNsense firewalls with intelligent cleanup policies.

If this helped you, please give it a star! It helps others find this solution.

Features

• Automated Boot Environment Creation: Daily and weekly snapshots visible in OPNsense Web GUI
• Intelligent Retention Policies:
  • Daily snapshots kept for 30 days
  • Weekly snapshots kept for 52 weeks (1 year)
• Web GUI Integration: All snapshots visible under System > Snapshots
• Automatic Cleanup: Old snapshots automatically removed based on retention policy
• Comprehensive Logging: Detailed logs for monitoring and troubleshooting
• Safety First: Never deletes active boot environments
• Cron Integration: Uses OPNsense's built-in cron system via configd

Why Use This?

Without This Script ❌

• Manual snapshot creation before every update
• No automatic cleanup - snapshots accumulate indefinitely
• Risk of running out of disk space
• Inconsistent backup strategy
• Time-consuming maintenance

With This Script ✅

• Set & Forget: Automatic daily and weekly snapshots
• Smart Cleanup: Old snapshots automatically removed
• Update Safety: Always have recent recovery points before firmware updates
• Disaster Recovery: Quick rollback capability via Web GUI or boot menu
• Space Efficient: ZFS copy-on-write technology minimizes storage usage
• Production Ready: Handles edge cases and prevents accidental deletions

Prerequisites

• OPNsense 24.7+ with ZFS root filesystem
• SSH access or Web GUI command prompt access
• ZFS-based installation (UFS not supported)

Note: OPNsense must be installed with ZFS filesystem. You can check with: zpool status

⚡ Quick Installation

Manual Installation

1. SSH into your OPNsense system or use Diagnostics > Command Prompt in the Web GUI

2. Download and run the installation script:

# Make executable and run
chmod +x zfs_snapshot_setup.sh
./zfs_snapshot_setup.sh

3. Configure Cron Jobs in Web GUI:

   • Navigate to System > Settings > Cron
   • Click "+" to add new jobs

   Daily Snapshots:

   • Command: ZFS Daily Boot Environment with 30-day retention
   • Schedule: 0 23 * * * (11:00 PM daily)

   Weekly Snapshots:

   • Command: ZFS Weekly Boot Environment with 52-week retention
   • Schedule: 0 22 * * 0 (10:00 PM Sundays)

4. Click Apply and you're done!

💾 Storage Requirements

Disk Size	Recommendation
128GB	⚠️ Minimum (tight but workable)
256GB	✅ Recommended (plenty of space)
512GB	✅ Excellent (future-proof)

Estimated Usage:

• Base OPNsense: ~4GB
• 30 daily snapshots: ~750MB
• 52 weekly snapshots: ~10GB
• Total: ~15GB (leaves plenty of room on 256GB)

🔍 Monitoring & Maintenance

View Your Snapshots

• Web GUI: System > Snapshots
• Command Line: bectl list

Check Logs

# Daily snapshot logs
tail -f /var/log/zfs_daily_snapshots.log

# Weekly snapshot logs  
tail -f /var/log/zfs_weekly_snapshots.log

Manual Operations

# Create manual snapshot
bectl create backup-before-config-change

# List all boot environments
bectl list

# Activate a different boot environment
bectl activate daily-20240829

# Delete a boot environment (if not active)
bectl destroy old-snapshot-name

Recovery Process

From Web GUI

1. Go to System > Snapshots
2. Select desired snapshot
3. Click "Activate"
4. Reboot system

From Boot Menu

1. Boot system and wait for boot menu
2. Press "8" for Boot Options
3. Press "2" to cycle through snapshots
4. Select desired snapshot and boot

Configuration

Adjust Retention Periods

Edit the scripts to modify retention:

Daily retention (default: 30 days):

vi /root/zfs_daily_snapshot.sh
# Change: RETENTION_DAYS=30

Weekly retention (default: 52 weeks):

vi /root/zfs_weekly_snapshot.sh  
# Change: RETENTION_WEEKS=52

Custom Naming

Modify the SNAPSHOT_PREFIX variables in the scripts:

SNAPSHOT_PREFIX="daily"    # Creates: daily-20240829
SNAPSHOT_PREFIX="weekly"   # Creates: weekly-2024W35

Troubleshooting

Common Issues

"Command not found" in Cron

• Ensure service configd restart was run after installation
• Check that actions file exists: ls -la /usr/local/opnsense/service/conf/actions.d/actions_zfs_snapshot.conf

Snapshots not visible in Web GUI

• Verify you're creating Boot Environments, not ZFS snapshots
• Check: bectl list should show your snapshots

Permission denied

• Ensure scripts are executable: chmod +x /root/zfs_*.sh

Out of space

• Clean up old snapshots manually: bectl list then bectl destroy old-name
• Check space usage: zpool list

Getting Help

1. Check the log files first
2. Open an issue with log output and system details
3. Include output of: bectl list, zpool status, uname -a

Contributing

Contributions welcome! Please:

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

Ideas for Contributions

• Pre-update snapshot triggers
• Slack/email notifications
• Web GUI configuration panel
• Snapshot size monitoring
• Multiple retention policies

License

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

Acknowledgments

• OPNsense team for the excellent firewall platform
• FreeBSD ZFS implementation
• Community feedback and testing

Star This Repository!

Found this useful? Give it a star! ⭐

It helps other OPNsense users discover this automation solution and motivates continued development.

---

Stats

Made with ❤️ for the OPNsense community