PunkBuster UDP Console (PBUCON)

About

PBUCON is a PunkBuster Server facility that allows server admins to obtain a remote UDP based console with a running PunkBuster Server version 1.225 or higher. Admins can use PBUCON to stream PB logging and optionally issue remote commands and optionally (for some games) stream normal game server logging. PBUCON allows concurrent real-time streaming of PB logging to multiple remote hosts and also does not require any special firewall configuration as it uses the same socket and port used by the running PunkBuster server for communication.

Using PBUCON

Using PBUCON requires two things:

1. configuring the PB Server to accept remote UDP consoles as this facility is disabled by default
2. running our PBUCON console applet which can be obtained from one of the links below

• pbucon.exe v0.983 for win32
• pbucon.run v0.983 for linux

The minimal configuration for a PB Server to accept PBUCON sessions requires three things:

1. creating a file named "pbucon.use" in the server's home pb folder (file contents does not matter)
2. setting the pb_sv_usessionlimit setting to a number higher than 0 (which is the default)
3. creating at least one PBUCON Profile to describe allowable remote sessions

Configuring the Server

Step 1: Create "pbucon.use"

In order for PBUCON to be activated, a file named "pbucon.use" must be placed in the server's "pb" folder. The file can be created with any standard text editor and its contents are irrelevant. (The file may even be empty) Admins that do not have some type of access (such as ftp) to their servers' pb folders must arrange for the server host to create the "pbucon.use" file.

Step 2: Configure the PBUCON Session Limit

The pb_sv_usessionlimit setting determines how many concurrent PBUCON sessions are allowed to be active at any point in time. The PBUCON program sends heartbeats when necessary to an active session (if a packet has not been sent during the past 30 seconds, a heartbeat will be sent to prevent a session timeout). The PB Server will automatically close sessions that are not sending heartbeats after a timeout period. The pb_sv_ucontimeout setting determines the length of the timeout period in seconds (default is 300).

Step 3: Create a PBUCON session profile

All active PBUCON sessions will automatically stream PB logging from the running PB Server to the remote PBUCON console in real time. NOTE: UDP packets are not guaranteed to arrive correctly. When conditions are good or fair, UDP communication is reliable to a high degree of accuracy. However, under poor conditions or with faulty equipment at some point between the PB Server and the running PBUCON program, any given UDP packet can be lost or duplicated.

To create a PBUCON profile, use the pb_sv_uconadd command. It takes 4 parameters as follows:

The [profile_type] parameter is a numeric bit field that will often be 0. It is used to specify options for the profile in addition to logging PB Server output to the remote console. If the admin wishes to allow sessions based on the profile to be able to send remote input (i.e. be able to send commands remotely) into the PB Server console, add 1 (one) to the profile_type. If the admin wishes to have the normal game server logging streamed to the remote console, add 2 (two) to the profile_type. NOTE: PB is not able to stream normal game logging for some games, specifying type 2 for those games has no effect.

The [hostmask] parameter is a string that describes an address or range of addresses that are permitted to open a session for the specified profile. This can be an IP address or a subnet (DNS hostnames/masks will not work). This field can be a single asterisk (*) to denote that the PB Server should accept any source address for this profile. We recommend never using * for a hostmask unless a firewall is in place to restrict communication to only trusted hosts.

The [username] and [password] parameters are used to authenticate remote session creation attempts.

PBUCON Profile Type Examples

The following are some examples of different PBUCON profile types:

In example #1 above, a profile is created with profile_type 3 which means: stream PB Server output (0), allow remote commands (+1), and send game streaming to the remote console (+2); the hostmask of "192.168." means that only remote consoles having an IP address that begins with "192.168." will be accepted; dorf and dorfspassword are the respective username and password for this PBUCON profile.

In example #2, profile_type 0 means only to stream PB logging to applicable sessions and to not accept remote command entry nor stream normal game server logging; the hostmask field for this profile tells the PB Server to expect a session from IP address 10.5.5.5 and port 12345.

In example #3, profile_type 1 means that the PB Server will stream PB Server output (0) and also accept remote command input (+1); the hostmask of 127.0.0.1: means that the PB Server will only allow PBUCON sessions to be opened for this profile when they exist on the same box as the running PB Server.

Additionally, pb_sv_uconlist, pb_sv_ucondel, and pb_sv_uconempty PB Server commands are included for management of PBUCON profiles. Issue "pb_sv_help ucon" for more information on these commands.

There are also cases where a server admin will want to prevent the execution of certain remote commands. The pb_sv_uconignore command can be used for these cases to create a list of "UCON Ignores" that the PB Server will use to discard PBUCON commands when necessary. For example, we recommend in most cases to issue "pb_sv_uconignore quit" so that a remote user doesn't accidentally shut down a running game server by typing the word quit out of habit. For management, additional related commands are pb_sv_uconignorelist, pb_sv_uconignoredel, and pb_sv_uconignoreempty.

Configuring the Client (Connecting to a PBUCON Enabled Server)

On the remote (client) side of things, running the PBUCON utility for the first time will present our End User License Agreement. When accepted, a "pbeula.txt" file is created so that the EULA is not displayed for subsequent sessions. Before a session with a PB Server can be established, PBUCON needs to know four things:

1. server's IP address
2. your local IP address
3. profile username
4. profile password

Most admins will want to put some or all of these items into ".ini" files each corresponding to a game server that will be administered remotely. By default, running PBUCON causes it to look for and parse a file in the current working folder called "pbucon.ini". Admins can, however, set up as many ini files as desired and launch PBUCON with an ini=[filename] command line parameter so that scripts can be written in order to quickly and easily open sessions with any number of servers.

For example, launching PBUCON under win32 with:

will cause PBUCON to open a file called quake4a.ini and parse the lines to obtain the info needed to establish a remote session. A sample quake4a.ini file might look something like this:

If any of the above parameters are not specified in an ini file, PBUCON will still launch but it will prompt for and require input for each unspecified parameter before attempting to establish a session. Note that port numbers must be specified as part of both the server= and myaddr= parameters. The server address represents the game server's active port used for gaming (i.e. what players would use to connect to the server via IP address:port). The myaddr port can be any unused UDP port that you wish to use (typically 1025-65535). When running multiple instances of PBUCON on the same box, you must use a different myaddr port for each instance. Some or all of these items may also be specified on the command line used to launch PBUCON if desired - issue "pbucon help" or "./pbucon.run help" for more information in that regard.

By default, PBUCON logs all output with time/date stamps to a file named "pbucon.log" in the current working folder. To specify a different log filename, use the pbuconlog command followed by the desired filename. This can be specified in the ini file used when PBUCON launches. It can also be changed in the middle of an active session using keyboard console input.

To help debug communication problems between PBUCON and a PB Server, enter 'pbucondebug' into a running PBUCON console. This will toggle debug logging mode which causes all netcode events to be logged.

To exit a running PBUCON session, type 'pbuconexit' into the console and press Enter.

NOTE: All traffic between the pbucon utility and a PB server is encrypted.

PBUCON for Programmers/Scripters

The following section describes how to use PBUCON with other programs and scripts. WARNING: These are advanced topics. If you are not a fairly advanced programmer interested in expanding PBUCON or using it with your own applications, you should ignore this section.

To collect streaming info from a PB Server using PBUCON as a black box, simply parse the local PBUCON log file in a polling manner. As an example for C programmers, simply use fopen with "rb" as the mode (2nd) parameter after specifying the filename with the 1st parameter. This will allow PBUCON to append to the file as logging comes in from the PB Server and your program can keep the FILE handle open continually reading the log file as a stream into a local memory buffer for parsing in any manner desired.

PBUCON can also be configured to accept external input via sockets (either TCP or UDP or both). To configure PBUCON in this manner, place one or both of the following settings into the ini file used for launching the PBUCON process: TCPlistenPort=[port] and/or UDPlistenPort=[port]. PBUCON will only accept administrative commands via these sockets from the localhost address 127.0.0.1. All attempts to control PBUCON from any other address will be ignored. If the UDPlistenPort is used for this purpose, it must not be set to the same port number used for the myaddr parameter. A quick test for TCPlistenPort functionality can be run using any telnet program.

By issuing pbucondebug and connecting to PBUCON with a telnet program, you can see how any external program can control the behavior of PBUCON and cause it to pass commands/input on to the PB Server. Additionally, since PBUCON uses stdin and stdout for input and output these can be redirected as needed (using pipes, etc.) for simple remote access chores. Permission is granted to redistribute our PBUCON applet as a part of non-commercial software systems provided that our copyright is acknowledged, a link to our website is included in the documentation, and end-users must accept, prior to installation or first use, the unmodified EULA presented natively by PBUCON.

Getting Help

For any issues related to PBUCON, please communicate directly with the PunkBuster staff using our Web Ticket System.