Example FLR scenarios

The following example scenarios are provided to help explain the typical FLR runtime and licensing process:

Example 1. Runtime scenarios

A “heartbeat” communication between an NRE with a floating license and the FLR server is used to enforce the licensing limits for a particular license bundle.

The following examples use a “station” as the NRE application, but the behavior applies to any NRE instance using the FLR.

Consider the following example environment:

An FLR server has a single license pack with:
- name="station"
- limit="1" (only one station can get the license at a time).
There are two supervisor stations (“S1” and “S2”) configured to use the FLR to get a license.
S1 starts and acquires the "station" license from the FLR.
S2 is not running.
S1, running normally, sends periodic heartbeat messages to the FLR to maintain its possession of the license.

Given the above FLR environment state, consider the following possible scenarios:

Scenario 1: S2 starts

Since S1 has obtained the only license from the FLR, the S2 request is rejected and the station does not start. S2 provides an error message stating that it is unable to obtain a license.
Scenario 2: S1 stops normally

The NRE on S1 notifies the FLR that it is finished with the license, thus freeing up a license for another station to start. An authorized station can now acquire the single "station" license from the FLR server.
Scenario 3: The FLR server is shutdown or “killed”

The next heartbeat from S1 fails because of no response from the FLR server. S1 then goes into a retry state. There are two possible outcomes:
- The FLR comes back up before the retry period ends.
  
  In this case, the next heartbeat from S1 succeeds and S1 attempts to reacquire its license from the FLR. If S1 reacquires the license it continues running normally. If it fails to reacquire the license (for example, the license is no longer available), it shuts down.
- The FLR does not come up before the retry period ends.
  
  In this case, S1 will become unusable and shut down.
Scenario 4: FLR is restarted, then S2 is started

This scenario is similar to Scenario 3, except now a competition, or “race” condition is introduced. Since the FLR was restarted, it has lost all its state information (license counters, etc.). When it starts up it assumes all licenses are available to serve. There are two possible results:
- S1 heartbeat gets to the FLR before S2 attempts to get a license:
  
  In this case, S1 indicates to the FLR that it currently has the license. This causes the FLR to reduce the number of available licenses (to 0 in this case). When S2 attempts to get a license, it fails since there are no more licenses.
- S2 requests a license before the next S1 heartbeat goes to the FLR:
  
  In this case, S2 acquires the license since the FLR thinks it has one to serve. When S1 next sends a heartbeat to the FLR, the FLR rejects the request from the NRE and the NRE immediately goes into an unusable state.
Scenario 5: S1 is stopped ungracefully (killed), then S2 is started

In this scenario, S1 was “killed” and did not have a chance to release its license to the FLR. There is nothing the FLR can do about this since it does not actively ping every NRE it has served a license to. In this case, when S2 starts it does not get a license since the FLR shows that S1 is using it. The FLR maintains an internal timeout and expiration for the license it served to S1. After a predetermined amount of time it auto-releases the lock for that license if no heartbeat is received from S1.

In this case, if you do not want to wait for the timeout period to expire, you could restart the FLR. Restarting causes all licensed floating NREs to compete to reacquire a license on the next heartbeat. This introduces the “race” condition, similar to the situation in Scenario 4.

Example 2. Licensing scenarios

Scenario 1 – License a new FLR

Request a license from a licensing provider and provide the following information:
- The hostId of the platform that runs the FLR server application
- The port that the FLR should listen on
- The desired license pack configurations for the FLR to serve
The Niagara Licensing Server generates the following files for the FLR
- Node-locked license file for the FLR. This license has the FLR feature enabled in it. The FLR cannot start without this license.
- The signed license pack file (LPF) for that FLR. The FLR can run without an LPF file, but it does nothing in that case. It needs to be told to reload the LPF file if there is an update or error with that file.
Scenario 2 – Change the port for an FLR

The LPF file needs to be regenerated and sent to the customer. There are two mechanisms that prevent running two FLRs are the same host in this case.
- The LPF file has a fixed name, so the new one must overwrite the previous one.
- The FLR periodically scans the LPF file to make sure it hasn’t changed.
  
  If it detects a change, it stops serving licenses, and all proxy NREs eventually fail because the heartbeat is not getting a response.
When an FLR changes its port, all the client NREs that are configured for that FLR must be reconfigured to use the new port.
Scenario 4 – Change a license pack or feature set

The LPF file needs to be regenerated by the Niagara License Server and sent to the customer. The FLR can either be restarted or have the LPF file “reload”. If a reload is performed and the pack limit becomes smaller than the current value some NREs will be rejected and immediately fail.

If a feature set changes for a pack, you probably will want to reload the license on all client NREs that already have that pack leased. However, it is not guaranteed that applications in the running NRE will “see” the feature set change because many applications only check their features once, and cache whether it is available or not. In this case, the client application would need to restart in some cases and reacquire the license to see the new set of features