Configuration

Introduction

Wings reads /etc/pterodactyl/config.yml at startup. The Panel creates it, through the auto-deploy command or as a copy from the node's Configuration tab. See Configuring Wings.

The Panel's file only has the keys the Panel knows about. At startup, Wings fills in every other key with its default and writes the complete file back, so the file on a running node is much longer.

After you edit the file, restart Wings:

systemctl restart wings

Container settings, such as DNS servers and limits, apply the next time each server starts, because Wings creates a new container on every start.

How the Panel and Wings Share the File

When you save a node's settings, the Panel sends Wings an updated configuration with the tokens, ports, SSL settings, and upload limit, and Wings writes it to config.yml. Some parts behave differently:

• Wings listens on a new port only after it restarts.
• Wings keeps its certificate and key paths when you change the node's FQDN. Update api.ssl.cert and api.ssl.key yourself.
• wings configure and these updates do not copy system.data or allowed_mounts. If you changed the Daemon Base Path or use mounts, set these two keys by hand. Copying the whole file from the Configuration tab does include them.
• If the Panel cannot reach Wings, it saves your changes anyway and tells you to update config.yml yourself.
• With ignore_panel_config_updates: true, Wings ignores these updates, and the file only changes when you edit it.

Panel Connection

remote must match the address in your browser exactly, including https:// and with no trailing slash. Wings only accepts console connections from that origin or from one in allowed_origins. If you open the Panel from more than one address, list the others:

allowed_origins:
- https://panel.example.net

At startup, Wings fetches its servers from remote. If it cannot reach the Panel, it stops with failed to load server configurations.

Keeping the Token Out of the File

token_id and token are secrets that the auto-deploy command fills in. Never share them, and remove them before you post your configuration anywhere.

To keep them out of config.yml, set either value to file:// followed by a path to read it from a file, or to ${NAME} to read an environment variable:

token: file:///etc/pterodactyl/token

The environment variables WINGS_TOKEN_ID and WINGS_TOKEN override both values.

API and SSL

The Panel calls Wings' API to manage servers. Browsers also connect to it directly, for the console and for file uploads and downloads.

If the Panel uses HTTPS, Wings must too, because browsers block insecure connections from a secure page. Wings loads its certificate at startup: if the files are missing, it stops with failed to configure HTTPS server, and after a renewal it needs a restart. See Creating SSL Certificates.

Behind a Reverse Proxy

If a proxy handles HTTPS for Wings, turn on Behind Proxy in the node's settings. The Panel then writes api.ssl.enabled: false, and Wings serves plain HTTP. The Panel and browsers still connect to https://<FQDN>:<Daemon Port>, so your proxy must accept HTTPS there and forward requests to Wings.

Add your proxy's address to trusted_proxies so the activity log records your users' addresses, not the proxy's:

api:
  trusted_proxies:
  - 192.0.2.10

Entries may be IP addresses or ranges such as 192.0.2.0/24. Any other entry stops Wings at startup. SFTP does not use HTTP, so users connect to it directly, not through the proxy.

SFTP

Users sign in with their Panel account. The username is their Panel username, a period, and the server's 8-character ID, as shown under SFTP Details on the server's Settings page. Wings keeps its SFTP host key in the data directory, under .sftp/.

Directories

Move existing server directories before you change system.data, or servers whose files are still at the old path appear empty.

System

If servers with many files are slow to start at "Ensuring file permissions are set correctly", set check_permissions_on_boot to false. Wings then stops fixing files that other tools changed.

Low values for disk_check_interval make Wings measure every server's files often, which costs a lot of disk I/O and CPU.

Crash Detection

When a server stops without anyone pressing Stop, Wings prints its exit code and whether it ran out of memory, then starts it again.

Backups and Transfers

Docker

Network

On first start, Wings creates a Docker network named pterodactyl_nw, with the bridge pterodactyl0. If the network already exists, Wings uses it as is.

If servers cannot resolve domain names, your host may block the default DNS servers. Replace them with your host's, as described in Servers Have No Internet Access.

To change the subnet, stop every server on the node, then remove the network so Wings creates it again. Docker cannot remove a network that running containers still use.

systemctl stop wings
docker network rm pterodactyl_nw
systemctl start wings

To give containers the host's network directly, set both name and network_mode to host:

docker:
  network:
    name: host
    network_mode: host

Private Registries

To pull images from a registry that needs a login, add it under docker.registries, keyed by the registry's address:

docker:
  registries:
    registry.example.com:
      username: registryuser
      password: registrypassword

Wings uses the entry whose address matches the image's registry.

Container Limits

Programs like Java use more memory than their configured heap, so Docker allows each container some memory above the server's limit. By default, Wings adds 15% for servers with up to 2048 MB, 10% up to 4096 MB, and 5% above that. To use your own steps, set override: true:

docker:
  overhead:
    override: true
    default_multiplier: 1.05
    multipliers:
      2048: 1.15
      4096: 1.10

CPU

These settings only affect servers with a CPU limit.

Console Throttling

Wings limits how fast a server may print to its console, so a runaway process cannot flood Wings and the browser. When a server prints more than lines lines within line_reset_interval milliseconds, Wings drops the extra output and prints "Server is outputting console data too quickly -- throttling...".

Wings writes a throttles.enabled key, but does not read it. Throttling is always on; raise lines to loosen it.

Mounts

allowed_mounts lists the host directories that servers may mount. Wings skips a mount whose source is outside these, and logs skipping custom server mount, not in list of allowed mount points. See Using Mounts.