License Roaming

In v14.1 Temporary Licenses were introduced, solving much the same use case, but in a more straightforward way. See Temporary Licenses for more information.

RLM has the ability to allow a floating license to roam to a system which will subsequently be disconnected from the network for a short period of time. The resulting license can be used for the number of days specified when the license was set to roam, and is checked back in automatically at the end of this time. In addition, the customer can return the roamed license back to the license pool early if this is desired. Roaming is generally done with a checkout of a single license. If you request multiple licenses in a single checkout call, see the Special Considerations with Roaming Licenses section below.

Note

Once the license is roamed to the disconnected system, by default the license will behave on that system as if it were a nodelocked, uncounted license. On the server system, one floating license will be assigned to the roamed system. The behavior of the roamed license on the disconnected system can be the same as a “single” license. In order to make the roamed licenses “single” licenses, make the following call in rlm_isv_config.c:

rlm_isv_cfg_set_roam_single(handle, 1);

In order to roam a license, an application performs a normal checkout with the RLM_ROAM environment variable set to a positive number (this number is the number of days which the license will roam). If successful, this checkout will create a roamed license which is valid for the specified number of days.

Note

If ISVNAME_ROAM is set (where ISVNAME is the ISV’s name in uppercase), it will be used in place of RLM_ROAM. In the remainder of this document, we will use the name RLM_ROAM to signify either RLM_ROAM or ISVNAME_ROAM.

If a subsequent checkout is performed with RLM_ROAM set to a positive number, the roam expiration date will be extended if required. The expiration date of the roam will not be truncated if the new value indicates an expiration sooner than the old expiration.

If you set RLM_ROAM to 0, then the client will use a roamed license if it is available, but if not, it will use a floating license.

Note

If you request both roaming and queueing, the queue request will be ignored. In other words, if both RLM_ROAM and RLM_QUEUE are set, RLM_QUEUE is ignored.

A roamed license can be returned to the license server by setting RLM_ROAM to -1. When the license is checked out with RLM_ROAM set to -1, a successful checkout removes the roam data on the client machine and informs the server that the license is no longer roaming.

Warning

In order for this to work, the license on the license server must be the same as it was when the roamed license was originally checked out. If the license is updated on the license server, the roamed license cannot be returned early, and must time out normally.

This is an important point – roamed licenses are specific to a particular license. If the license is replaced on the server side, the roamed license cannot be returned early – the roam can only time out in this situation. Roamed licenses are also version-specific – both license version and RLM version, so if your software is upgraded and either uses a newer version of RLM or requests a different version, the existing roamed license will not work.

RLM has the notion of the “oldest compatible version/revision” for roam file data. As long as the version and revision are greater than the oldest compatible version/revision stored in the roam file itself, the roam data will work on applications compiled with different RLM versions.

ISV control over license roaming

As an ISV, you control whether licenses are able to roam, and how long they can be checked-out in the disconnected state.

License Roaming is only available to systems that are able to check out an rlm_roam license issued by you. This license must be available at all times - when the initial product checkout is done as well as when operating in a disconnected fashion. In other words, you must issue an uncounted, node-locked rlm_roam license. This license can, of course, be node-locked to “ANY” hostid.

The characteristics of the rlm_roam license also restrict how roaming can be used. For example, if the rlm_roam license specifies platforms=x86_w, then only 32-bit Windows systems would be able to check out roamed licenses. If rlm_roam specifies max_roam=7, then roamed licenses could only be checked out for 7 days. You can apply the max_roam attribute to any product license as well, but max_roam on the rlm_roam license creates a maximum for all products, so you only need to specify it once if you want to set a global maximum. If you do this and wish to disable roaming on an individual license, set max_roam to-1 for that license. You can, of course, always set an individual license max_roam to a value lower than the value in the rlm_roam license.

In addition, you can specify the max_roam_count attribute to any license. max_roam_count specifies how many of that particular license can be roamed. So, for example, to disable roaming of a particular license, specify max_roam_count=0 on that license.

Note

The hold and min_checkout parameters of a license which is roaming will be ignored.

License roaming and servers locked to transient hostids

If a license server is locked to a transient hostid (usually a dongle), it is easy for the license administrator to move the server to another machine, which not only allows for extra licenses to be roamed, but also interferes with the returning of roamed licenses, if the server isn’t running on the same machine as when the license was roamed. Roaming is disabled if the server is locked to a transient hostid, and the application will receive an RLM_EL_NOROAM_TRANSIENT error.

If you want to enable roaming on servers with transient hostids, modify rlm_isv_config.c and set the 2nd parameter to the rlm_isv_cfg_set_enable_roam_transient() to 1.

Example rlm_roam license

The following rlm_roam license would allow anyone to roam any of your licenses for up to 14 days. You can apply max_roam to any individual license to override this 14-day default:

LICENSE isvname rlm_roam 1.0 permanent uncounted hostid=any max_roam=14 sig="xxx"

This license should always be available to the application which will be roaming. If you want to enable roaming for all your customers, a good way to do this is to sign the rlm_roam license and pass the signed license as the 3rd parameter to rlm_init(). If you only want to enable roaming for certain customers, then the license must always be available to the client in a local license file.

Once issued, the contents of the rlm_roam license, as well as the restrictions on the other product licenses will be in effect, but your customer controls roaming operation from that point on.

If you have issued an rlm_roam license and wish to disable roaming for a particular product license, set the max_roam attribute on the product license to -1. If you want an individual license to roam for only 5 days, set the max_roam on that license to 5. All other licenses will be able to roam for 14 days.

For a description of how roaming works from a license administrator perspective, see How to use Roaming Licenses.

Special Considerations with Roaming Licenses

Roaming licenses are attached to an exact license pool. This means that the licenses, once roamed, are associated with the exact LICENSE line on the server from which they were checked out. If that license is subsequently upgraded or replaced, the server will no longer have access to the roaming information. The roamed license on the client node will continue to be valid until it expires, and the server will return to its (newly upgraded) full complement of floating licenses. This also means that the server’s host name and port-number must remain unchanged during the time the license is roamed. If you change either the server name or port, the roamed license cannot be returned early.

You should note that this means that a license which is roaming at the time the licenses are upgraded on the server can no longer be returned early, and as a consequence, a new roaming license (of a potentially higher version) will not be available until the original license roam expires. This also means that during the remaining time of the license roam, there will be one additional floating license available for each unexpired roamed license of the old version.

Another consideration is that a roamed license is a unit. Generally, it is unwise to roam licenses when a checkout request specifies multiple licenses. However, if you do this (checkout multiple licenses and allow them to roam), note that any check-in will check all the roamed licenses back in. For example, if you do a checkout of 4 licenses and they roam, then a check-in of 2 licenses with RLM_ROAM set to -1 will check in all 4 of the licenses which were checked out and roaming. In other words, the checkout you do to roam a license, even if the count is greater than one creates a single roamed license. When this license is checked in (either by setting RLM_ROAM to a negative value, or at the end of the roaming period), the entire quantity of licenses is checked back in. Put another way, a roamed license is indivisible, and it is not possible to return a subset of the license count in a roamed license.

Since you cannot have more than one roamed license of a given name on a single system, if you first request a roam of N licenses, then you make a 2nd request to roam more than N licenses, the 2nd request will be rejected with an RLM_EL_ALREADY_ROAMING status. Otherwise, the first roam file is destroyed and can never be returned.

RLM provides a mechanism to remove a local roaming license when the application cannot check the license back in early. In order to unconditionally return the local roamed license, set the RLM_ROAM environment variable to -100 before performing a checkout of the license. If set to -100, the checkout processing will still attempt to return the roamed license early, but if the server cannot process the request, the client will still remove the local roaming license information.

Special note on roaming licenses from a broadcast-discovered server

Reprise Software strongly recommends that you do not attempt to use the broadcast method to locate the server if a license is to be roamed. While this will often work, there are circumstances where RLM cannot re-locate the original server which supplied the licenses, and the roamed license cannot be returned early.

If the broadcast server is the only license server on the network, RLM will be able to return these licenses. However, if there are multiple license servers on the network, there is no guarantee that the application will find the correct server to return the licenses, even if you manually set the port and host of the server before attempting to return the license. If you know the port and host of the ISV SERVER which roamed the licenses, you can then:

  • Make sure the ISV server is running on the same port# (set the port # on the ISV line, if necessary).

  • Set RLM_LICENSE to this port and host (the ISV server, not rlm).

  • Set RLM_ROAM to -1 and check out the license again.

The relationship between roamed licenses, the rlm_checkout() count parameter, and rlm_isv_cfg_set_roam_single(handle, 1)

In nearly all cases, licenses will be roamed by using a checkout count of 1. However, it is possible to roam a license with a checkout count = n > 1. Reprise Software does not recommend this practice, but if you do it, take the following into consideration:

  • n licenses will be subtracted from the license server’s license pool

  • Once roamed, if a request is made for <= n licenses, the roamed license will satisfy this request. This is not a counted license in the normal sense, it is just that the roamed license keeps track of the count of licenses requested.

  • Once roamed, if a request is made for > n licenses, this request will fail with an RLM_EL_ALREADY_ROAMING error.

  • If rlm_isv_cfg_set_roam_single() is called, only a single process will be able to check out these licenses, however that process can check out up to “n” roaming licenses.

  • If rlm_isv_cfg_set_roam_single() is not called, any number of processes on the system will be able to check out up to “n” roaming licenses.

Extending the Roamed License

If your customer’s plans change and they would like to keep the license until after the roaming time has expired, but cannot reconnect the system to the network, they can extend the roam by having someone on the network extend the roam in the RLM web interface. Note that this only works before the original roam period has expired.

This capability must be enabled by you.

Call rlm_isv_cfg_enable_roam_extend(handle, 1) in your rlm_isv_config.c file, and re-build your ISV server or settings file after you have done so. If you do not do this, the “Extend Roam” column will not appear in the RLM web interface. Also note that if you enable this capability, the max_roam setting from your rlm_roam license will have no effect on the length of a roam extension. What this means is that the max_roam setting of the roamed license itself will be what limits the extension of the roam. By default, every license has a max_roam setting of 30 days, unless you override it. So be aware that if you enable the roam extend feature and you specify max_roam, you must do so on the product license, rather than on the rlm_roam license for max_roam to have any effect on roam extensions.

To extend the roam, someone on the network views the license status and finds the license that is roaming. This user must have the “extend_roam” privilege to see the last field. By selecting Status->License Usage for this license, they will see a screen listing all licenses currently in use. By entering the # of days to extend the roam in the text box on the right and pressing “Extend”, the process of extending the roam will start. Click YES to confirm the extension; the roam will be extended on the server side, and the screen will display the roam extension code, similar to the following:

test:12-sep-2017:1234567890abcdef1234567890abcdef1234567890abcdef

Now, on the disconnected client, set the environment variable RLM_ROAM_EXTEND to the roam extension code:

setenv RLM_ROAM_EXTEND test:12-sep-2017:1234567890abcdef1234567890abcdef1234567890abcdef

and run the application which checks out the “test” product. Once the checkout happens, the roam period is extended.

If you do not record the roam extension code from the web interface, it is also recorded in the server’s debug log as follows:

08/28 15:45 (reprise) ROAM EXTENDED: 5 days test v1.0 by matt@zippy
08/28 15:45 (reprise) Roam extended for product test by 5 days
08/28 15:45 (reprise) Roam extension code, place in RLM_ROAM_EXTEND
08/28 15:45 (reprise) and run client to check out license:
08/28 15:45 (reprise) test:12-sep-2017:1234567890abcdef1234567890abcdef1234567890abcdef

Note

If you extend the roam past a daylight-savings-time transition day, you may appear to get one hour more or less than you might expect (when viewing the RLM web interface), but the roam actually ends at midnight.

Tutorial on Roaming Licenses

The RLM kit contains an example program to help you understand how roaming licenses operate.

This example is called roam_example, and it is built during the normal kit installation. The example license file on the kit also contains an rlm_roam license, so everything is ready to go.

We suggest you follow this procedure to familiarize yourself with the operation of roaming licenses.

  1. First, install the kit.

  2. If you haven’t done so yet, sign the example license file using the command:

    % rlmsign example.lic

  3. Start the license server (in a separate window on Unix, or in a command window on windows, so that it is easy to see the debug log):

    % rlm

Now you are ready to run the roam_example program to investigate RLM roaming license behavior.

The first thing we are going to do is to set up a roaming license. To do this, run roam_example, and when it asks for the RLM_ROAM value, enter 1. roam_example will set the environment variable RLM_ROAM to 1, then contact the license server with a checkout request for the test1 license. You will note that roam_example now says that it has acquired a FLOATING license. This is correct. When the initial checkout which sets up the roaming license is performed, the application checks out a normal floating license, and informs the license server that it wishes for this license to roam. When this is successful, the roaming license is installed on the system where the application is running. You will note a line similar to the following in the server debug log:

01/14 15:28 (demo) OUT: test1 v1.0 by username@hostname (ROAMING for 1 days)

Finally, enter a <CR> to exit roam_example. You will note now that the server does not log the check-in of the license. This is because the license is roaming. The check-in will be logged later when either (a) the roam time expires, or (b) the license is manually returned (we will manually return the license later in this tutorial).

Your system is now set up with a roaming license, valid for 1 day. To test this license, run roam_example again, and specify 1 for the RLM_ROAM value. This time, you will see no activity in the server logfile, and roam_example will indicate that it acquired a ROAMING license. Enter a <CR> to exit roam_example.

Next, run roam_example and enter 0 or <CR> for the RLM_ROAM value. What happens next depends on whether the license server is still running or not. If the license server is running, roam_example will check out a floating license from the server and you will see this reflected in the server logfile. If the server is not running, then roam_example will use the roaming license, since no floating license was available. Why does it operate this way? Well, since the RLM_ROAM environment variable wasn’t set, RLM attempts to the checkout in the “normal” way, which means it contacts the license server and asks for a license. Only if all the normal checkout methods fail does it then attempt to use a roaming license if one exists. Note how this varies from the case above, where you set RLM_ROAM to 1 - in that earlier case, RLM attempts to use any roaming license before contacting the license server, and only if it cannot find a roaming license does it check out a license from the server (and as part of that process create a new roaming license on the system).

Early Check-in

Finally, what happens if you have set up a roaming license but want to return it early. RLM provides for this by setting the RLM_ROAM variable to a negative value. Make sure the license server is still running (start it if it is not) and run roam_example again. This time, specify -1 when asked for the RLM_ROAM value. You will check out a floating license, and the server will remove the currently existing roaming license for this computer. When roam_example does its check-in (actually, it simply exits), the server will log the check-in of the originally-checked-out roaming license.

At any step, you can use the RLM web interface to examine the state of the license server to see which licenses are checked out.

One thing to note about this tutorial is that it worked because we pre-installed an rlm_roam license in the example.lic license file. With this license present, both the client and the server were able to check out rlm_roam, which is a requirement for roaming to operate. In practice, if you wish for your customers to have the ability to use roaming licenses, you will need to ensure that a valid rlm_roam license exists on any computer where a roaming license is created. Since the whole point of roaming is to allow disconnected operation, the disconnected node cannot depend on getting its rlm_roam license from the license server, so you will need to put a small local license file on that machine. In practice, the easiest way to do this is to create the license file in the same directory as your product binaries, since this license file only enables roaming, and should not vary from customer to customer. In other words, if you wish to enable roaming for all your customers, treat the license file with the rlm_roam license as a normal part of your distribution kit.

We encourage you to browse the source of roam_example - it is in the examples directory on the kit, named roam_example.c.