keepcalculator

06 Numbers and Powers

FiveM Whitelist Setup: Step-by-Step Guide

Card No. 06·72911 · Updated · Standard formula, shown below

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 resources folder 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

  1. Create the whitelist resource folder. Navigate to your server’s resources directory. Create a new folder named whitelist (all lowercase). This will hold your whitelist script.
  2. Create the main script file. Inside the whitelist folder, create a new file named server.lua. This is where the whitelist logic will live.
  3. Write the whitelist check script. Open server.lua in 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.

  4. 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 playerlist in the server console to see connected players and their identifiers. Copy the steam: or license: identifier and add it to the whitelist table in the script.
  5. Set up the resource manifest. In the whitelist folder, create a file named fxmanifest.lua (or __resource.lua for older servers). Add the following content:
    fx_version 'cerulean'
    game 'gta5'
    
    server_script 'server.lua'

    For older servers, use __resource.lua with:

    server_script 'server.lua'

    This tells FiveM to load your server script.

  6. Add the resource to your server.cfg. Open your server.cfg file and add the line ensure whitelist (or start whitelist for older versions). Place it after any other essential resources but before your game mode if possible.
  7. 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.
  8. 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.json file. 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 whitelist to server.cfg. The resource won’t load, and the whitelist won’t be active.
  • Putting the script in the wrong folder. The server.lua must be inside the whitelist folder, and the folder must be in the resources directory.
  • 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 print statement 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 whitelist in the server console (it will show a message if already started). Also, verify that the server.lua has 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: vs license:). 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.lua or 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.lua is 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 use deferrals.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

The whole Numbers and Powers drawer →