Panel Configuration

Configure Wings in the Pterodactyl Panel and set up node connectivity

After installing and configuring Wings, you need to create and configure the node in your Pterodactyl Panel. This guide covers the complete process of setting up Wings in the Panel.

Prerequisites

Before configuring Wings in the Panel:

1. Panel Installed

   Ensure Pterodactyl Panel is installed and running

2. Wings Installed

   Wings must be installed on the target server

3. Admin Access

   You need administrator access to the Panel

4. Network Connectivity

   Panel must be able to reach Wings on port 8080 (or configured port)

Creating a Node

A node represents a Wings instance in the Panel.

Step 1: Access Admin Panel

1. Log in to your Pterodactyl Panel
2. Navigate to the Admin Control Panel
3. Go to Nodes in the sidebar
4. Click Create New

Step 2: Basic Configuration

Fill in the basic node information:

Name · string · required

Descriptive name for the node (e.g., “US-East-1”, “EU-Node-01”)

Description · string

Optional description for internal use

Location · select · required

Select or create a location for this node

FQDN · string · required

Fully qualified domain name or IP address of the Wings server

Examples:

• node1.example.com
• 192.168.1.100
• wings.pterodactyl.example.com

The FQDN must be accessible from both the Panel and end users. Use a domain name for production deployments.

Communicate Over SSL · boolean

Enable if Wings is configured with SSL/TLS

Behind Proxy · boolean

Enable if Wings is behind a reverse proxy

Step 3: Configuration Settings

Configure resource limits and paths:

System Settings

Total Memory · integer · required

Total RAM allocated to this node in MB

This should be less than total system memory to account for OS overhead

Memory Over-Allocation · integer · default: "0"

Percentage of additional memory to allow allocation

Example: 20% allows allocating 120% of total memory

Total Disk Space · integer · required

Total disk space allocated in MB

Disk Over-Allocation · integer · default: "0"

Percentage of additional disk to allow allocation

Daemon Configuration

Daemon Port · integer · default: "8080"

Wings API port (must match api.port in Wings config)

Daemon SFTP Port · integer · default: "2022"

Wings SFTP port (must match system.sftp.bind_port in Wings config)

Step 4: Save Node

Click Create Node to save the configuration.

Obtaining Configuration

After creating the node, you need to configure Wings with the Panel.

Method 1: Auto-Configuration (Recommended)

Use the Wings auto-configure command:

1. Generate API Token

   1. In the Panel, go to Account Settings → API Credentials
   2. Click Create New
   3. Description: “Wings Configuration”
   4. Select permissions:
      • ✓ Nodes → Read
      • ✓ Nodes → Create
   5. Copy the generated API token
2. Run Configure Command

   On the Wings server, run:

   sudo wings configure --panel-url https://panel.example.com \
     --token YOUR_API_TOKEN \
     --node NODE_ID
   

   The Node ID is shown in the Panel’s node list

3. Verify Configuration

   Check that the config was created:

   sudo cat /etc/pterodactyl/config.yml
   

Method 2: Manual Configuration

Alternatively, copy configuration from the Panel:

1. View Configuration

   1. In the Panel, open your node
   2. Go to the Configuration tab
   3. Copy the YAML configuration shown
2. Create Config File

   On the Wings server:

   sudo nano /etc/pterodactyl/config.yml
   

   Paste the configuration from the Panel

3. Set Permissions

   sudo chmod 600 /etc/pterodactyl/config.yml
   sudo chown root:root /etc/pterodactyl/config.yml
   

Setting Up Allocations

Allocations are IP:Port combinations assigned to servers.

Creating Allocations

1. Navigate to Node

   In the Panel, open your node and go to the Allocation tab

2. Add Allocation

   Click Create Allocation

3. Configure Allocation

   IP Address · string · required

   Server’s IP address (e.g., 192.168.1.100 or 0.0.0.0 for all interfaces)

   IP Alias · string

   Friendly name for the IP (optional)

   Ports · string · required

   Port or port range to create

   Examples:

   • Single port: 25565
   • Port range: 25565-25665
   • Multiple ports: 25565,25566,25567
4. Save Allocation

   Click Submit to create the allocation(s)

Bulk Allocation Creation

For large deployments, create multiple allocations at once:

IP Address: 192.168.1.100
Ports: 25565-26565

This creates 1,001 allocations (25565 through 26565).

Ensure your firewall allows these ports! See Network Requirements.

Starting Wings

With configuration complete, start Wings:

First-Time Start

# Start Wings manually to check for errors
sudo wings --debug

Watch the output for any errors. You should see:

[INFO] configured wings with system timezone: UTC
[INFO] configured system user successfully
[INFO] configuring internal webserver
[INFO] webserver is now listening

Enable Systemd Service

Once verified, enable the systemd service:

# Stop the manual instance (Ctrl+C)

# Enable and start the service
sudo systemctl enable --now wings

# Check status
sudo systemctl status wings

Verifying Connectivity

Ensure the Panel can communicate with Wings:

Check Node Status

In the Panel:

1. Go to Admin → Nodes
2. Your node should show a green heart icon indicating it’s online
3. Click the node to view details

Test API Connection

From the Panel server, test the Wings API:

curl -k https://node.example.com:8080/api/system

You should receive a JSON response with system information.

Check Wings Logs

Monitor Wings logs for connection attempts:

# View real-time logs
sudo journalctl -u wings -f

# View recent logs
sudo journalctl -u wings -n 100

# View Wings log file
sudo tail -f /var/log/pterodactyl/wings.log

Authentication Tokens

Wings uses token-based authentication with the Panel.

Token Configuration

Tokens are configured in two places:

1. Panel: Node configuration stores the token ID and token
2. Wings: Configuration file references these tokens (see config/config.go:324)

/etc/pterodactyl/config.yml

token_id: 'abc123def456'
token: 'very-long-secure-token-string'

Rotating Tokens

To change authentication tokens:

1. Regenerate in Panel

   1. In the Panel, go to your node’s Configuration tab
   2. Click Generate Token
   3. Copy the new configuration
2. Update Wings Config

   Update /etc/pterodactyl/config.yml with new tokens

3. Restart Wings

   sudo systemctl restart wings
   

Secure Token Storage

For production environments, use systemd credentials:

/etc/systemd/system/wings.service

[Service]
LoadCredential=token_id:/etc/pterodactyl/credentials/token_id
LoadCredential=token:/etc/pterodactyl/credentials/token

/etc/pterodactyl/config.yml

token_id: 'file://${CREDENTIALS_DIRECTORY}/token_id'
token: 'file://${CREDENTIALS_DIRECTORY}/token'

See config/config.go:844 for credential expansion implementation.

SSL/TLS Configuration

Secure communication between Panel and Wings:

Using Let’s Encrypt (Auto-TLS)

Wings includes built-in Let’s Encrypt support:

sudo wings --auto-tls --tls-hostname node.example.com

Update systemd service:

/etc/systemd/system/wings.service

[Service]
ExecStart=/usr/local/bin/wings --auto-tls --tls-hostname node.example.com

Auto-TLS requires port 80 to be accessible for ACME challenges (see cmd/root.go:353).

Using Custom Certificates

Configure SSL in Wings config:

/etc/pterodactyl/config.yml

api:
  ssl:
    enabled: true
    cert: /etc/letsencrypt/live/node.example.com/fullchain.pem
    key: /etc/letsencrypt/live/node.example.com/privkey.pem

Enable SSL in Panel node settings:

1. Edit node in Panel
2. Enable Communicate Over SSL
3. Update FQDN to use https:// if needed

Advanced Configuration

Reverse Proxy Setup

If Wings is behind a reverse proxy (Nginx, Apache, Cloudflare):

1. Panel: Enable Behind Proxy in node settings
2. Wings: Configure trusted proxies

/etc/pterodactyl/config.yml

api:
  trusted_proxies:
    - 127.0.0.1
    - 10.0.0.0/8
allow_cors_private_network: false

Multiple Nodes

For multi-node setups:

1. Create Each Node

   Repeat the node creation process for each Wings server

2. Configure Unique Allocations

   Each node should have its own IP allocations

3. Load Balancing

   The Panel automatically distributes servers across nodes based on available resources

Troubleshooting

Node Shows Offline

Check Wings status:

sudo systemctl status wings
sudo journalctl -u wings -n 50

Verify Panel can reach Wings:

# From Panel server
curl https://node.example.com:8080/api/system

Authentication Failures

Verify tokens match:

# Check Wings config
sudo grep -E "token" /etc/pterodactyl/config.yml

Regenerate tokens in Panel and update Wings config.

SSL/TLS Errors

Check certificate validity:

# Test SSL connection
openssl s_client -connect node.example.com:8080

Ensure Panel has “Communicate Over SSL” enabled if Wings uses SSL.

Port Already in Use

Check for port conflicts:

sudo ss -tulpn | grep -E ':(8080|2022)'

Change ports in both Wings config and Panel node settings.

Allocation Issues

Verify allocations exist:

# Check Wings network
sudo docker network inspect pterodactyl_nw

Ensure firewall allows allocation ports.

Testing Server Creation

Verify everything works by creating a test server:

1. Create Server

   1. In the Panel, go to Servers → Create New
   2. Select your node
   3. Choose an allocation
   4. Configure and create the server
2. Monitor Wings Logs

   sudo journalctl -u wings -f
   

   Watch for:

   • Container creation
   • Image pulling
   • Server startup
3. Verify Server Starts

   The server should start successfully in the Panel console

Next Steps

Managing Servers

Learn how to manage servers through Wings

Backups & Transfers

Configure backup and transfer systems

Monitoring

Set up monitoring and alerting

Upgrading Wings

Keep Wings up to date

Configuration Summary

Key configuration points:

• Panel node FQDN must match Wings server address
• Ports in Panel must match Wings configuration
• Tokens must be identical in Panel and Wings config
• Allocations must be created before assigning servers
• SSL settings must match between Panel and Wings
• Firewall must allow all configured ports