You are Here:
Components and connections

Author (Read 7911 times)

Components and connections
« on: September 07, 2012, 06:11:19 pm »


  • Administrator
  • Sr. Member
  • *****
  • 270
  • Karma: 8
    • View Profile
Here's a brief overview of components belonging to the OpenTTD network and how they are connected (click the picture to get a bigger version):

Now I explain each component:

Main machine: "BOxxOR"
This is the main server which also was everything we had until short time ago, it is called "BOxxOR". It's a machine hosted in a data center by Hetzner in Falkenstein, Germany. The machine is running on Debian Linux. This is also the master server, holding the central database, web server with website and forum and the IRC server. It is currently running 10 servers without an additional character tag (compared "x" tag for the other server).

OpenTTD servers on this machine are available via both IPv4 and IPv6, for IPv4 it has the DNS name
Players in Europe will in most cases have a better connection to this one than to "supervds".

Additional Machine: "SuperVDS" - the "x" servers

This is an additional server which was added later. It is kindly provided by SuperVDS Hosting. It is hosted in a data center by Dacentec in North America. The machine is running on Debian Linux. It is connected to the main server via VPN. It is currently running 4 "x" servers.

OpenTTD servers on this machine are currently only available via IPv4, the DNS name is
Players on the American continent will in most cases have a better connection to this one than to "BOxxOR".

The player sees the end of this whole network. Being a member of the Community he can enter our IRC and chat with us, as well as see the chat of all servers, which is mirrored to IRC. He can also use the website, which includes the forum. And last but not least he connects to one of our OpenTTD servers to play, while he doesn't have to care about the fact that for the "x" servers he is playing on a different machine when choosing one from the OpenTTD server list.

xShunter is the software that controls the OpenTTD server from the outside to add extra features to the game. You can read more about xShunter here. Basically all chat commands beginning with an exclamation mark (so called triggers, e.g. "!help") are provided by it, OpenTTD doesn't support triggers by default. Also things like the goal system, score system, admin request system, clone checking, achievements and company protection are all provided by xShunter plug-ins.
For the score system a MySQL plug-in is used to read and write player scores from/to a MySQL database.

Each OpenTTD server has an xShunter instance that controls it, so for 8 OpenTTD servers it's 8 xShunter instances. To connect to the OpenTTD server it uses various interfaces (and other channels that are not directly interfaces but are still used to get data from OpenTTD) - simply because each of these interfaces provides different information, so to get the maximum amount of control OpenTTD all of them need to be used.

Client interface:
This is the interface you know as a player. Your OpenTTD client uses it to connect to a server and show you what is happening in the game, as well as report your actions to the server so it can be distributed for all other players. This interface contains every single action any player on the server performs as well as complete information about the map. It is TCP based, which is unusual for an online game but still makes sense for OpenTTD.
xShunter is not utilizing it basically for the same reasons that were mentioned for patching: it would need to be kept updated with every new release of OpenTTD.

UDP interface:
This is an interface to get very generic status information and is used by both the OpenTTD client and xShunter. It contains basic game specs like the map size, current game year, current players/max players, current companies/max companies, current spectators/max spectators, all sent within a single UDP packet. OpenTTD uses it to show this information in the server list window while xShunter needs it to learn about these specs. (e.g. otherwise the autoclean plug-in wouldn't know when the last company slot was taken.

Console interface:
This was probably not meant to be used as an interface for another program, yet it is possible and e.g. utilized by the TCL script autopilot. xShunter uses it through xConsole (see below). Since the admin interface was introduced its importance for xShunter has significantly decreased, xShunter now merely uses it to learn about the exact time when it can connect to the admin interface after OpenTTD was started (as opposed to blindly try to keep reconnecting) or to see when the game was restarted (which at least for the first game start can happen before xShunter managed to connect to the admin interface already).
It is also used as fallback when the admin interface connection is lost (xShunter automatically switches to using console commands then).

Admin interface:
This is one of the newer features in OpenTTD. This interface was added to provide external applications with a clean way of interacting with the server. As the "admin" term indicates it was rather meant to be used for administrative tasks and not to control details of the gameplay, however, it also provides detailed company and player information which xShunter depends on very much. Additionally it provides all game commands sent by players and while it cannot be used to get a full picture of what is happening in the game (the documentation even says it is only meant for logging purposes) xShunter does a lot more with it, e.g. this is how the Achievements plug-in knows what players did to give them achievements for.

Process control:
This is only done indirectly by xShunter, as it instructs xConsole about how to control the OpenTTD server process (see xConsole section below). Basically the process can be started (with variable run arguments), stopped in a clean way, killed the hard way or the running status of it is checked.
This is e.g. used to do scheduled restarts of OpenTTD (once or in regular intervals or only when server is empty for X hours).

This is not an interface on its own, hence also not shown in the above diagram. However, it can get information from the current OpenTTD game on a more detailed level than most of the other interfaces, e.g. it can get information about vehicles in the game or limited information regarding the map (e.g. check what is currently on a specific tile). Furthermore it can be used to force a company to execute commands.
Like OpenTTD itself a GameScript running on the OpenTTD server can communicate with external applications through the admin interface. Therefore xShunter comes with a GameScript that acts as an extended arm of xShunter within OpenTTD, listening for commands coming in from xShunter through the admin interface and executing them within OpenTTD. In the other direction the script is intercepting in-game events and forwarding them to xShunter through admin interface.

OpenTTD config file:
Some information xShunter needs it reads from the OpenTTD configuration file, e.g. connection data for the admin interface (although that can also be overriden in xShunter configuration) or the ban list (because it's more reliable to read from there than parsing it from the "banlist" console command).

This program is part of the xShunter suite but in theory is not limited to be used with only OpenTTD or only xShunter. What it does is control a program and attach to its console on one side and provide that console to external programs via a TCP interface on the other side (for both reading from it and writing to it).

In our case it acts as abstraction layer between the console of the OpenTTD server and xShunter. In earlier versions xConsole didn't exist and xShunter was controlling the OpenTTD server and its console directly. The problem was that it is only possible to attach to the console of a program by starting this program - you cannot attach to the console of an already running program (at least not without special tricks like running as a debugger registered in the operating system). As a result if xShunter crashed the OpenTTD game could not be controlled again, it had to be restarted to be able to run with xShunter again, causing an outage of the OpenTTD server (and even when saving and restoring the current game all company passwords are lost). Now crashes aren't happening that frequently, but the same applies to installation of updates for xShunter, those DO happen frequently.

xConsole brought the solution, as its functionality is held so simple that it's both unlikely to crash and only very rarely needs updates. Additionally to being a proxy it starts the OpenTTD server when instructed to do so by xShunter, but can also stop it or even kill the process if it is hung. Now xShunter can crash or get restarted for an update installation without affecting the running game (except that the xShunter features aren't available for some seconds during the update). Therefore the invention of xConsole was a great improvement to stability and availability of the n-ice servers while still maintaining the high frequency of updates to bring new features in.

This is our community website you see on

The forum belongs to the website, both running on the same Apache webserver, but technically it's a separate piece of software (Simple Machines) with its own MySQL database. The forum account system was connected with the n-ice account system so players don't have to register and login twice, which means the n-ice database for the website is a different one than the forum database. The website database is the same database that xShunter uses, which is why scores written by xShunter can be seen on the website without extra synchronization and why accounts created on the website and tokens generated there can be used to login in-game.

The website itself is written in PHP, code and design are custom and were created from scratch.

IRC server
The IRC server is run using the InspIRCd IRC daemon and Atheme for IRC services. The services are only running on server machine 1, but server machine 2 is running an leaf IRC daemon too.
The IRC servers can be reached through on port 6668, which is a DNS round-robin for both the hub server on server machine 1 and the leaf server on server machine 2, so we got some redundancy.

The webchat also connects to this IRC, so even players without an IRC client can join the chat by using the website.

Furthermore the xShunter instances also connect to IRC to be able to mirror the chat there. They can also receive commands from IRC, just like from in-game.

OpenTTD servers
These are the actual OpenTTD servers, the part we are all here for  ;)
What is worth noting is that we are running vanilla servers - we're taking the binary version from the official OpenTTD website, no compiling, no patching. While patching is the most powerful method of adding custom features to the OpenTTD servers or modifying existing features it also has the worst maintainability. For each official version that is released the patches have to be reapplied and OpenTTD recompiled afterwards - but the bad part is that also often patches become incompatible and have to be changed to fit the new code. If you use patches written by someone else you always depend on that person to provide a new version of his patch after a new OpenTTD release. If the person quits his work on the patch you're lost, if no new maintainer is found.
Alternatively you can program and maintain the patches yourself or have developers on your admin team who could do it. But still, in worst case it means that you need to program every time a new OpenTTD version is released only so your patches fit again. This means effort is necessary for each release, effort only to keep the status quo where it should be used to implement new features, whereas xShunter can in almost every case run with new OpenTTD versions without extra work.
This was the reason why xShunter was invented in the first place, even when the downside is that some things are technically impossible to do from an external application and probably will always be.

MySQL database
We're using a standard MySQL database server - it is running two databases, one shared by xShunter and the website and another one for the forum. So beside forum data it contains all the highscores, player profiles, achievements and everything else that is related to players and you can see on the website or through xShunter.

VPN tunnel
While we just connected the IRC daemon on the SuperVDS machine directly for the server link databases should never be accessible from the Internet, and of course our database isn't either. However, we needed to connect the xShunter instances on server machine 2 to the database of server 1, so the "x" servers can also be linked to the n-ice community with player's accounts and scores.
So a permanent VPN tunnel using OpenVPN was established between the two machines and the MySQL connections are routed through it.
« Last Edit: January 13, 2017, 08:03:03 pm by Chucky »