Setting up a whitelist on your FiveM server restricts access to only players you approve, which is essential for private communities, roleplay servers, or testing environments. This guide walks you through the entire process, from creating the whitelist script to adding players and troubleshooting common issues. You’ll need basic file editing skills and access to your server’s resources folder.
What You’ll Need
- A FiveM server (either hosted locally or on a provider) with admin access to the server files.
- A code editor like Notepad++ or Visual Studio Code (plain Notepad works too).
- Access to your server’s
resourcesfolder and the ability to restart resources (via console or server.cfg). - Basic understanding of Lua or JavaScript (the script we provide is in Lua).
Step-by-Step
- Create the whitelist resource folder. Navigate to your server’s
resourcesdirectory. Create a new folder namedwhitelist(all lowercase). This will hold your whitelist script. - Create the main script file. Inside the
whitelistfolder, create a new file namedserver.lua. This is where the whitelist logic will live. - Write the whitelist check script. Open
server.luain your editor and paste the following code:-- Whitelist configuration local whitelist = { "steam:110000123456789", -- Example Steam ID "license:abc123def456" -- Example license ID } -- Event handler for player connecting AddEventHandler('playerConnecting', function(playerName, setKickReason, deferrals) local player = source local identifiers = GetPlayerIdentifiers(player) -- Defer the connection to allow async checks deferrals.defer() -- Check if any identifier is in the whitelist local allowed = false for _, id in ipairs(identifiers) do for _, whitelistedId in ipairs(whitelist) do if id == whitelistedId then allowed = true break end end if allowed then break end end -- Allow or deny the connection if allowed then deferrals.done() else deferrals.done("You are not whitelisted on this server.") end end)This script checks the player’s identifiers (Steam, license, etc.) against a hardcoded list. If a match is found, they are allowed in; otherwise, they are kicked with a message.
- Add player identifiers to the whitelist. To whitelist a player, you need their identifiers. The easiest way is to ask them to join once (they will be kicked), then check your server console or logs for their identifiers. Alternatively, you can use a command like
playerlistin the server console to see connected players and their identifiers. Copy thesteam:orlicense:identifier and add it to thewhitelisttable in the script. - Set up the resource manifest. In the
whitelistfolder, create a file namedfxmanifest.lua(or__resource.luafor older servers). Add the following content:fx_version 'cerulean' game 'gta5' server_script 'server.lua'For older servers, use
__resource.luawith:server_script 'server.lua'This tells FiveM to load your server script.
- Add the resource to your server.cfg. Open your
server.cfgfile and add the lineensure whitelist(orstart whitelistfor older versions). Place it after any other essential resources but before your game mode if possible. - Restart your server. Save all files and restart your FiveM server. The whitelist will now be active. Test by connecting with a non-whitelisted account to see the kick message, and with a whitelisted account to confirm access.
- Optional: Make whitelist management easier. Instead of editing the script every time, you can use a database or a separate file. For example, you could read from a
whitelist.jsonfile. However, the hardcoded method is simplest for small communities.
Common Mistakes
- Using the wrong identifier format. Ensure you copy the entire identifier string including the prefix (e.g.,
steam:110000...). Missing the prefix will cause the check to fail. - Forgetting to add
ensure whitelistto server.cfg. The resource won’t load, and the whitelist won’t be active. - Putting the script in the wrong folder. The
server.luamust be inside thewhitelistfolder, and the folder must be in theresourcesdirectory. - Not using deferrals correctly. The
deferrals.defer()call is mandatory to delay the connection until the check is complete. If you skip it, the player may connect before the kick is issued. - Hardcoding identifiers in multiple places. If you have multiple scripts, keep the whitelist in one place to avoid inconsistencies.
Tips
- Use a database for large communities. For more than a few dozen players, consider using a MySQL database to store whitelisted identifiers. This makes adding/removing players easier without editing files.
- Add a command to whitelist players in-game. You can extend the script to allow admins to add players via a command like
/whitelist add. This requires storing the list in a persistent file or database. - Log connection attempts. Add a
printstatement in the script to log who was denied. This helps you see who tried to join and their identifiers. - Test with a friend. Have a friend join to test the whitelist from a different machine to ensure it works correctly.
- Keep a backup of your whitelist. If you edit the file, keep a copy of the original in case you make a mistake.
Troubleshooting
- Players are not being kicked. Check that the resource is running by typing
ensure whitelistin the server console (it will show a message if already started). Also, verify that theserver.luahas no syntax errors. Look for red errors in the console when the resource starts. - Players are kicked even when whitelisted. Double-check the identifier string. It’s easy to copy an extra space or miss a character. Also, ensure the identifier type is correct (e.g.,
steam:vslicense:). Some players may have multiple identifiers; your script checks all of them, so any match should work. - Server crashes on start. This usually indicates a syntax error in
server.luaor the manifest file. Check the console for error messages. Common issues: missing commas in the whitelist table, or using the wrong manifest version. - The whitelist resource doesn’t appear in the resource list. Ensure the folder name matches the resource name (case-sensitive on Linux). Also, check that
fxmanifest.luais spelled correctly and is in the root of the folder. - Deferrals not working. If you see players connecting briefly before being kicked, the deferral is not working. Make sure you call
deferrals.defer()before any long operations, and usedeferrals.done()to finish.
Frequently Asked Questions
Can I whitelist by IP address?
Yes, you can add IP identifiers, but they are less reliable because players can change IPs. It’s better to use Steam or license identifiers.
How do I find my own identifiers?
Join your server (even if kicked), then check the server console. It will print the identifiers of the connecting player. You can also use server commands like playerlist or check logs.
Can I whitelist a whole group (like a Steam group)?
Yes, but it requires more complex scripting. You can use the Steam API to check group membership, but this is advanced and not covered in this basic guide.
Does this work on all FiveM servers?
Yes, the script is standard and works on both standalone and FXServer-based servers, as long as you place the files correctly.
How do I remove a player from the whitelist?
Simply delete their identifier from the whitelist table in server.lua and restart the resource or server.
Can I use a GUI to manage the whitelist?
There are third-party admin tools that offer GUI whitelist management, but they require additional setup. The basic script is file-based, which is fine for small communities.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Samsung Smart Speaker Rollable Display: Facts
- HP 9730e: Wide Prints, Not A3 Scans
- What 8888 Does When You Use It as DNS Server
- Credential Manager: Seamless Sign-In Explained
- API Governance for Public Data: What Growing Portfolios Need
- Enterprise AI Hidden Cost: Data Architecture ROI