Automatically synchronize port forwarding between Pterodactyl Panel and OPNsense Firewall. No manual NAT rule management needed!
- β Automatic sync every 60 seconds
- β Bulk updates (no port loss)
- β Protected ports (SSH, HTTP, etc.)
- β Auto cleanup of orphaned ports
- β Docker ready with pre-built images
# 1. Create .env file
cat > .env << 'EOF'
PTERODACTYL_PANEL_URL=https://your-panel.com
PTERODACTYL_API_KEY=ptla_your_api_key
OPNSENSE_URL=https://192.168.1.1
OPNSENSE_API_KEY=your_opnsense_key
OPNSENSE_API_SECRET=your_opnsense_secret
ALIAS_NAME=pterodactyl_ports
EXCLUDED_PORTS=22,80,443,3306,5432,6379,8006,9090
EOF
# 2. Download and start
curl -O https://raw.githubusercontent.com/Smallinger/pterodactyl-portmapper/main/docker-compose.ghcr.yml
docker-compose -f docker-compose.ghcr.yml up -d
# 3. View logs
docker-compose -f docker-compose.ghcr.yml logs -f# 1. Clone and configure
git clone https://github.com/Smallinger/pterodactyl-portmapper.git
cd pterodactyl-portmapper
cp .env.example .env
nano .env # Edit with your credentials
# 2. Start
docker-compose up -d
# 3. View logs
docker-compose logs -fEdit your .env file:
# Pterodactyl
PTERODACTYL_PANEL_URL=https://panel.example.com
PTERODACTYL_API_KEY=ptla_your_key_here
# OPNsense
OPNSENSE_URL=https://192.168.1.1
OPNSENSE_API_KEY=your_key
OPNSENSE_API_SECRET=your_secret
OPNSENSE_VERIFY_SSL=false
# Settings
ALIAS_NAME=pterodactyl_ports
SYNC_INTERVAL=60
EXCLUDED_PORTS=22,80,443,3306,5432,6379,8006,9090- System β Access β Users β Your user β API keys β Click "+"
- Copy API Key and API Secret to
.env
- Firewall β Aliases β Click "+"
- Name:
pterodactyl_ports - Type:
Port(s) - Content: (leave empty)
- Click Save β Apply
- Firewall β NAT β Port Forward β Click "+"
| Field | Value |
|---|---|
| Interface | WAN |
| Protocol | TCP |
| Destination | WAN address |
| Destination Port | pterodactyl_ports (alias) |
| Redirect Target IP | Your Pterodactyl host IP |
| Redirect Target Port | pterodactyl_ports (alias) |
- Click Save β Apply changes
β Done! The script will now auto-manage ports.
| Problem | Solution |
|---|---|
| "Alias not found" | Check alias name matches ALIAS_NAME in .env |
| "401 Unauthorized" | Verify API credentials |
| "SSL Error" | Set OPNSENSE_VERIFY_SSL=false |
| Ports not forwarding | Verify NAT rule uses alias for both destination and target |
View logs:
docker-compose -f docker-compose.ghcr.yml logs -fProtected ports (never forwarded):
22 (SSH), 80 (HTTP), 443 (HTTPS), 3306 (MySQL), 5432 (PostgreSQL), 6379 (Redis), 8006 (Proxmox), 9090 (Management)
Customize: Edit EXCLUDED_PORTS in .env
MIT License - See LICENSE file
- β Star this repo if you find it useful!
- οΏ½ Issues: GitHub Issues
- π¬ Discussions: GitHub Discussions
If you like what I do, consider supporting me:
Made with β€οΈ for the Pterodactyl and OPNsense community
- Check the logs
- Review OPNsense API documentation
- Create an issue in the repository
- Web UI for monitoring
- Prometheus metrics export
- Multi-firewall support
- Port range support
- UDP protocol support