Set Up a Server Whitelist

What is a Whitelist?

A whitelist is a list of approved player usernames that are allowed to join your server. When enabled, any player not on the whitelist will be automatically kicked with a message indicating they're not whitelisted.

Benefits of Using a Whitelist

• Security: Prevents unauthorized players from joining
• Control: Manage exactly who has access to your server
• Privacy: Keep your server private for friends or specific communities
• Performance: Reduce server load by limiting player count
• Works with Offline Mode: Provides authentication when using offline mode

How to Enable and Configure a Whitelist

Step 1: Enable Whitelist in server.properties

1. Access your server's server.properties file
2. Find the line white-list=false
3. Change it to white-list=true
4. Save the file

# Enables the whitelist
white-list=true

Step 2: Enforce Whitelist (Optional but Recommended)

To ensure the whitelist is always enforced, even for operators:

1. Find the line enforce-whitelist=false in server.properties
2. Change it to enforce-whitelist=true
3. Save the file

# Enforces the whitelist even for operators
enforce-whitelist=true

Step 3: Restart Your Server

1. Save all changes to server.properties
2. Restart your Minecraft server from the Pterodactyl panel
3. Wait for the server to fully start

Step 4: Add Players to the Whitelist

You can add players using either method:

Method 1: Using the Server Console

1. Open your server console in the panel
2. Use the whitelist command:

whitelist add <username>

For example:

whitelist add Notch
whitelist add jeb_

Method 2: Using the whitelist.json File

1. Access your server's file manager
2. Open the whitelist.json file (it will be created automatically after enabling the whitelist)
3. Add player entries in JSON format:

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  },
  {
    "uuid": "853c80ef-3c37-49fd-aa49-938b0ada1c0b",
    "name": "jeb_"
  }
]

Step 5: Reload the Whitelist

After adding players via the JSON file, reload the whitelist:

1. Open the server console
2. Type: whitelist reload
3. The server will reload the whitelist without requiring a restart

Managing Your Whitelist

View Current Whitelist

To see all whitelisted players:

whitelist list

Remove a Player from Whitelist

whitelist remove <username>

Remove All Players

whitelist remove *

Disable Whitelist Temporarily

You can disable the whitelist without removing players:

1. Open server.properties
2. Set white-list=false
3. Restart the server

Players will remain in whitelist.json and can be re-enabled later.

Whitelist Commands Reference

Troubleshooting

Player Can't Join Despite Being Whitelisted

1. Verify the username is spelled correctly (case-sensitive)
2. Check that white-list=true in server.properties
3. Ensure the server has been restarted after enabling the whitelist
4. Try using whitelist reload command
5. Verify the player's UUID matches if using whitelist.json

Whitelist Not Working

1. Confirm white-list=true is set correctly
2. Check for typos in server.properties
3. Ensure the server was restarted after changes
4. Verify enforce-whitelist=true if you want strict enforcement

Finding Player UUIDs

For online mode servers, the UUID is automatically generated. For offline mode or manual entry:

1. Use online UUID lookup tools
2. Or use the command: /whitelist add <username> which will automatically fetch the UUID

Best Practices

• Regular Updates: Keep your whitelist updated and remove inactive players
• Backup: Regularly backup your whitelist.json file
• Documentation: Keep a list of whitelisted players and their roles
• Combine with OPs: Use whitelist for access control and operator permissions for admin rights
• Use with Offline Mode: Whitelist is especially important when using offline mode for security