Using the Chat Relay

Note: If the Chat Relay is running, any changes to the properties file will not become active until the Chat Relay is restarted.

Starting the Chat Relay

Linux

Execute the startup script:

<INSTALL_PATH>/bin/start.sh

Optional: If you would like the Chat Relay to start when the system boots, then perform the following steps:

• 1. Edit the <INSTALL_PATH>/etc/init.d/checkvalvechatrelay script and set the value of the BASEDIR variable

1. Run the following commands (as root):

cp <INSTALL_PATH>/etc/init.d/checkvalvechatrelay /etc/init.d

insserv checkvalvechatrelay

Windows

Navigate to the <INSTALL_PATH>\bin directory and double-click on the startup.bat file, or execute the startup.bat file from a DOS command prompt.

Advanced Startup Options

The startup scripts for both Linux (start.sh) and Windows (startup.bat) take the following optional command-line arguments:

Command-line options:

--config <file> Read config from <file> [default = checkvalvechatrelay.properties]

--minheap <size> Set the JVM's minimum heap size to <size> [default = 8m]

--maxheap <size> Set the JVM's maximum heap size to <size> [default = 16m]

--debug Enable the Java debugging listener (for use with jdb)

--debughost <ip> IP for jdb connections if debugging is enabled [default = localhost]

--debugport <port> Port for jdb connections if debugging is enabled [default = 1044]

--help Show this help text and exit

Note: For --minheap and --maxheap, the <size> value should be a number followed by "k" for kilobytes, "m" for megabytes, or "g" for gigabytes (Ex: 1048576k, 1024m, 1g).

Stopping the Chat Relay

Linux

Execute the <INSTALL_DIR>/bin/stop.sh script.

Windows

Navigate to the <INSTALL_DIR>\bin directory and double-click on the shutdown.bat file.

Testing the Chat Relay

The CheckValve Chat Relay includes a few utilities for testing its functionality. Specifically, it includes a utility to send simulated SRCDS log messages to the Chat Relay, as well as a simple client which can connect to the Chat Relay and show relayed messages. These utilities are located in the <INSTALL_DIR>/util directory, and are provided in both Perl and Java.

Testing the message listener

The UDP message emitter sends a simulated SRCDS log message to the Chat Relay.

Perl usage:

perl udp_message_emitter.pl

Java usage:

java UDPMessageEmitter

Regardless of the invocation, the command-line options are the same:

Command line options:

--to <ip>:<port> Send messages to the listener at the specified IP and port (default = 127.0.0.1:12345)

--from <ip>:<port> Send messages from the specified IP and port (default = 127.0.0.1:2345)

--delay <num> Send a message every <num> seconds (default = 1)

--limit <num> Stop after sending <num> messages (default = no limit)

--message <string> Send <string> as the message text (default = "This is a test!")

--sayteam Make this a say_team message (default = say)

Notes:

• You can also use the short options -t, -f, -d, -l, -m, and -s, respectively.

• There are no required command-line arguments; the defaults will be used if none are provided.

• When using the --from option, the specified address must be assigned to a network interface on the host.

Testing the client listener

The chat logger opens a client connection to the Chat Relay and displays messages received from the relay.

Perl usage:

perl chat_logger.pl

Java usage:

java ChatLogger

Regardless of the invocation, the command-line options are the same:

Command line options:

--chat-relay <ip>:<port> Connect to the CheckValve Chat Relay at the specified IP and port (required).

--game-server <ip>:<port> Request chat messages from the game server at the specified IP and port (required).

--limit <num> Stop the chat logger after receiving <num> messages.

--password <password> Specify the CheckValve Chat Relay password.

--quiet Suppress connection and status messages.

Notes:

• You can also use the short options -c, -g, -l, -p, and -q, respectively.

• The Chat Relay (-c or --chat-relay) and game server (-g or --game-server) options are required.

• The password option (-p or --password) must be specified if the Chat Relay requires a password for client connections.

The Chat Logger utility will print chat messages to the console. If you wish to log these messages to a file, you must redirect the program's output. On DOS and most Linux shells, this is accomplished using the ">" operator to write to a new file, or the ">>" operator to append to an existing file. The following examples demonstrate logging to a file.

Example: Save chat messages to a new file:

java ChatLogger -c 127.0.0.1:12345 -g 127.0.0.1:27015 -p myPassword -q > chat-messages.txt

Example: Append chat messages to an existing file:

java ChatLogger -c 127.0.0.1:12345 -g 127.0.0.1:27015 -p myPassword -q >> chat-messages.txt

When logging chat message to a file, it may also be preferable to run the Chat Logger as a background process. The following examples demonstrate how this can be accomplished.

Example: Run the Chat Logger as a background process in a Linux shell and save messages to a new file:

java ChatLogger -c 127.0.0.1:12345 -g 127.0.0.1:27015 -p myPassword -q > chat-messages.txt &

Example: Run the Chat Logger as a background process in a DOS shell and save messages to a new file:

START /B java ChatLogger -c 127.0.0.1:12345 -g 127.0.0.1:27015 -p myPassword -q > chat-messages.txt

Connecting to the Chat Relay

Clients

The CheckValve Chat Relay listens for client connections via TCP on the port specified in the configuration file. The default port for client connections is 23456. When a client connects, the server returns its identity string and then waits for a connection request from the client (see Packet Types and Formats). The server will close the socket if another packet is not received within 2 seconds, or if the next packet is not a connection request.

Note: No message is returned to the client if the connection is timed out, but the timeout is logged and it counts as a bad connection attempt for the client IP if auto-bans are enabled.

Game servers

Logging must be enabled on the HLDS/SRCDS server, and the server must be configured to send log messages to the Chat Relay. This is done using the logaddress_add console command. To configure a server to send log messages to the chat relay, enter the following lines into the server console or the server's configuration file (usually server.cfg) where <ip> is the IP address of the Chat Relay, and <port> is the message listener port (12345 by default):

Source engine:

log on

logaddress_add <ip>:<port>

GoldSrc engine:

log on

logaddress_add <ip> <port>

Note: In Source engine servers, the IP and port are separated with a colon, but in GoldSrc servers (such as Counter-Strike 1.6), the IP and port are separated by a space.

Securing the Chat Relay

Auto-banning clients

Enabling the auto-banning feature is highly recommended in order to mitigate the risk of denial-of-service attacks or other possible problems.

Restricting client access

Client access can be further restricted using rules in the server's local firewall or your site's main firewall, if you have one. If you have a specific set of client IPs who should have access to the Chat Relay, you can create firewall rules to allow only those IPs and block everything else.

A simple example of an iptables rule set to restrict client access:

/sbin/iptables -A INPUT -s 1.2.3.4 -p tcp --dport 23456 -j ACCEPT

/sbin/iptables -A INPUT -s 2.3.4.5 -p tcp --dport 23456 -j ACCEPT

/sbin/iptables -A INPUT -p tcp --dport 23456 -j DROP

In this example, we are allowing client connections on port 23456 (the default client listener port) from the IP addresses 1.2.3.4 and 2.3.4.5, and dropping all other packets coming to that port. Note that the name of the chain (INPUT in this example) may be different depending on the Linux distribution.

Protecting the message listener

Auto-banning and TCP firewall rules only work for clients connecting to the client listener. To protect the message listener from being flooded by unwanted UDP traffic, you should create rules in the server's local firewall to allow traffic from the desired game servers, and block everything else.

A simple example of an iptables rule set to protect the message listener:

/sbin/iptables -A INPUT -s 1.2.3.4 -p udp --dport 12345 -j ACCEPT

/sbin/iptables -A INPUT -s 2.3.4.5 -p udp --dport 12345 -j ACCEPT

/sbin/iptables -A INPUT -p udp --dport 12345 -j DROP

In this example, we are allowing incoming UDP packets to port 12345 (the default message listener port) from the IP addresses 1.2.3.4 and 2.3.4.5, and dropping all other packets coming to that port. Note that the name of the chain (INPUT in this example) may be different depending on the Linux distribution.

Logging

Logging options

Logging is enabled when the logFile option is set in the properties file, and the value is a file which the Chat Relay can create and write to. If the value of logFile does not include the full path to the file, then the Chat Relay's working directory will be used. If this option is missing or empty, or if the specified file is not writable, then no logging will occur. The default value in the properties file is checkvalvechatrelay.log without any path specified.

Log Rotation

If log rotation is enabled, then the log file will be rotated at the interval specified by the logRotateInterval option in the properties file. Old logs are stored in the same directory as the open log file, and the number of old logs which are kept when a rotation occurs is specified by the logRotateKeepFiles option in the properties file. In the default properties file, log rotation is enabled and will occur once per week, and up to 10 old log files will be kept.

Startup messages

On startup, the Chat Relay will write a series of log messages prefixed with [STARTUP] which give some basic information about the environment and configuration.

Shutdown messages

On shutdown, the Chat Relay will write a series of log messages prefixed with [SHUTDOWN] which include information about the shutdown process.

Client-related messages

For each successful connection attempt, the Chat Relay will log the client's IP address and port number, the IP address and port number of the game server from which the client wants to receive chat messages, and the internal connection slot to which the client has been assigned (the number of available connection slots is specified by the maxClients option in the properties file). The Chat Relay will also log client errors or disconnections.

For each rejected connection attempt, the Chat Relay will log the client's IP address and port number, and the reason the connection was rejected. A rejected connection will not be logged if auto-banning is enabled and the client IP has been banned.

Error messages

If an error occurs, the Chat Relay will attempt to log the error and resume normal operations, if possible. Error messages are prefixed with ERROR: and usually include a description of the error, as well as an indication regarding whether or not the error was fatal. To see more detailed information about errors and exceptions, increase the value of the debugLevel option in the properties file (see Configuring the Chat Relay).

Auto-ban messages

If auto-banning is enabled, then the Chat Relay will write log messages whenever new bans are put in place or old bans expire. Each of these messages is prefixed with [AUTO-BAN].

Stats messages

If statistics logging is enabled, then the Chat Relay will periodically write some statistics to the log file. Each of these messages is prefixed with [STATS]. The interval at which these statistics are logged is defined by the logStatsInterval option in the properties file. In the default properties file, statistics logging is enabled and will occur once every 24 hours.

These messages include the following information about the Chat Relay:

• • Uptime (how long the Chat Relay has been running)

  • Memory usage

    • Maximum memory which the Chat Relay can use (defined in the startup script)

    • Amount of memory which has been allocated to the Chat Relay

    • Amount of the allocated memory which is currently being used

    • Amount of the allocated memory which is currently free

  • Total number of packets received since startup

  • Number of chat packets processed since startup

  • Number of accepted client connections since startup

  • Number of rejected client connections since startup

  • Number of clients currently connected

  • Number of clients currently banned (if auto-banning is enabled)

Notes:

• • A packet is only processed if there is at least one client who wants messages from the game server which sent the packet. Therefore, the number of chat packets processed only reflects those packets which were received when a client was listening for those chat messages.

  • The memory usage numbers are not averaged over time; these are simply the real-time values polled at the time the statistics are logged. However, these values can be useful in spotting memory leaks, or determining whether the runtime memory settings need to be adjusted.

Debug messages

If debug logging is enabled, then the Chat Relay will write more verbose messages to the log file. Each debug message is prefixed with [DEBUG(#)] where # is the debug level which caused the message to be written. Debug logging is enabled by setting a non-zero value for the debugLevel option in the properties file. Log messages are written for all debug levels up to and including the specified level.

Update messages

If update checking is enabled, then the CheckValve Chat Relay will check for a newer version on startup, and then re-check at the interval specified by updateCheckInterval (once per day by default). If an update is available, then a message will be logged. The message will also be shown on the console if (and only if) an update is detected during startup. Each of these messages is prefixed with [UPDATE].