//==============================================================================
// GLevelSecurity v2.11
//==============================================================================

//=================
Change Log:

6/21/11	-	Initial release!


//=================
Abstract:
	GLevelSecurity provides a simple table based authorization scheme found
in many Unix operating environments. The table based scheme allows the server admin
to clearly define who can perform what operations. GLevelSecurity also provides
some control over chat and inventory respawn aspects of the game.


//=================
Installation:
	The following files should be included with this README:
	-GLevelSecurity.u		(Main file)
	-GLevelSecurity_Shared.u	(Main file)
	-IPPlugin.u			(IP retrieval template class)
	-IPPlugin227.u			(Implements IPPlugin interface 
					-- included for convenience; valid only
					on Unreal version 227)
	-GLevelSecurity.ini
	-GLevelSecurity.int

	Place all files in your Unreal's system directory. Change the following
line in your JGrass.ini file:

	SecurityHandlerClass=GLevelSecurity.GLevelSecurity

	GLevelSecurity will now automatically load with your server when running JGrass.

	You should not add GLevelSecurity, IPPlugin or IPPlugin227 to serverpackages, 
but you do need to add GLevelSecurity_Shared to serverpackages to allow clients 
to access SecurityInfo related data.

//=================
Help / Walkthrough:
	
	GLevelSecurity's main strength comes from its table/level based authorization
method.

	Before getting into the configurable variables, the following is a logical
descrition of the different levels of administration:

	AdminLevel 1 - Server administrator. Should be allowed to perform any action.

	AdminLevel 2 - Secondary administrator. Typically given basic moderative
			action authorization in addition to all lesser admin actions.

	AdminLevel 3 - Temporary administrator. Typically allowed to perform basic
			non-moderative actions such as God/Fly... in addition to
			all lesser admin actions.

	AdminLevel 4 - Client. The default level of any non administrative player.

	To configure GLevelSecurity, you can either access the variables through 
GLevelSecurity.ini or through AdvancedOptions when the server is running (GameTypes->
JGrass->Handlers->SecurityHandlers->GLevelSecurity). Descriptions of these variables
follow below:

[ActionControl]
ActionLoggingType -	Allows you to choose how actions will be logged (an action
			is a command or event that requires authorization).
			ALT_All - Logs all actions.
			ALT_ValidatedOnly - Logs accepted actions only.
			ALT_RejectedOnly - Logs rejected actions only.
			ALT_None - No logging of actions.

AuthorityTable -	The main table that defines what actions can be executed
			by what levels of admin. Each entry has the following
			structure:

			Action - The name of the action.

			ActionType - What kind of action it is. The following
					numerical values correspond to their
					action types:
				0 - Security. This is a security command/action.
				1 - GameLogic. This is a game command/action.
				2 - Player. This is a player class command/action.
				3 - Mutator. This is a mutator related command/action.
				-1 - Unknown.
				
				If, for example, the action is a command in a 
				GameLogicHandler subclass, the action would have
				to be flagged as ActionType 1 to correctly correspond
				to the code associated with that action. Failure to
				correctly flag actions with their ActionTypes will
				most likely lead to action rejection (failure to
				look up in the table).

			MinAdminLevel - The minimum (ie. least powerful) level of
					admin required to be authorized to perform
					the associated action. For example, a min
					admin level of 1 would permit only level 1
					admins to perform the action, but a min
					level of 3 would allow levels 3, 2, and 1
					to perform the action (numerically, this is
					the "max" level, but in terms of admin power
					it is the least required power to perform
					the action).

			bCovert - If set to true, the action will be not be broadcasted
					to other clients. This should be used for actions
					that should not be publically viewed (such as the
					Login command)
	
DefaultAction - 	This entry is identical in structure to an entry in the
			AuthorityTable and serves as the default action in case
			the lookup of an action failed. It is recommended that you
			leave this entry at its default value (rejection).

MaxRejectionsPerSecond -	Maximum number of allowable failures by a user
				to perform an action before they are automatically
				ejected from the server.

[ChatControl]
AntiSpamMuteTime -	Time in seconds to mute a client after they have been
			detected as spamming.

bChatLog - 		If true, chat will be logged to the server console.

MaxMessagesPerSecond - 	Max. # of messages that a single client can send per
			second before being marked as spamming.

MinAntiSpamOverrideLevel - 	Any admin with an admin level of power equal
				to or greater than this level will bypass
				all spam detection. For example, setting this
				to 2 will allow admin levels 2 and 1 to
				spam without being muted.

[GameControl]
bForceSeedNoRespawn -	If true, the "seeds" inventory item will not respawn.

[LoginControl]
AdminPassword -		The three admin passwords corresponding to the three
			levels of administration. Entry 0 -> Level 1, Entry
			1 -> Level 2, Entry 3 -> Level 3.

bAllowOnlyGPlayerSubclasses -	If true, only subclasses of GPlayer will be
				allowed to join the game.

BanTable -		Contains all of the entries corresponding to banned
			players. Each entry has the following structure:
			
			BanEntryDate - Date when the ban was inserted.
			
			BannedBy - Textual name of the banning administrator.
			
			BanReply - Custom rejection message given to the
					banned player.
	
			IP - IP address of the banned player.

bAutoBanRJA - 		If true, then Repetetive Join Attacks will be blocked
			and the offender will be automatically banned.

GamePassword -		If filled in, all incoming clients must provide
			this password to enter the server.

IPPluginClass -		Plugin class to use for retrieving IP addresses
			associated with specific clients. This must properly
			load to enable banning functionality.

MaxPlayers -		Maximum # of players allowed to be in the game.

MaxSpectators -		Maximum # of spectators allowed to be in the game.

MinbAdminLevel - 	The minimum level of admin required to set the bAdmin
			variable in the admin's playerclass to true. This
			is here to provide compatibility with custom player
			classes that may rely on the bAdmin variable. It
			is recommended to set this to either 2 or 1 to
			avoid exposing the server to possible abuse of admin
			commands from lesser (generally less trustworthy)
			admins.

[ReportingControl]
bBroadcastAuthorizations -	If true, then all authorization transactions
				will be broadcasted as a security event.

bHUDCompatibilityMode -		If true, then all messages will be broadcasted
				as type 'event'. Otherwise, messages will be
				broadcasted with the type GSecurityHandler to
				allow for custom rendering by custom HUD classes.
				Set this to true if you are unable to see 
				security messages in game.

bSilentSecureMessages -		If true, security messages will not cause a 
				message sound on the client.

GeneralSecureMessages -		The tag displayed before any security message.

MinReceiveSecurityEventsLevel -	Minimum level of admin required to receive
				security event messages. Setting this to 4 will
				make security messages public (good for keeping
				your admins honest :)

	---

	GLevelSecurity provides a series of administrative functions that
allow admins to keep the server under control. The following is a list
of Actions and their associated Effects. You can modify the entries (
as these are all provided by default) in your table to alter the 
authorization behavior associated with each command. All commands must
be prefixed with the word "secure" to be executed (for example, "secure
login" is a valid command but "login" alone is not.)

Action		|	Effect
-----------------------------------------------------------------------------
Help		-	Displays all commands that are available to the user.
			Hides commands that the user is not authorized to use.

Login		-	User can attempt to log in as an administrator with
			this command.

Logout		-	Resets the user's admin level to the client level (4)
			and sets bAdmin back to false on the user. Effectively
			logs the user out from all administrative privileges.

SetName		-	Stock Unreal 1 behavior. Changes the name of the user.
			Parameters are <New Name>

KillAll		-	Destroys all actors in the game with the same class
			name as the input string. Paramters are <Class Name>

Admin		-	Executes a command in the context of the server.

GetIDs		-	Displays the ID associated with each player in the
			game.

GetIPs		-	Displays the IP associated with each client in the
			game. Requires a valid IPPlugin class.

ListBans	-	Lists all bans currently in the ban table.

BanID		-	Bans the client with the associated input ID. 
			Parameters are <ID> <Reason> where Reason is the
			rejection message that will be displayed to the
			client when they try to connect.

BanIP		-	Same as BanID but the first parameter is <IP> 
			instead of <ID> where <IP> is a dotted 4 subnet
			IP address (e.g. "1.2.3.4").

RemoveBan	-	Removes a ban from the associated slot number.
			Parameters are <Slot #>.

End		-	Toggles the end on or off. Parameters are <"on"/"off">
			where "on" will enable the ends and "off" will
			disable them.

ASay		-	Displays a message to all administrators (admins of
			level 3, 2 or 1). Parameters are <Message>.

PsayID		-	Privately messages a given client. This command is
			special in that it will NOT be logged or broadcasted
			regardless of any setting. Parameters are <ID> <Message>

SummonID	-	Summons a player in front of you. Parameters are <ID>

GoToID		-	Teleports to a player. Parameters are <ID>

RestartID	-	Restarts a player. Parameters are <ID>

GiveAdminID	-	Gives admin privileges to a player. Parameters are <ID>
			<Admin Level>. You cannot grant a more powerful level
			of admin to a client for obvious reasons.

RevokeAdminID	-	Takes away admin privileges from a player. Parameters
			are <ID>. You cannot revoke admin from a player with
			a more powerful admin level than your own.

KillID		-	Kills a player. Parameters are <ID>

KickID		-	Ejects a player from the server. Parameters are <ID>

MuteID		-	Mutes a player. Parameters are <ID>

UnmuteID	-	Unmutes a player. Parameters are <ID>

FreezeID	-	Freezes a player in place. Parameters are <ID>

UnfreezeID	-	Unfreezes a player. Parameters are <ID>

RenameID	-	Renames a player. Parameters are <ID> <New Name>

	---
	
	As an added note, GLevelSecurity provides an extra level of security against
unwanted player classes on the server. In order for a playerclass to be allowed,
it must be in serverpackages. Though this may seem obvious at first, an example
of where this filtering would be useful is where you have a player class "GMyClass"
defined in package "GMyPackage". GMyClass is a player subclass that implements
the code in GPlayerTemplate, enabling it to function completely with the framework,
but GMyClass is a subclass of MyClass which resides in MyPackage. Visually,

	Playerpawn
	|_MyPackage.MyClass
			|_GMyPackage.GMyClass
			
	Let's say that you want to only permit GMyClass to join but not MyClass. You
can do this by adding GMyPackage to ServerPackages but not MyPackage.
This is fine, because GMyPackage is statically linked with MyPackage, and thus
incoming clients will download both files. However, if a client tries to explicitly use
the MyPackage.MyClass playerclass then the server will reject the request.

	This type of filtering is useful for filtering on a package basis. If two player
classes reside in the same package but one of them is unwanted then this
scheme is insufficient to provide such fine grain selectivity of playerclasses. 
This is, however, a fairly rare case and is not covered. It can easily be covered
by modifying the server side file (GLevelSecurity.u) with a simple array based
blacklist. For simplicity, this functionality is not provided by default in GLevelSecurity
but will be added if there is sufficient need for it.

								
//=================
Conclusion:
	If you have any questions or comments, feel free to email me at 
	pravin_prabhu at hotmail.com.

You can also post on the UDHQ forums, found at 
	http://udhq.falconpunch.net/phpBB3/

Keep it Unreal!
-Pravin "Pcube" Prabhu
http://udhq.org

END





