Pure Servers

From Valve Developer Community
Revision as of 14:03, 11 March 2012 by Yuri (talk | contribs) (2007 problem udner linux)
Jump to: navigation, search

A pure server is one that forces all clients on the server to use content that matches what is on the server. This 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.

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.

Whitelist File Format

There are two different whitelists currently in use by Source games, and one is whitelist.cfg. Currently this file is under apparent speculation more info will come soon. This file is found in the main game directly (orangebox/<game>/...) for example. The next whitelist file is the pure_server_whitelist.txt file found in /hl2/. This whitelist is used in 2009 and before Source engine 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.
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.
Clients can load the specified files from disk, but their on-disk files must match the files on the server.


   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 or whitelist.cfg file and you set sv_pure to 1, there would be no difference from sv_pure 0.

Note.png Note: The default pure_server_whitelist.txt and whitelist.cfg 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 or whitelist.cfg file, 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

Default whitelist.cfg File

The default whitelist.cfg 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.

// Note:  Items are evaluated in order...
//	"add"		"save/..."    // does a recursive *.*
//	"add"		"screenshot/*.*"  // does a non-recursive *.*
//	"remove"	"save/..."
//	"remove"	"maps/*.*"			
//	"add"		"e3_town_02.dem"			// adds a single file
//	"remove"	"maps\d1_town_05.bsp"		// removes a single file...

	// Individual files to pass through...
	"add"		"unusedcontent.cfg"
	"add"		"whitelist.cfg"
	"add"		"buildreslists.bat"
	"remove"	"cfg/config.cfg"

	"add"		"maps/stats_overview/..."

	// Additional files/directories to allow
	"add"		"materials/console/..."
	"add"		"materials/vgui/..."
	"add"		"materials/sprites/..."
	"add"		"materials/hud/..."
	"add"		"materials/debug/..."
	"add"		"materials/shadertest/..."
	"add"		"materials/engine/..."
	"add"		"materials/dev/..."
	"add"		"materials/voice/..."

	"add"		"sound/combined/..."
	"add"		"sound/UI/..."
	"add"		"sound/common/bugreporter_*"


The attributes for files are applied in top-down order in the pure_server_whitelist.txt and whitelist.cfg 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 or whitelist.cfg files. 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.