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 requires two things:
configuring the PB Server to accept remote UDP consoles as this facility is disabled by default
running our PBUCON console applet which can be obtained from one of the links below
The minimal configuration for a PB Server to accept PBUCON sessions requires three things:
creating a file named "pbucon.use" in the server's home pb folder (file contents does not matter)
setting the pb_sv_usessionlimit setting to a number higher than 0 (which is the default)
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).
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
PBUCON Profile Type Examples
The following are some examples of different PBUCON profile types:
Example 1: pb_sv_uconadd 3 192.168. dorf dorfspassword
Example 2: pb_sv_uconadd 0 10.5.5.5:12345 leaguestream xxx&password&xxx
Example 3: pb_sv_uconadd 1 127.0.0.1: local local
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
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:
server's IP address
your local IP address
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.
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.
For any issues related to PBUCON, please communicate directly with the PunkBuster staff using our