docs/admin_network.txt

   1 OpenTTD's admin network
   2 Last updated:    2011-01-20
   3 ------------------------------------------------------------------------
   4
   5
   6 Table of contents
   7 -----------------
   8 1.0) Preface
   9 2.0) Joining the network
  10 3.0) Asking for updates
  11  * 3.1) Polling manually
  12 4.0) Sending rcon commands
  13 5.0) Sending chat
  14  * 5.1) Receiving chat
  15 6.0) Disconnecting
  16 7.0) Certain packet information
  17
  18
  19 1.0) Preface
  20 ---- -------
  21   The admin network provides a dedicated network protocol designed for other
  22   applications to communicate with OpenTTD. Connected applications can execute
  23   console commands remotely (rcon commands) with no further authentication.
  24   Furthermore information about clients and companies can be provided.
  25
  26   Admin applications remain connected when starting a new game or loading a saved
  27   game in contrast to normal OpenTTD clients that get disconnected.
  28
  29   This document describes the admin network and its protocol.
  30
  31   Please refer to the mentioned enums in src/network/core/tcp_admin.h
  32
  33   Please also note that further improvements to the admin protocol can mean that
  34   more packet types will be sent by the server. For forward compatibility it is
  35   therefore wise to ignore unknown packets. Future improvements might also add
  36   additional data to packets. This data should be ignored. Data will never be
  37   removed from packets in later versions, except the possibility that complete
  38   packets are dropped in favour of a new packet.
  39   This though will be reflected in the protocol version as announced in the
  40   ADMIN_PACKET_SERVER_PROTOCOL in section 2.0).
  41
  42   A reference implementation in Java for a client connecting to the admin interface
  43   can be found at: http://dev.openttdcoop.org/projects/joan
  44
  45
  46 2.0) Joining the network
  47 ---- -------------------
  48   Create a TCP connection to the server on port 3977. The application is
  49   expected to authenticate within 10 seconds.
  50
  51   To authenticate send a ADMIN_PACKET_ADMIN_JOIN packet.
  52
  53   The server will reply with ADMIN_PACKET_SERVER_PROTOCOL followed directly by
  54   ADMIN_PACKET_SERVER_WELCOME.
  55
  56   ADMIN_PACKET_SERVER_PROTOCOL contains details about the protocol version.
  57   It is the job of your application to check this number and decide whether
  58   it will remain connected or not.
  59   Furthermore, this packet holds details on every AdminUpdateType and the
  60   supported AdminFrequencyTypes (bitwise representation).
  61
  62   ADMIN_PACKET_SERVER_WELCOME contains details on the server and the map,
  63   e.g. if the server is dedicated, its NetworkLanguage, size of the Map, etc.
  64
  65   Once you have received ADMIN_PACKET_SERVER_WELCOME you are connected and
  66   authorized to do your thing.
  67   The server will not provide any game related updates unless you ask for them.
  68   There are four packets the server will none the less send, if applicable:
  69     - ADMIN_PACKET_SERVER_ERROR
  70     - ADMIN_PACKET_SERVER_WELCOME
  71     - ADMIN_PACKET_SERVER_NEWGAME
  72     - ADMIN_PACKET_SERVER_SHUTDOWN
  73
  74   However, ADMIN_PACKET_SERVER_WELCOME only after a ADMIN_PACKET_SERVER_NEWGAME
  75
  76
  77 3.0) Asking for updates
  78 ---- ------------------
  79   Asking for updates is done with ADMIN_PACKET_ADMIN_UPDATE_FREQUENCY.
  80   With this packet you define which update you wish to receive at which
  81   frequency.
  82
  83   Note: not every update type supports every frequency. If in doubt, you can
  84   verify against the data received in ADMIN_PACKET_SERVER_PROTOCOL.
  85
  86   The server will not confirm your registered update. However, asking for an
  87   invalid AdminUpdateType or a not supported AdminUpdateFrequency you will be
  88   disconnected from the server with NETWORK_ERROR_ILLEGAL_PACKET.
  89
  90   Additional debug information can be found with a debug level of net=3.
  91
  92   ADMIN_UPDATE_DATE results in the server sending:
  93     - ADMIN_PACKET_SERVER_DATE
  94
  95   ADMIN_UPDATE_CLIENT_INFO results in the server sending:
  96     - ADMIN_PACKET_SERVER_CLIENT_JOIN
  97     - ADMIN_PACKET_SERVER_CLIENT_INFO
  98     - ADMIN_PACKET_SERVER_CLIENT_UPDATE
  99     - ADMIN_PACKET_SERVER_CLIENT_QUIT
 100     - ADMIN_PACKET_SERVER_CLIENT_ERROR
 101
 102   ADMIN_UPDATE_COMPANY_INFO results in the server sending:
 103     - ADMIN_PACKET_SERVER_COMPANY_NEW
 104     - ADMIN_PACKET_SERVER_COMPANY_INFO
 105     - ADMIN_PACKET_SERVER_COMPANY_UPDATE
 106     - ADMIN_PACKET_SERVER_COMPANY_REMOVE
 107
 108   ADMIN_UPDATE_COMPANY_ECONOMY results in the server sending:
 109     - ADMIN_PACKET_SERVER_COMPANY_ECONOMY
 110
 111   ADMIN_UPDATE_COMPANY_STATS results in the server sending:
 112     - ADMIN_PACKET_SERVER_COMPANY_STATS
 113
 114   ADMIN_UPDATE_CHAT results in the server sending:
 115     - ADMIN_PACKET_SERVER_CHAT
 116
 117   ADMIN_UPDATE_CONSOLE results in the server sending:
 118     - ADMIN_PACKET_SERVER_CONSOLE
 119
 120
 121   ADMIN_UPDATE_CMD_LOGGING results in the server sending:
 122     - ADMIN_PACKET_SERVER_CMD_LOGGING
 123
 124 3.1) Polling manually
 125 ---- ----------------
 126   Certain AdminUpdateTypes can also be polled:
 127     - ADMIN_UPDATE_DATE
 128     - ADMIN_UPDATE_CLIENT_INFO
 129     - ADMIN_UPDATE_COMPANY_INFO
 130     - ADMIN_UPDATE_COMPANY_ECONOMY
 131     - ADMIN_UPDATE_COMPANY_STATS
 132     - ADMIN_UPDATE_CMD_NAMES
 133
 134   ADMIN_UPDATE_CLIENT_INFO and ADMIN_UPDATE_COMPANY_INFO accept an additional
 135   parameter. This parameter is used to specify a certain client or company.
 136   Setting this parameter to UINT32_MAX (0xFFFFFFFF) will tell the server you
 137   want to receive updates for all clients or companies.
 138
 139   Not supported AdminUpdateType in the poll will result in the server
 140   disconnecting the application with NETWORK_ERROR_ILLEGAL_PACKET.
 141
 142   Additional debug information can be found with a debug level of net=3.
 143
 144
 145 4.0) Sending rcon commands
 146 ---- ---------------------
 147   Rcon runs separate from the ADMIN_UPDATE_CONSOLE AdminUpdateType. Requesting
 148   the execution of a remote console command is done with the packet
 149   ADMIN_PACKET_ADMIN_RCON.
 150
 151   Note: No additional authentication is required for rcon commands.
 152
 153   The server will reply with one or more ADMIN_PACKET_SERVER_RCON packets.
 154   Finally an ADMIN_PACKET_ADMIN_RCON_END packet will be sent. Applications
 155   will not receive the answer twice if they have asked for the AdminUpdateType
 156   ADMIN_UPDATE_CONSOLE, as the result is not printed on the servers console
 157   (just like clients rcon commands).
 158
 159   Furthermore, sending a 'say' command (or any similar command) will not
 160   be sent back into the admin network.
 161   Chat from the server itself will only be sent to the admin network when it
 162   was not sent from the admin network.
 163
 164   Note that when content is queried or updated via rcon, the processing
 165   happens asynchronously. But the ADMIN_PACKET_ADMIN_RCON_END packet is sent
 166   already right after the content is requested as there's no immediate output.
 167   Thus other packages and the output of content rcon command may be sent at
 168   an arbitrary later time, mixing into the output of other console activity,
 169   e.g. also of possible subsequent other rcon commands sent.
 170
 171
 172 5.0) Sending chat
 173 ---- ------------
 174   Sending a ADMIN_PACKET_ADMIN_CHAT results in chat originating from the server.
 175
 176   Currently four types of chat are supported:
 177     - NETWORK_ACTION_CHAT
 178     - NETWORK_ACTION_CHAT_CLIENT
 179     - NETWORK_ACTION_CHAT_COMPANY
 180     - NETWORK_ACTION_SERVER_MESSAGE
 181
 182   NETWORK_ACTION_SERVER_MESSAGE can be sent to a single client or company
 183   using the respective DestType and ID.
 184   This is a message prefixed with the 3 stars, e.g. *** foo has joined the game
 185
 186 5.1) Receiving chat
 187 ---- -------------
 188   Register ADMIN_UPDATE_CHAT at ADMIN_FREQUENCY_AUTOMATIC to receive chat.
 189   The application will be able to receive all chat the server can see.
 190
 191   The configuration option network.server_admin_chat specifies whether
 192   private chat for to the server is distributed into the admin network.
 193
 194
 195 6.0) Disconnecting
 196 ---- -------------
 197   It is a kind thing to say good bye before leaving. Do this by sending the
 198   ADMIN_PACKET_ADMIN_QUIT packet.
 199
 200
 201 7.0) Certain packet information
 202 ---- --------------------------
 203   All ADMIN_PACKET_SERVER_* packets have an enum value greater 100.
 204
 205   ADMIN_PACKET_SERVER_WELCOME
 206     Either directly follows ADMIN_PACKET_SERVER_PROTOCOL or is sent
 207     after a new game has been started or a map loaded, i.e. also
 208     after ADMIN_PACKET_SERVER_NEWGAME.
 209
 210   ADMIN_PACKET_SERVER_CLIENT_JOIN and ADMIN_PACKET_SERVER_COMPANY_NEW
 211     These packets directly follow their respective INFO packets. If you receive
 212     a CLIENT_JOIN / COMPANY_NEW packet without having received the INFO packet
 213     it may be a good idea to POLL for the specific ID.
 214
 215   ADMIN_PACKET_SERVER_CMD_NAMES and ADMIN_PACKET_SERVER_CMD_LOGGING
 216     Data provided with these packets is not stable and will not be
 217     treated as such. Do not rely on IDs or names to be constant
 218     across different versions / revisions of OpenTTD.
 219     Data provided in this packet is for logging purposes only.