
              Dpmaster, a master server supporting the DarkPlaces
                and Quake III Arena master server protocols
           ---------------------------------------------------------

                             Technical information
                             ---------------------


* COMPILING DPMASTER:

Dpmaster is being developed mostly on PC hardware, on Linux and Windows, using
GCC and MS Visual Studio respectively. If you use one of these compilers, you
should be able to compile dpmaster without any problem.
Dpmaster is also occasionally compiled on BSD systems, and on Win32 systems
using MinGW32 (GCC for Win32). It may not compile on these configurations, but
if you're a C developer you should be able to solve the problem(s) easily.

Although great care has been taken to avoid issues regarding CPU endianess and
word size, dpmaster is rarely compiled and run on non-PC hardware. Please
report us any problem on such a system.

To compile dpmaster using GCC on a UNIX system, just type "make" or "make debug"
to build a debug version. To clean the directory from the binary and temporary
files, type "make clean". Note that MinGW32 requires a special syntax: the
commands are respectively "make mingw", "make mingw-debug" and "make win32clean"
in this case.

For compiling with MSVC6, double-click on "dpmaster.dsw" to load the project,
go to the "Build" menu, then "Set Active Configuration..." and select "dpmaster
- Win32 Release". Hit 'F7' to build the project. You'll find the executable
file in the "Release" subdirectory.


* PROTOCOL:

Dpmaster uses a protocol that is heavily inspired by Quake III Arena's master
server protocol. The reference document for this protocol can be found on id
Software anonymous FTP site:
    ftp://ftp.idsoftware.com/idstuff/quake3/docs/server.txt
We have tried to keep our protocol as close as possible to Q3A's one, for a
matter of compatibility with the numerous tools that exist for this game.

Dpmaster uses 5 types of messages: "heartbeat", "getinfo", "infoResponse",
"getservers" and "getserversResponse". The first 3 types are used by servers to
authenticate and register to a master server. The 2 remaining types are used by
clients to get a list of servers from a master server. All messages start with
4 bytes set to 0xFF (character 255), then the command type in plain text.

The 2 types of messages which are likely to cause compliance problems with Q3A-
compatible tools are: "heartbeat" (requires a different protocol string) and
"getservers" (requires a game name before the protocol number). Also, note that
the "infoResponse" messages may be considered invalid by programs which require
precisely the key names used by Q3A in the infostring.

    1) heartbeat: 

        - description:

            The heartbeat is sent by a server when it wants to get noticed by a
            master. A server should send an heartbeat each time it becomes empty
            or full, plus it should make sure the master gets at least one
            heartbeat from it every 5-10 minutes, so the master doesn't remove
            it from its list of active servers.

        - samples:

            "\xFF\xFF\xFF\xFFheartbeat QuakeArena-1\x0A" (Q3A protocol)
            "\xFF\xFF\xFF\xFFheartbeat DarkPlaces\x0A"   (DP protocol)

        - syntax:

            A protocol string is required after the type name, and a line feed
            (character 10, '\n') closes the message. Note that the string after
            the type name is a PROTOCOL STRING, not a game string! Please make
            sure you use "DarkPlaces" as your protocol string. Dpmaster only
            checks this string for debugging purpose for the moment, but it's
            likely to change in the future. You're warned.

    2) getinfo:

        - description:

            This message is sent by a master to a server, usually in response
            to an "hearbeat" by this very server. It's used by the master to
            trigger the sending of an "infoResponse" from the server. The
            challenge string is necessary to authenticate the server's
            corresponding "infoResponse".

        - sample:

            "\xFF\xFF\xFF\xFFgetinfo A_ch4Lleng3"

        - syntax:

            The message type is followed by a challenge string. All printable
            characters but 5 are allowed in this string (from ASCII code 33 to
            126). The 5 exceptions are characters '\', '/', ';', '"' and '%'.

    3) infoResponse:

        - description:

             An "infoResponse" message is the reponse to a "getinfo" request.
             It contains an infostring including the most important information
             about the current server state.

        - sample:

            "\xFF\xFF\xFF\xFFinfoResponse\x0A\\sv_maxclients\\8\\clients\\0\\.."

        - syntax:

            The message type is followed by a line feed character and the
            server's infostring. An infostring is a series of keys and values
            separated by '\'. Popular keys include "hostname" (the host name),
            "mapname" (the map currently played on this server).
            This infostring must contain the challenge string sent by the
            master in the "getinfo" that triggered this response (key name:
            "challenge"). "sv_maxclients" (the maximum number of clients
            allowed on the server; must not be 0), "protocol" (the protocol
            number) and "clients" (the current number of clients on the
            server) must also be present. Except for Q3A, "gamename" (the game
            name) is mandatory too.

    4) getservers:

        - description:

             A "getservers" message is sent to a master by a client who wants
             to get a list of servers.

        - samples:

            "\xFF\xFF\xFF\xFFgetservers 67 empty full"   (Q3A)
            "\xFF\xFF\xFF\xFFgetservers Nexuiz 3"        (DP running Nexuiz)
            "\xFF\xFF\xFF\xFFgetservers qfusion 39 full" (QFusion)

        - syntax:

            The message must contain a protocol version, and optionally "empty"
            and/or "full" depending on whether or not the client also wants to
            get empty or full servers. Except for Q3A, the client has to specify
            its game name, right before the protocol number.

    5) getserversResponse:

        - description:

            A "getserversResponse" message contains a list of servers requested
            by a client.

        - sample:

            "\xFF\xFF\xFF\xFFgetserversResponse\\[...]\\EOT\0\0\0"

        - syntax:

             The list of servers is composed of IPv4 addresses and ports. Each
             server is stored on 4 bytes for the IP address and 2 bytes for the
             port number, and a '\' to separate it from the next server. The
             list ends with the 6-byte string "EOT\0\0\0'. All numbers are
             big-endian oriented (most significant bytes first). For instance,
             a server hosted at address 1.2.3.4 on port 2048 will be sent as:
             "\x01\x02\x03\x04\x08\x00".


* BEHAVIOUR:

The way dpmaster behaves when talking to clients and servers is largely based
on one important idea: authenticated "infoResponse" messages are the only
messages we can reasonably trust.

When dpmaster receives an "heartbeat" message from a server, it will reply with
a "getinfo" and register this server for a couple of seconds. If it hasn't sent
back an "infoResponse" containing a valid challenge string by this time,
dpmaster forgets it. Further "heartbeat" messages can't prolong this time,
and the server IP address won't be transmitted to any client during that period
of time.

When dpmaster receives a valid "infoResponse" from a server, it associates a new
timeout value to it (15 min). Only another valid "infoResponse" from this very
server will be able to refresh this timeout value. Its IP address will be
transmitted to the appropriate clients, until it timeouts. Then, dpmaster
forgets it.

You may have noticed that this behaviour doesn't take into account the fact
that some servers send 2 "heartbeat" messages when closing. I deliberately
choose to keep the behaviour as simple and predictible as possible, hopefully
making it free from any major abuse.


--
Mathieu Olivier
molivier, at users.sourceforge.net
