The K2 client-server communication protocol is lightweight yet robust. It is also fault tolerant, and supports your configured license Policies with the greatest possible transparency to end users. UDP port 19283 is opened on the KeyServer host in order to receive client connections. As a KeyServer administrator, there is generally no need to understand the details but you may be interested in some specific implications for offline and online management of the various license policy types.
Here we will describe the protocol in a bit more detail, for those who are curious. We will focus on how intermittent network connectivity affects control and tracking of KeyServer managed products. In particular this applies to laptop computers used on and off network.
Normal Communication
As part of the user login sequence, the K2 client, KeyAccess, establishes a session with the KeyServer. KeyServer sets a timer, and tells the client to expect a “tickle” within 10 minutes. Then before the 10 minute expiration, KeyServer sends a small tickle packet. As soon as KeyServer receives the acknowledge packet, the session timer is again reset. This tickle/acknowledge pair happens ongoing until the client closes the session or connectivity is for some reason lost as described below.
Missed Tickles
Now let’s assume something gets in the way. This can be a network outage, a client crash, a server crash, a UDP port timeout, or simply a laptop being closed during an active session.
At around 7 minutes the KeyServer sends the client a tickle as usual, but let’s assume it gets no answer. It then tickles repeatedly at intervals of around one minute. This means a short network outage is tolerated because one of the later tickles will be acknowledged and the session will be maintained. But if the client does not receive any tickle within the promised 10 minutes for any reason (for example, a UDP port timeout on the client or router), it sends a “saveMe” packet to the KeyServer. Assuming KeyServer is reachable, the saveMe packet will cause KeyServer to reset the tickle timer to 10 minutes just like a tickle acknowledge.
Lost Sessions
If the KeyServer hears nothing from the client for 15 minutes – no tickle acknowledge and no saveMe packet – KeyServer will consider the session lost and close it out. This includes marking all controlled program usage as having ended. Of course, in the rare case that sessions are “closed out” due to a crash of the KeyServer host or KeyServer process, marking program usage records appropriately has to occur when KeyServer next starts up – but the record keeping cleanup is similar. In either case, if KeyServer receives a saveMe request that does not match any active session, a new session is created. Any currently active usage for managed software will be matched to prior records and the tracking information will be updated as appropriate.
If the saveMe request fails to get an acknowledge from KeyServer of course the new session described above will not be created – then, if any shadows have been set up, the client may send a similar saveMe to a KeyShadow. If all saveMe attempts fail, the client will commence local recording of program usage. This local usage data will be sent to the KeyServer at next connection, so any “offline” usage will eventually be available for subsequent reporting. Hence there is no real need for most sites to install a KeyShadow (unless the older “fully keyed” option is still being used for management of some program executables).
Other considerations
The transparent user experience described above assumes that the “Detachable” option checkbox is on for the management Policy – this is the default setting. However, in order to strictly enforce a Concurrent license metric, rather than relying on usage reports alone to document the concurrent maximums, you should turn the “Detachable” checkbox off in the Policy. Then whenever a computer loses its session (and cannot get support from a shadow), KeyAccess will request the managed programs to quit. Turning the detachable option off for a Site policy will likewise result in quit requests when the managed programs go offline – this may or may not be the desired behaviour depending on the details of your “site” license.
Note: as an alternative to denying offline use for a Concurrent license policy or merely reporting on use, it may sometimes be appropriate to change a Concurrent license policy to use the less efficient “Lease” metric. Then the concurrent use limit will be strictly enforced while still tolerating a well defined period of offline use. Programs managed by Leased or Node Locked policies are not affected by the detachable checkbox – they will run with or without a session as long as the license remains allocated.
Examples
Here are a few typical cases:
Laptop is shut and reopened again on-network
When the client is re-opened, KeyAccess sends a saveMe to the KeyServer. If the session on the KeyServer is still active, the session is rejoined. If the session has been torn down (e.g. the laptop has been closed for more than 15 minutes) the client is given a new session, and software use counts are rectified. When a desktop or laptop computer wakes from sleep mode with managed applications running the same thing happens.
Laptop is shut and reopened again off-network
If the computer is re-opened with no internet connection or on a network where the route to KeyServer is blocked by firewalls, then the KeyAccess saveMe will not reach KeyServer.
- Any program in use via a Node locked or Leased policy will continue to run, and it can be launched offline.
- Any program in use via a Site or Concurrent policy with the “Detachable” option set on will continue to run, and it can be launched offline.
- Any program in use via a Site or Concurrent policy with the “Detachable” option off will be asked to quit and launch attempts will fail offline.
- Usage data for managed programs will be recorded offline and uploaded to KeyServer as soon as a new session is obtained when next online.
Laptop moves among different networks or the network interface changes from wired to wireless
The retry protocol for saveMe and tickle packets is designed to tolerate the typical short interruptions due to these kinds of network reconfigurations without advancing to the more complicated “fail-safe” behaviours described above. Assuming that there is a route for UPD 19283 on one interface or another, an active KeyServer session will be maintained without interruption.
There are a number of other subtleties and sub-cases that are outside the scope of this post. Please feel free to contact us with any questions you may have.
Subscribe
Hi Michael,
Useful information in the blog. I have a question.
Assume there is a firewall between the K2 client and the KeyServer and the firewall is configured only to allow traffic initiated from the clients. KeyServer traffic to tickle the K2 clients will not be permited by the firewall..
Will the KeyServer be able to manage the K2 clients?
This is a common scenario at large IT service providers in India. They serve multiple customers, each with their own isolated network protected by firewalls.
Thanks,
Harsha Reddy
In short: yes, the KeyServer protocol is designed to tolerate the typical firewall configuration that you are describing.
You are right that traffic “initiated” from KeyServer will be blocked by standard firewall configurations. The firewall will of course need to be configured to allow incoming connections to the KeyServer but all conversations must be initiated by the client from a random port. KeyServer uses our registered port 19283 – see https://www.sassafras.com/hrl/7.1/firewall.html for details on how to set up firewalls.
If the connection were TCP, the firewall would typically allow all packets sent in both directions for the duration of the session. We use UDP, though, because of the lower overhead required on the server. DNS is another example of a server based on UDP – DNS uses port 53. UDP is a session-less protocol so most firewalls enforce an idle timeout on UDP conversations that is on the order of 1-3 minutes by default. If there have been no packets sent in either direction for a period exceeding the timeout, then subsequent packets from the server will be blocked until a new packet from the client is seen – a packet from the client will re-open the connection and reset the idle timeout counter.
You are correct that often a “tickle” from the KeyServer to the client will be sent after a firewall’s UDP idle timeout has expired – the tickle packet won’t be delivered. But when the client notices it hasn’t received an expected tickle, it will send a saveMe packet to the KeyServer. This packet, coming from the client, will be allowed by the firewall. The connection will be re-established, and the idle timeout counter will be reset. Just like the example of a DNS server, there are no unusual firewall issues to consider. Traffic incoming to the service must be allowed on the registered port – for KeyServer, that simply means allowing traffic to the KeyServer host computer on UDP port 19283.