How to Set Up a Whitelist on a Project Zomboid Server

How to Set Up a Whitelist on a Project Zomboid Server

A whitelist locks your server to a pre-approved list of players. Anyone not on the list gets rejected at connect. This is the simplest way to stop random griefers and keep your server private. Setup takes 5 minutes.

Step 1 — Enable whitelist mode in servertest.ini

Stop the server first. Then open:

/home/container/Zomboid/Server/servertest.ini

Find these two lines and change them to:

Open=false
Public=false

Save and start the server.

Step 2 — Add players one at a time (console method)

In the server console (panel → Console tab), type:

adduser "PlayerName" "password"

The password becomes that player's login password for your server. Tell them what you set, or pick something they can change later.

For multiple players, run adduser for each:

adduser "Alice" "alicepw123"
adduser "Bob" "bobpw456"
adduser "Carol" "carolpw789"

Step 3 — Add players already on the server (bulk method)

If players are connected when you flip whitelist on, add all of them at once:

addalltowhitelist

This whitelist-promotes every currently connected player. Run it once after enabling Open=false and connecting your trusted players.

Step 4 — Test the whitelist

Have a friend (not on the list) try to connect. They should see:

Server is closed. Contact server administrator.

If they get in anyway, Open=false didn't apply — make sure you stopped the server before editing and the file actually saved.

Removing players from the whitelist

removeuserfromwhitelist "PlayerName"

Or via setaccesslevel (sets them to "none"):

setaccesslevel "PlayerName" "none"

Both kick them at next connect attempt.

Where the whitelist is stored

The whitelist lives in the SQLite database:

/home/container/Zomboid/db/servertest.db

Inside, the whitelist table has columns: username, password (bcrypt-hashed), accesslevel, banned, steamid. You can edit it directly with DB Browser for SQLite if you need bulk operations.

Security note: Passwords are stored as bcrypt hashes, not plaintext. You can't recover lost passwords — only reset them via changepwd from the console.

Whitelist + Steam authentication (recommended for public-facing servers)

If your server faces the open internet, also enable Steam authentication. In servertest.ini:

SteamScoreboard=true
SteamPort1=8766
SteamPort2=8767

This ties whitelist entries to Steam IDs once players join, so banned players can't reconnect with a renamed Steam account.

Friends-only quick setup

For a small server (5-10 friends), the fastest path:

1. Open=true initially so friends can join
2. Once everyone is on, run addalltowhitelist from console
3. Set Open=false in the .ini file
4. Restart the server

Now your friends are whitelisted permanently and no one new can join.

Discord-bot integration (advanced)

For larger communities, a Discord bot that handles /whitelist <PlayerName> requests is common. The bot writes directly to servertest.db (whitelist table). Open-source examples exist for several PZ-focused bots.

Common problems

"Server is closed" even for me as admin. You're not in the whitelist. Add yourself: adduser "YourName" "yourpw", then grantadmin "YourName".

adduser says "user already exists". The player is already in the database, just not whitelisted. Use addusertowhitelist "PlayerName" instead.

Whitelist doesn't seem to work. Three possible causes: 1) you forgot to set Open=false, 2) you edited while the server was running and the change got overwritten on shutdown, 3) you set Open=false but didn't restart.

Players need a password but I want them to set their own. There's no in-game self-registration. Either send them their initial password, or have them register via your community Discord/website and then adduser them manually.

FAQ

Can I use a whitelist with Steam-only servers? Yes — whitelist enforcement happens at the username level, which is your Steam display name (or in-game name). Steam authentication runs in parallel.

Does whitelist prevent IP bans from being needed? No — they're complementary. Whitelist controls who can join, IP/Steam bans permanently exclude specific identities even if they get whitelisted later.

What's the difference between Open=false and PauseEmpty=true? Open=false = whitelist required. PauseEmpty=true = world doesn't tick when no one's online. Different features entirely.

Can I whitelist a Steam group? Not via vanilla — there's no Steam group integration. You can write a Discord/web bot that bulk-adduses members though.