summaryrefslogtreecommitdiff
path: root/docs/admin_network.txt
diff options
context:
space:
mode:
Diffstat (limited to 'docs/admin_network.txt')
-rw-r--r--docs/admin_network.txt205
1 files changed, 205 insertions, 0 deletions
diff --git a/docs/admin_network.txt b/docs/admin_network.txt
new file mode 100644
index 000000000..a450af026
--- /dev/null
+++ b/docs/admin_network.txt
@@ -0,0 +1,205 @@
+Admin Network
+
+ Preface
+1. Joining the network
+2. Asking for updates
+3. Polling manually
+4. Sending rcon commands
+5. Sending chat
+6. Receiving chat
+7. Disconnecting
+8. Certain packet information
+
+
+ Preface
+----------
+
+ The admin network provides a dedicated network protocol designed for other
+ applications to communicate with OpenTTD. Connected applications can execute
+ console commands remotely (rcon commands) with no further authentication.
+ Furthermore information about clients and companies can be provided.
+
+ Admin applications remain connected when starting a new game or loading a saved
+ game in contrast to normal OpenTTD clients that get disconnected.
+
+ This document describes the admin network and its protocol.
+
+ Please refer to the mentioned enums in src/network/core/tcp_admin.h
+
+ Please also note that further improvements to the admin protocol can mean that
+ more packet types will be sent by the server. For forward compatibility it is
+ therefore wise to ignore unknown packets. Future improvements might also add
+ additional data to packets. This data should be ignored. Data will never be
+ removed from packets in later versions, except the possibility that complete
+ packets are dropped in favour of a new packet.
+ This though will be reflected in the protocol version as announced in the
+ ADMIN_PACKET_SERVER_PROTOCOL in section 1.
+
+
+1. Joining the network
+----------------------
+
+ Create a TCP connection to the server on port 3977. The application is
+ expected to authenticate within 10 seconds.
+
+ To authenticate send a ADMIN_PACKET_ADMIN_JOIN packet.
+
+ The server will reply with ADMIN_PACKET_SERVER_PROTOCOL followed directly by
+ ADMIN_PACKET_SERVER_WELCOME.
+
+ ADMIN_PACKET_SERVER_PROTOCOL contains details about the protocol version.
+ It is the job of your application to check this number and decide whether
+ it will remain connected or not.
+ Furthermore, this packet holds details on every AdminUpdateType and the
+ supported AdminFrequencyTypes (bitwise representation).
+
+ ADMIN_PACKET_SERVER_WELCOME contains details on the server and the map,
+ e.g. if the server is dedicated, its NetworkLanguage, size of the Map, etc.
+
+ Once you have received ADMIN_PACKET_SERVER_WELCOME you are connected and
+ authorized to do your thing.
+ The server will not provide any game related updates unless you ask for them.
+ There are four packets the serve will none the less send, if applicable:
+ - ADMIN_PACKET_SERVER_ERROR
+ - ADMIN_PACKET_SERVER_WELCOME
+ - ADMIN_PACKET_SERVER_NEWGAME
+ - ADMIN_PACKET_SERVER_SHUTDOWN
+
+ However, ADMIN_PACKET_SERVER_WELCOME only after a ADMIN_PACKET_SERVER_NEWGAME
+
+
+2. Asking for updates
+---------------------
+
+ Asking for updates is done with ADMIN_PACKET_ADMIN_UPDATE_FREQUENCY.
+ With this packet you define which update you wish to receive at which
+ frequency.
+
+ Note: not every update type supports every frequency. If in doubt, you can
+ verify against the data received in ADMIN_PACKET_SERVER_PROTOCOL.
+
+ The server will not confirm your registered update. However, asking for an
+ invalid AdminUpdateType or a not supported AdminUpdateFrequency you will be
+ disconnected from the server with NETWORK_ERROR_ILLEGAL_PACKET.
+
+ Additional debug information can be found with a debug level of net=3.
+
+ ADMIN_UPDATE_DATE results in the server sending:
+ - ADMIN_PACKET_SERVER_DATE
+
+ ADMIN_UPDATE_CLIENT_INFO results in the server sending:
+ - ADMIN_PACKET_SERVER_CLIENT_JOIN
+ - ADMIN_PACKET_SERVER_CLIENT_INFO
+ - ADMIN_PACKET_SERVER_CLIENT_UPDATE
+ - ADMIN_PACKET_SERVER_CLIENT_QUIT
+ - ADMIN_PACKET_SERVER_CLIENT_ERROR
+
+ ADMIN_UPDATE_COMPANY_INFO results in the server sending:
+ - ADMIN_PACKET_SERVER_COMPANY_NEW
+ - ADMIN_PACKET_SERVER_COMPANY_INFO
+ - ADMIN_PACKET_SERVER_COMPANY_UPDATE
+ - ADMIN_PACKET_SERVER_COMPANY_REMOVE
+
+ ADMIN_UPDATE_COMPANY_ECONOMY results in the server sending:
+ - ADMIN_PACKET_SERVER_COMPANY_ECONOMY
+
+ ADMIN_UPDATE_COMPANY_STATS results in the server sending:
+ - ADMIN_PACKET_SERVER_COMPANY_STATS
+
+ ADMIN_UPDATE_CHAT results in the server sending:
+ - ADMIN_PACKET_SERVER_CHAT
+
+ ADMIN_UPDATE_CONSOLE results in the server sending:
+ - ADMIN_PACKET_SERVER_CONSOLE
+
+
+3. Polling manually
+-------------------
+
+ Certain AdminUpdateTypes can also be polled:
+ - ADMIN_UPDATE_DATE
+ - ADMIN_UPDATE_CLIENT_INFO
+ - ADMIN_UPDATE_COMPANY_INFO
+ - ADMIN_UPDATE_COMPANY_ECONOMY
+ - ADMIN_UPDATE_COMPANY_STATS
+
+ ADMIN_UPDATE_CLIENT_INFO and ADMIN_UPDATE_COMPANY_INFO accept an additional
+ parameter. This parameter is used to specify a certain client or company.
+ Setting this parameter to UINT32_MAX (0xFFFFFFFF) will tell the server you
+ want to receive updates for all clients or companies.
+
+ Not supported AdminUpdateType in the poll will result in the server
+ disconnecting the application with NETWORK_ERROR_ILLEGAL_PACKET.
+
+ Additional debug information can be found with a debug level of net=3.
+
+
+4. Sending rcon commands
+------------------------
+
+ Rcon runs separate from the ADMIN_UPDATE_CONSOLE AdminUpdateType. Requesting
+ the execution of a remote console command is done with the packet
+ ADMIN_PACKET_ADMIN_RCON.
+
+ Note: No additional authentication is required for rcon commands.
+
+ The server will reply with a ADMIN_PACIKET_SERVER_RCON packet. Applications
+ will not receive the answer twice if they ave asked for the AdminUpdateType
+ ADMIN_UPDATE_CONSOLE, as the result is not printed on the servers console
+ (just like clients rcon commands).
+
+ Furthermore, sending a 'say' command (or any similar command) will not
+ be sent back into the admin network.
+ Chat from the server itself will only be sent to the admin network when it
+ was not sent from the admin network.
+
+
+5. Sending Chat
+---------------
+
+ Sending a ADMIN_PACKET_ADMIN_CHAT results in chat originating from the server.
+
+ Currently four types of chat are supported:
+ - NETWORK_ACTION_CHAT
+ - NETWORK_ACTION_CHAT_CLIENT
+ - NETWORK_ACTION_CHAT_COMPANY
+ - NETWORK_ACTION_SERVER_MESSAGE
+
+ NETWORK_ACTION_SERVER_MESSAGE can be sent to a single client or company
+ using the respective DestType and ID.
+ This is a message prefixed with the 3 stars, e.g. *** foo has joined the game
+
+
+6. Receiving chat
+-----------------
+
+ Register ADMIN_UPDATE_CHAT at ADMIN_FREQUENCY_AUTOMATIC to receive chat.
+ The application will be able to receive all chat the server can see.
+
+ The configuration option network.server_admin_chat specifies whether
+ private chat for to the server is distributed into the admin network.
+
+
+7. Disconnecting
+----------------
+
+ It is a kind thing to say good bye before leaving. Do this sending the
+ ADMIN_PACKET_ADMIN_QUIT packet.
+
+
+8. Certain packet information
+-----------------------------
+
+ All ADMIN_PACKET_SERVER_* packets have an enum value greater 100.
+
+ ADMIN_PACKET_SERVER_WELCOME
+ Either directly follows ADMIN_PACKET_SERVER_PROTOCOL or is send
+ after a new game has been started or a map loaded, i.e. also
+ after ADMIN_PACKET_SERVER_NEWGAME.
+
+ ADMIN_PACKET_SERVER_CLIENT_JOIN and ADMIN_PACKET_SERVER_COMPANY_NEW
+ These packets directly follow their respective INFO packets. If you receive
+ a CLIENT_JOIN / COMPANY_NEW packet without having received the INFO packet
+ it may be a good idea to POLL for the specific ID.
+
+