Manage your Minecraft allowlist and operators

An allowlist (called the whitelist in the game's files) lets only named players join, and an operator list grants administrator powers to chosen players. This article shows how to set up both, and how to make changes when the server runs as a service without an interactive console.

Before you begin

• The Minecraft Java server installed, with online-mode=true and a successful start (see the Minecraft Java Edition article).
• The server running as a systemd service (see the systemd article).
• The exact Minecraft usernames of the players you want to add. Usernames are case-sensitive in the game.
• A sudo user on the server (this guide uses alex).

Step 1: Turn on the allowlist in the settings

The allowlist works only when it is switched on. Two settings in server.properties control it: white-list turns the list on, and enforce-whitelist makes the server kick players who are not on it. Open the file and change the values:

sudo nano /opt/minecraft/server.properties

white-list=true
enforce-whitelist=true

Save and exit with Ctrl+O and Ctrl+X. Nothing changes until the server reads the file again, so restart the service at the end of this article.

Step 2: Add players with console commands

The server accepts commands, such as whitelist add, at its console. The service runs without an interactive console, so the simplest method is a short foreground session. Stop the service, run the server by hand, type the commands, and then stop the server and start the service again:

sudo systemctl stop minecraft
sudo -u minecraft sh -c 'cd /opt/minecraft && java -Xms1G -Xmx2G -jar server.jar nogui'

When the Done line appears, type these commands one per line, pressing Enter after each:

whitelist add alex
whitelist add sam
whitelist list

The whitelist list command prints the current players. Expected output:

There are 2 whitelisted players: alex, sam

The server writes these names to whitelist.json, with the account's ID, so the names are verified against the official account service.

Step 3: Grant operator rights

Operators can use administrative commands. The op command gives a player operator status, and deop removes it. Give operator rights only to people you trust. At the same console, type:

op alex
list

The list command shows who is online. Operator levels run from 1 to 4, and the op-permission-level setting in server.properties sets the default level for new operators. Level 4 has full control, including the stop command, and it is the default. Use a lower level for helpers who only need to manage players.

Type stop to shut the server down cleanly, then return to the service:

stop

sudo systemctl start minecraft
sudo systemctl status minecraft --no-pager

The status should be active (running). Joining players now pass the allowlist check, and anyone else sees a message that they are not whitelisted.

Step 4: Check the saved files

The lists are plain JSON files, so you can review them at any time. Check that the names are the ones you expect:

cat /opt/minecraft/whitelist.json
cat /opt/minecraft/ops.json

Each entry holds a name, an ID and, for operators, a permission level. If a name is wrong, fix it with the console commands rather than editing these files by hand, since IDs must match the official account.

Step 5: Remove a player

To remove someone, repeat the foreground session and type whitelist remove sam, then deop sam if they were an operator. Stop the server and start the service again. Removing a player from the allowlist does not delete their saved data in the world, so they keep their inventory if they return later.

Troubleshooting

• A player on the list still cannot join: check the spelling and capitalization with whitelist list. Run whitelist reload at the console after edits to the file.
• The changes disappear after a restart: commands typed in a session that ended without stop may not be saved. Always type stop at the console before leaving.
• Operator commands show "Unknown command": the player is not an operator. Check cat /opt/minecraft/ops.json, then run op name again.
• The foreground session will not start: the service is still running and holding the port. Run sudo systemctl stop minecraft first.

Next steps

Your server now admits only the players you choose. The backup article is the next step, so that a bad change, a crash or a deleted world can be undone. Revisit this article whenever your group changes.