Cloudflare Subdomains

What You Need

• A Cloudflare-managed zone such as example.com
• A Hydrodactyl panel admin account
• A node and allocation setup that can publish a public address
• A supported egg feature such as subdomain_minecraft

Create A Cloudflare Token

1. Open Cloudflare Dashboard -> My Profile -> API Tokens.

2. Select Create Token.

3. Start from Edit zone DNS, or create a custom token with the same scope.

4. Set the permission to:

   • Zone -> DNS -> Edit

5. Scope the token to the exact zone you want Hydrodactyl to manage:

   • Include -> Specific zone -> example.com

6. Create the token and copy it immediately.

Get The Zone ID

1. Open the zone in Cloudflare.
2. On the overview page, copy the Zone ID from the right sidebar.

Verify The Token

Before adding the domain to Hydrodactyl, verify the token from any machine that can reach the Cloudflare API:

curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  --header "Authorization: Bearer YOUR_TOKEN"

The response should include "success": true.

If you receive an authentication error here, Hydrodactyl will fail too.

Create The Domain In Hydrodactyl

1. Open Admin -> Settings -> Domains.

2. Select Create Domain.

3. Fill in:

   • Domain Name: your zone name, for example example.com
   • DNS Provider: Cloudflare
   • API Token: the token created above
   • Zone ID: the Cloudflare zone ID for this domain

4. Click Test Connection.

5. If the connection succeeds, save the domain.

6. Mark the domain as Active.

7. Mark it as Default if you want Hydrodactyl to generate subdomains for new supported servers automatically.

Configure The Node And Allocations

Hydrodactyl builds subdomain DNS records from the server's primary allocation. That means the address behind the allocation must be valid for public DNS.

Option 1: Publish The Allocation IP Directly

Use this if the allocation IP is already public.

• Leave Domain by Allocation Alias disabled on the node, or
• Keep it enabled only if each allocation has a correct public alias

Option 2: Publish The Allocation Alias

Use this if the node uses private addresses internally.

1. Open Admin -> Nodes -> Your Node -> Settings.
2. Enable Domain by Allocation Alias.
3. Open Admin -> Nodes -> Your Node -> Allocation.
4. Set the allocation alias for the server's primary allocation to the public IP you want DNS to publish.

Record Behavior

Hydrodactyl creates different records depending on the egg feature and port:

• Minecraft on port 25565: A record only
• Minecraft on a non-default port: A record plus an SRV record
• Other supported services: record sets vary by feature

See Egg Features for the supported subdomain feature flags.

Troubleshooting

Authentication error

This usually means one of the following:

• You used a Global API Key instead of an API Token
• The token is scoped to the wrong zone
• The token does not include Zone -> DNS -> Edit
• The token was copied incorrectly

Recreate the token and test it again with Cloudflare's token verify endpoint.

Subdomain Points To A Private IP

Check the node and allocation configuration:

• If Domain by Allocation Alias is enabled, make sure the allocation has a public ip_alias
• If the alias is blank, Hydrodactyl may publish the allocation's internal IP

No Domain Appears In The Server UI

Check all of the following:

• The domain is marked Active
• The server uses an egg with a supported subdomain_* feature
• At least one domain exists in Admin -> Settings -> Domains

Automatic Subdomain Creation Does Not Happen

Automatic generation only applies when:

• The server supports subdomains
• A default domain exists
• That default domain is active