Pure Servers

From Valve Developer Community
Jump to: navigation, search
Español Français Nederlands Polski Русский

A pure server is one that forces all clients on the server to use content that matches what is on the server. This, along with sv_consistency, prevents cheating by modifying game content, e.g. increasing the size of models or volume of footsteps, or making wall materials transparent.

Basic Usage

To use pure server mode on a server, set the sv_pure console variable to 1 or 2. Then, on the next map change, the server will ensure that the content (materials, models, and sounds) on client machines matches what is specified.

By default, the server will kick clients whose custom content varies from that the server is using. By setting sv_pure_kick_clients to 0, the server will only display a warning about clients using this kind of "impure" custom content. The server can force the client to use content provided by the game, and will never kick players who have only modded default content, like custom skins or models.

In Source MP games (HL2:DM, DoD:S, CS:S, and TF2), sv_pure must be enabled on the server's command-line, before the game loads its VPK files.

Mode 1 Details

In this mode, the list of content that the server enforces is specified in the file pure_server_whitelist.txt, which is contained in the server's hl2 directory. Server administrators can edit this file to change which content clients are allowed to modify. For example, the server could specify in this file that clients are allowed to modify sounds, but not materials or models.

Mode 2 Details

In this mode, all game content is forced to be default. This is identical to running in mode 1 and with everything in the whitelist file set to from_steam.

sv_consistency and Mode -1

Source MP games no longer support sv_consistency. It has been merged with sv_pure. sv_pure 0 is the equivalent of sv_pure 0 and sv_consistency 1 in older games. sv_pure -1 is the equivalent of sv_pure 0 and sv_consistency 0.

Whitelist File Format

The whitelist file is the pure_server_whitelist.txt file found in /hl2/. This whitelist is used in CS:GO, Source 2009 and before Source engine games.

The whitelist file has moved to the game's /cfg/ directory in Source MP games.

The pure_server_whitelist.txt file specifies attributes for groups of files. Each line specifies one file or a group of files and the attributes for those files. Here is an example line:

materials\...    from_steam

The first part ('materials\...') specifies the files. In this case, it is specifying all files under the materials directory, recursively. The second part ('from_steam') specifies the attributes to apply to those files. In this case, it is saying that all of those files must come from Steam. So if clients have custom content in their materials directories, that content will not be used, and the content from their Steam caches will be used instead.

There are three ways to specify a file group:

By filename
All files in a directory
To do: Would *.vtf work too?
All files in a directory and its subdirectories

And there are three ways to specify an attribute:

Forces clients to load this set of files from the Steam cache even if they have custom content on disk. Replaced by trusted_source in Source MP games.
Clients can load the specified files from disk. They also don't have to match the content on the server. So these files are totally unprotected. Replaced by any in Source MP games.
Clients can load the specified files from disk, but their on-disk files must match the files on the server. Replaced by VPK signing keys in trusted_keys.txt in Source MP games.


   materials\models\player\...                      allow_from_disk
   sounds\...                                       from_steam
   models\MyMod\...                                 allow_from_disk+check_crc
   materials\MyMod\Customizable\*.*                 allow_from_disk
   materials\models\props\cs_assault\wirepipe.vtf   from_steam

Default Attributes

If sv_pure is set to 1, the default attribute for all files is allow_from_disk. So if you had an empty pure_server_whitelist.txt file and you set sv_pure to 1, there would be no difference from sv_pure 0.

Note:The default pure_server_whitelist.txt file that ships with the Source Engine does in fact have settings, so even if you don't modify the default pure_server_whitelist.txt, sv_pure 1 will still enforce most content.

Default pure_server_whitelist.txt File

The default pure_server_whitelist.txt file that ships with the game looks like this. If you want to begin making changes to the whitelist file, you can start with this.

	// 3 modifiers are allowed on file specifications:
	//	from_steam		- only check the Steam cache for the file (ignore anything on disk)
	//	allow_from_disk		- allow the file to come from disk
	//	check_crc		- used with allow_from_disk - server does CRC checks on the client's file to make sure it matches
	//	The default modifier on all files is allow_from_disk. Thus, all files can come from disk and don't need CRC checks unless 
	//	allow_from_disk can be set at the same time as check_crc. Use the + character in between them to signify this: allow_from_disk+check_crc.
	// Three types of file specifications:
	//	1. directory\*.*	- refers to all files under the directory
	//	2. directory\...	- refers to all files under the directory and all directories under that (recursively)
	//	3. directory\filename	- refers to a single file
	// By default, when in pure server mode, most content file types are only allowed to come from Steam.
	materials\...			from_steam
	models\...			from_steam
	sound\...			from_steam
	// Allow custom player models. Don't do CRC checks on them because the clients may all
	// have different custom models and the server won't have them all.
	models\player\...		allow_from_disk
	materials\models\player\...	allow_from_disk
	// Allow custom spray decals.
	materials\temp\...		allow_from_disk
	materials\vgui\logos\...	allow_from_disk
	materials\vgui\logos\ui\...	allow_from_disk
        // Allow replay browser thumbnails.
        materials\vgui\replay\thumbnails\...   allow_from_disk
	// (Uncomment and edit these for mods).
	// Allow mod resources to come from disk.
	// materials\mymod\...		allow_from_disk+check_crc
	// models\mymod\...		allow_from_disk+check_crc
	// sound\mymod\...		allow_from_disk+check_crc

For SteamPipe Source MP games, from_steam; allow_from_disk; and check_crc were deprecated. They were replaced with trusted_source; any; and the ability to validate signed VPKs based on their public keys.

The new default is:

        // Example custom server whitelist.
        // Do not modify this file.  Instead, rename this file to "pure_server_whitelist.txt" and then modify it as appropriate.
        // sv_pure values are in order of "increasing pureness":
        //   -1: No restrictions.  Allow clients to load any files.
        //    0: Only load pure_server_minimal.txt.
        //    1: Load pure_server_full.txt, followed by pure_server_whitelist.txt (the custom file).
        //       Also, in this mode, the server may specify additional public keys that it considers to be trusted.
        //    2: Load pure_server_full.txt only.
        //       In this mode, user only the public keys listed in trusted_keys_base are used.
        // If multiple rules apply to the same file, then the rule listed later (or from the file loaded later) takes priority.
        // Therefore, because the custom whitelist file is loaded last, after a fully pure whitelist has been loaded, typically
        // the custom whitelist file is used to carve out exceptions (where the server wants to be more permissive), rather than
        // listing the files that are requested to be.
        // 2 different rule types may be used:
        //      trusted_source - require file to be loaded from a "trusted source".
        //                   A trusted source is a VPK that is signed with one of the public keys listed
        //                   in trusted_keys_base.txt or trusted_keys.txt.
        //      any - Client can use file from any source.
        // For historical purposes, the following strings are also allowed:
        //      allow_from_disk           - same as "any"
        //      from_steam                - same as "trusted_source"
        //  check_crc                 - same as "trusted_source"
        //  allow_from_disk+check_crc - same as "trusted_source"
        // Three types of file specifications:
        //      1. directory\*.*                        - refers to all files under the directory
        //      2. directory\...                        - refers to all files under the directory and all directories under that (recursively)
        //      3. directory\filename           - refers to a single file
        // Allow custom player models.
        models\player\...           any
        materials\models\player\... any
        // Allow custom spray decals.
        materials\temp\...          any
        materials\vgui\logos\...    any
        materials\vgui\logos\ui\... any
        // Allow "mymod" resources to come from disk.
        materials\mymod\... any
        models\mymod\...    any
        sound\mymod\...     any


The attributes for files are applied in top-down order in the pure_server_whitelist.txt file. This way, you can apply one attribute to a large set of files and a different attribute to a subset of those files. For example, if you wanted to force all models to come from Steam except the models under models\MyMod, you could add these lines to your pure_server_whitelist.txt file:

   models\...         from_steam
   models\MyMod\...   allow_from_disk+check_crc

Advanced Usage

If you set sv_pure to 2, then the server will not even load the pure_server_whitelist.txt file. Instead, it will apply the from_steam attribute to all materials, models, and sounds. This can be useful for competitive matches where one team is hosting the game. The team who is not hosting the game can look in their console at round start and see which sv_pure mode the server is using. If the server is using sv_pure 2, then the non-hosting team can know that the players on the hosting team are not using custom content.


Source SDK 2007 apparently has problems when checking directories having files as well as directories on the Linux platform (Windows behaves correctly).

For example doing something like this would lead to sv_pure error when the MyModDecals contain files and some subdirectories:

materials\MyModDecals\*.* allow_from_disk+crc_check
materials\MyModDecals\... allow_from_disk+crc_check

You should avoid this and put the files into their subdirectories and check them separately.


There are two places where sv_pure will affect performance.

When the server loads its first map with sv_pure set to 1, it has to calculate file CRCs for all files marked as allow_from_disk+check_crc.
Generally, this set of files should be set to the minimal set of files. If, for example, the pure_server_whitelist.txt file had a line like materials\... allow_from_disk+check_crc, the server would pause for a very long time the first time it loaded a map because it would calculate CRCs for every single material file in the game.
Setting sv_pure to 2 will not affect server performance because the server does not need to calculate CRCs.
When a client loads a map and the value of sv_pure has changed, the client will reload any content necessary to make sure it is obeying the pure server's rules.
So if the client had many materials, models, and sounds that were customized on a previous server and then connected to a pure server, the client would have to reload all those materials, models, and sounds.
Generally, the performance hit on the client is negligible because the client will only flush out a few files when connecting to a pure server.