README

A Pterodactyl addon for automated port forwarding through OPNsense.

Description

FeatherForward is a Pterodactyl addon that automatically configures port forwards in OPNsense when new allocations are created. This makes server management much easier as you don't need to manually configure port forwards anymore.

Features

• Automatic port forward configuration for new allocations
• Support for TCP and UDP protocols
• Configuration through OPNsense API
• Comprehensive logging of all operations
• Easy installation via Composer
• Fully tested with PHPUnit

Requirements

• PHP 8.0 or higher
• Pterodactyl Panel 1.0 or higher
• OPNsense with API access
• Composer

Installation

1. Install the package via Composer:

   composer require dagelijksdutchgaming/featherforward
   

2. Publish the configuration:

   php artisan vendor:publish --provider="FeatherForward\FeatherForwardServiceProvider" --tag="config"
   

3. Add the following to your .env file:

   OPNSENSE_URL=https://your-opnsense-url
   OPNSENSE_API_KEY=your-api-key
   OPNSENSE_API_SECRET=your-api-secret
   FEATHERFORWARD_ENABLED=true
   FEATHERFORWARD_AUTO_CONFIGURE=true
   

Configuration

The configuration can be adjusted in config/featherforward.php:

return [
    'port_forwarding' => [
        'enabled' => env('FEATHERFORWARD_ENABLED', false),
        'auto_configure' => env('FEATHERFORWARD_AUTO_CONFIGURE', false),
        'protocol' => 'tcp', // or 'udp'
        'description_prefix' => 'Pterodactyl - ',
    ],
    'opnsense' => [
        'url' => env('OPNSENSE_URL'),
        'api_key' => env('OPNSENSE_API_KEY'),
        'api_secret' => env('OPNSENSE_API_SECRET'),
    ],
];

Usage

FeatherForward works automatically once installed and configured. When a new allocation is created in Pterodactyl:

1. The addon detects the new allocation
2. A port forward is created in the database
3. The port forward is configured in OPNsense via the API
4. The status is updated in the database

Testing

The package is fully tested with PHPUnit. You can run the tests with:

./vendor/bin/phpunit

The tests cover:

• Automatic port forward creation
• Error handling
• API communication
• Database operations

Contributing

Contributions are welcome! Feel free to submit a pull request.

License

This package is open-sourced software licensed under the MIT license.