
Dpmaster, a master server for DarkPlaces, Quake III Arena and QFusion
---------------------------------------------------------------------
                         Technical information
                         ---------------------


* COMPILING DPMASTER:

Dpmaster is being developed on PC hardware, on Linux and Windows, using GCC and
MS Visual C++ 6 respectively. If you use one of these compiler, you should be
able to compile dpmaster without any problem.
Dpmaster is also regularly compiled on OpenBSD and NetBSD systems, and on Win32
systems using MinGW32 (GCC for Win32). Occasionally, dpmaster 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 potential issues regarding endianess and
CPU word size, dpmaster has never be compiled or run on non-PC hardware. Please
report us any (un)successful attempt on such a system.

To compile dpmaster using GCC on a UNIX system, just type "make". 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"
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 'F9' to compile the project. You'll find the executable
file in the "Release" subdirectory.


* PROTOCOL:

Dpmaster uses a protocol that is heavily inspired from Quake III Arena 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.

    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 its state
            changes (new map, new player, shutdown, ...), 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 the list of active
            servers.

        - samples:

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

        - syntax:

            A protocol string is required after the type name. A line feed
            (character 10, '\n') close the message. Please use "DarkPlaces" as
            the protocol string. Dpmaster only checks this string for debugging
            purpose at this time, but it may change. You're warned.

    2) getinfo:

        - description:

            This message is sent by a master to a server, usually in response
            to a "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 '\'. 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), "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 prolongate 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
