Server Addresses (API)
This page describes how KAG server addressing works, with an emphasis on how the API handles addresses.
A KAG server has two configuration variables for binding to specific IP addresses: sv_ip and sv_ipv6. By default these are 0 or `` (empty). For most servers, these are left as the defaults. The main situation in which an address is bound by configuration is when multiple servers are hosted and there is the desire to have each separate server use the same port on multiple addresses. In this case, server A will bind address A, ands server B will bind address B.
If a server has IPv4 and IPv6 Internet connectivity and the owner configures only sv_ip or sv_ipv6, the server will refuse to try to contact the API for registration with the server list (e.g. it overrides sv_register and forces it to 0). Upon startup this is detected and a warning is printed to the console (and logs). This is done to prevent inconsistent behavior with IPv4 and IPv6, especially with how servers show up in the API. If this was permitted to happen, two servers running on the same physical machine but only using sv_ip (while IPv6 is also functioning on the server), the servers could be confused by the API as they make calls over IPv6 and claim to be on the same port.
Servers are identified by the API as IP address and port combinations which are used to look up another identifier used only internally by the API (at some point this may be returned to the KAG server in status messages for diagnostic purposes). The API server determines whether the source address of the HTTP request is authorized to update the server specified in the resource URI. If it is, the call proceeds. If it is not, the call is declined with HTTP status 403 with instructions (machine-readable JSON) to call back from another address which is already authorized for this server. The server will call back from the other authorized address and in doing so will register the initial address as authorized. In many cases this is not possible because it means an address has changed (is no longer available to be used by the KAG server for calling the API)and the server will create a new record on the API.
The KAG server makes a number of decisions to try and preserve the server identity across address changes, however these typically only work on dual-stack servers or servers having multiple IPv4 or IPv6 addresses. Some of this logic is still being changed as the codebase matures.
Upon startup the KAG server makes a few HTTP calls to http://v4-whoami.kag2d.com , http://v6-whoami.kag2d.com , and http://ds-whoami.kag2d.com to determine its external IPv4 and IPv6 addresses, mapping of local to external addresses (e.g. NAT), and determining its outbound address family preference (IPv4 vs IPv6). These are used to determine how calls are made to the API later and to help ensure consistent source addresses are used.
In general these attempts to preserve server identity are best effort. Server owners can help this by attempting to run KAG servers on physical machines which have at most one IPv4 and IPv6 address on their interface containing the default IPv4 and IPv6 routes. In this situation, the server identity will never be lost over time and server restarts.
