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.
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.
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.
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).
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.
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.
Author: Michael Maddalena
Having tested and supported KeyServer since as far back as version 3.2, Michael has been working with some long-term customers for decades now, but is always happy to help anyone (Old Hands, New or Recent customers, or Prospects) understand and get the most out of our software. He also handles any questions related to bees or goats.