docs/admin_network.md

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