docs/admin_network.md

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