diff options
| -rw-r--r-- | docs/admin_network.txt | 205 |
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. + + |