Setting up your users.ini file

Subiect: Setting up your users.ini file Vin Feb 06, 2009 11:47 pm

Setting up your users.ini file

This file controls the access levels of administrators to Admin Mod commands. To be an administrator on the server, your name, WONID, or IP must be in this file. The users.ini file also enables nick name and WONID protection/reservation.

The users.ini file is where you will store all of the player names, WONIDs, IPs, passwords, and access levels of the users to whom you wish to grant privileges on your server. In the interest of being complete, but not confusing some, we will start with simple examples here and get more technical as we go along. The sample users.ini file that comes with the Admin Mod distribution is documented with internal comments, as well. For clarity names, WONIDs and IPs will be highlighted in green, passwords fields in blue and access levels in red. If you get confused, remember this legend.

The normal format of the users.ini like this:

username:password:accesslevel

Without the appropriate password, a user identified in the users.ini file and the wrong password will not able to use the rights granted to them which can include not being able to join the server if they have reserved access.

Each of the three segments will be explained below.

Field One: Names

There are four ways to identify users in this file and give them access. Each method of specifying the user's identity (player name, WONID, Steam Id or IP) offers its own different advantages and disadvantages:

* Player Name

playername:password:accesslevel

Using someone's player name to give them access to Admin Mod commands means that, to use the commands, the person has to use the name exactly as it is in the users.ini file. (Names AND passwords are case sensitive.) However, they can use their name and password from any computer. The player name cannot be numeric (composed only of numbers), as it will always be interpreted as a WONID. If a name contains one or more colon characters (":") they are required to be 'escaped' or Admin Mod will see them as dividers and mis-parse the data. To escape a character, place a backslash in front of it (so ::AM::alfred becomes \:\:AM\:\:alfred). Divider colons must never be escaped.

* WONID

wonid:password:accesslevel

Using someone's WONID to give them access to Admin Mod commands has the advantage of letting a player use any name he wishes while playing, because, as long as he stays on the same computer, his WONID will not change. On the other hand, because of the way the WONID is calculated, if the player who has access to Admin Mod commands attempts to play using another CD key, he will be unable to access those commands. If the user is on his computer, but does not have the appropriate password, he will be kicked from the server to which he should normally have access. Had the permission been given through the use of the player name, he would have been able to access the server with a different name.

N.B.
WONIDs are no longer available for internet play and cannot be used to provide access. This information is retained for compatibility reasons and for those who may be using a WONID provider other than the central WONID servers previously used by Valve.
Admin Mod can still use WONIDs internally but their use is deprecated from Admin Mod 2.50.58 onwards.
For general use WONIDs should no longer be used to grant access to individuals. Steam Ids should be used instead.

* Steam Ids

authid:password:accesslevel

A Steam Id can either look like this STEAM_056789, which is the word STEAM followed by an underscore, a number, a colon and a second number. Or it can look like so: STEAM_056789, which is a second colon and a third number in addition to the format above. You enter the Steam ID exactly in the same format that you see when you use the "users" or "status" command in the server console.

The colons in the Steam Ids should not be 'escaped'. This is different from using colons in names (see above). Admin Mod will recognize that a Steam Id has been used in the users.ini field and will use the colons to recognize the correct format. Do not 'escape' the colons. As an example, using the example Ids from above a users.ini line with a Steam Id would look like the following:

STEAM_056789:secretpass:1023

or

STEAM_1:23456789:hushhush:121356

* IP address

IP:password:accesslevel

The ability to use IP (Internet Protocol) addresses to determine Admin Mod access was a new addition to version 2.50.50. The purpose of using an IP to determine player identification is mainly for LAN servers. In the past, a server administrator could not allocate administrative access with WONIDs on a LAN since the same cd key can be used on multiple computers when playing LAN games. However, IPs are unique to every computer, and a LAN user can therefore be granted access even though they have the same WONID as another user. The disadvantage is that since access is granted by computer, any user on a computer with Admin Mod access can execute Admin Mod commands.

Field Two: Passwords

* Passwords are case sensitive which means for example that 'T' and 't' are two different characters. If this is ignored the users may not be able to gain access to their rights.

* Passwords can be blank. this allows you to allocate access/name reservation without forcing the user to supply a password. Global default access should be allocated with the default_access CVAR though.

* Encrypted passwords are available which can increase password security. *nix based operating systems have the required tools as part of the OS distribution and tools are provided with Admin Mod allowing encryption to be used in Windows based OSs

* As of Admin Mod 2.50.26, passwords are only ever exchanged between the server and individual client system preventing cheats from sniffing the passwords.

Field Three: Access Levels

You determine a user’s permissions by adding up the access levels for all of the commands you want that person to be able to use on the server. We have provided a friendly little javascript calculator that will do the work for you. The chart provided shows the access levels, and the associated Admin Mod commands, followed by some simple instructions covering how to calculate the correct access level for the commands you want to provide to a user.

The access levels are simply numbers. The numbers are fairly meaningles in decimal notation but viewing in binary shows you that each access level corresponds to a single bit in the number. The numbers can easily be worked with by treating each level as a switch bit in the binary representation of the number, 1 is on 0 is off for that level. If you don't understand binary numbers then it is best to deal with the access levels as decimal numbers but it is far easier to quickly understand access levels in binary notation.

The access levels used in Admin Mod plugins are defined in the include files that are used to compile the plugins. If you wish to change the access levels for any reason (for example to move commands to different levels) then the plugins shoudl be edited to change the individual commands. If you wish to change all commands on a single access level then the include file should be edited to change that access level. Both these methods of alteration require some knowledge of plugin scripting. All the access levels use by Admin Mod apart from a small number (reserved slot access level and reserved name access level) can be changed by the user.

The rules of Users.ini

Access levels

Note that if you give a user access to a given level, you are giving access to all commands on that level (level 512 gives access to admin_cfg, admin_servercfg and admin_hostname, for example). You cannot selectively give access to only one command in a given level – they come as a package. They have been grouped in a way that makes good logical sense, though, so you will most likely not find the grouping to be a problem. If you are an adventurous scripter, you can modify the access levels for each command and create your own custom security levels, but that is beyond the scope of this configuration document.

As you can see, access relies on the equation between two things: name/WONID/IP and password. In the same users.ini file, multiple players can have the same password, and the same player name can have different access levels with different passwords.

The users.ini is read from the top to the bottom which allows some interesting configurations. Be careful, however, as this is also an easy sources of hard-to-find errors.
A pair of entries like this for example:

player:testpass:199

player:testpass:65535

Will always give player access level 199, the second line will never come into effect because once the player and password are matched, the searching stops.

There is an exception to this. If a name is reserved anywhere in the users.ini and the connecting player and password combination does not have the reserved access level (level 16384) then they will not be allowed to join. So in the example below

player:access_pass:199

player:name_pass:16384

If player connects with his password set to access_pass despite the fact that the first line will be matched first Admin Mod will still check the to see if the name is reserved, if it is and he does not have the proper password or access to reserved nick (his use of access_pass only grants him the access level of 199 and not the reserved access level of 16384) he will be kicked. In this case the levels could be combined and given the same password.

Using a blank password

If you have a player who you don't want to provide a password for then you should leave the password section of the entry blank. The colons separating fields are still required. For example if you are specifying a user by their Steam Id you may not need a password because no-one but that user has their Id. In which case you would use something like this:

STEAM_0:1111:2222::65535

now the user can connect from machine and as long as the the Steam Id is matched they will be granted the access level in the final part of the string.

Reserving a user name and WONID

If you have a player who mostly plays from home but occasionally plays from someone else's computer, you can allocate their access by reserving both their username and WONID. This method works because both username and WONID reservation use the same password and have the reserved name access. You create two entries in the users.ini, one using the WONID and the second with the user name:

WONID:password:16384

username:password:16384

now the user can connect with his the same password from anywhere. if he is at his own machine the WONID entry will be matched and if he is at another machine the user name can be matched.

Linking a user name and WONID

Another interesting ability is that of linking a WONID and user name. This allows you to reserve access using WONIDs (better security) and to prevent other players using the nickname. This is accomplished by first adding the user with a normal WONID type entry. Then on the next line put the name you wish to reserve, replace the password with the WONID from the entry above it and the access number should always be minus 16384. It sounds complicated but it's really not:

123456:password:access

player:123456:-16384

This allows player to connect and gain access using his wonid, it will also prevent other people from using his user name.

Using REGEX for your user names

REGEX is a text formatting tool supported by Admin Mod , which allows you to do a number of things, such as using special characters in user names, blocking or protecting parts of a name and protecting clan tags.

Getting started with REGEX and AM:

It's important to realize that once you turm on REGEX you have to adapt your users.ini to match the REGEX rules.

In order to utilize REGEX in Admin Mod, you first must set the value of the use_regex CVAR in your server.cfg file to "1" to enable it.

Once enabled, you can use a partial name in your users.ini file, for example, to protect your clan tag. Let's say your clan uses the tag [AMbT].

\[AMbT\]Jaguar:PaSsWoRd:65535

\[AMbT\]Rope:paSSwOrd:65535

\[AMbT\]:PAssWOrd:16384

The above entries would allow Jaguar and Rope to connect using the clan tag, if they successfully authenticate, but will not allow anyone who is not listed in users.ini to connect with the [AMbT] tag. Note that with this setup, anyone who is not listed by username, but who uses the tag and supplies the correct password, would be given only reserved nickname access (16384) and nothing else in the above example.

Note that the brackets in the above example are both preceded by back-slash characters ("\"). The back-slash character denotes that the character to the right of it is to be treated as a text character, rather than as an operator. In other words, it allows non-alphanumeric characters to be used as part of a username. This is especially helpful when you are wanting to assign a username that includes any of the "forbidden characters." As a general rule, any character not listed below should be escaped (preceded with a back-slash) when using REGEX.

A-Z

a-z

0-9

- _ / .

A complete discussion of REGEX, it's uses and detailed explanation is beyond the scope of this manual. If you need REGEX support with Admin Mod, feel free to post your questions in the Admin Mod Forums.

More information about REGEX can be found on the web:

http://www.delorie.com/gnu/docs/regex/regex_toc.html