.. _use-roaming-licenses: ########################### How to use Roaming Licenses ########################### RLM has the ability to allow a floating license to roam to a system which will subsequently be disconnected from the network. 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, you can return the roamed license back to the license pool early if this is desired. ------ ******************************************* How to know if License Roaming is Available ******************************************* Your ISV makes the decision to enable roaming licenses. If you have been issued an rlm_roam license, then roaming is available to you with the restrictions specified in the *rlm_roam* license. Note that you must be able to check out an rlm_roam license on any system that is disconnected. Practically speaking, this means that disconnected systems need a local license file with a nodelocked *rlm_roam* license in it. ------ ************************** How to make a License Roam ************************** If you have an *rlm_roam* license, set the environment variable **RLM_ROAM** to the number of days which you would like to use the license (this license will be available until midnight on the last day of the roam, so for example if you specify one day, the license is available until midnight tomorrow). Once **RLM_ROAM** is set, run the product and let it check out its license(s). If the checkout succeeds, then the license is set up to roam. You can repeat this procedure for any other products that have roaming capability enabled. If you set **RLM_ROAM**, the setting of **RLM_QUEUE** is ignored. .. note:: Beginning in RLM v12.2, 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**. Be sure your *rlm_roam* license is contained in a license file that is local to this system, otherwise you will not be able to use these licenses. Your Software Provider might have supplied a GUI to handle the setting of the RLM_ROAM environment transparently to you. If this is the case, they will have documented this capability in their application's documentation. .. note:: Beginning in RLM v11.1, **RLM_ROAM** can be set to the special value “today”. If set to “today”, the license will roam until the end of the day today. Please note that if you use a v11.1 client with an older (pre-11.1) server, **the roam time will be one day longer than what** **you specified**. Pre-11.1 clients will roam as expected with 11.1 and later servers, however they will not be able to take advantage of the “today” value of **RLM_ROAM**. ------ ********************************************* While your system is connected to the network ********************************************* After the initial checkout of the roaming license, but during the time your system is connected to the network, the value of **RLM_ROAM** will affect the behavior of the roaming license. If **RLM_ROAM** remains set to the original value, the license will be "refreshed" each day to the total roam time. On the other hand, if **RLM_ROAM** is set to 0, the original roam end date will remain, and no subsequent checkouts of the license will alter the final roam day. What this means, for example, is that if you set **RLM_ROAM** to 14 days, the license will always be available to you 14 days after the last time you checked it out on the network. If, however, you first set **RLM_ROAM** to 14 days, check out the license, then set **RLM_ROAM** to 0, the license will be available on the disconnected system for 14 days from the date of the first checkout, no matter how many times you check it out while connected. Again, your Software Provider may have taken care of this for you in their GUI. ------ ********************************* While your system is disconnected ********************************* During the time your system is disconnected, **RLM_ROAM** must remain set to a non-negative value. This license will be available on this system for the number of days you requested, and you no longer need to be able to access the license server from which the license was granted. On the network, the license server will show the license checked out to you. .. note:: **RLM_ROAM** does not need to be set *while* the system is disconnected. .. note:: If you are connected to the network and do not set **RLM_ROAM**, you may check out a license from the license server rather than using the roamed license. If this is not desired, you can set **RLM_ROAM** to a positive number which will cause the roamed license to be used. Also note that if **RLM_ROAM** is not set, the checkout of the "rlm_roam" license must come from a local license file, not from the license server. ------ ********************************************** If you want to return the Roamed License early ********************************************** If your plans change and you would like to return the license before the roaming time has expired, reconnect the system to the network (so that it can contact the original license server), and set the environment variable **RLM_ROAM** to -1. Now run the program and let it check out the license. Once the program exits (or does a check-in), the roamed license will be returned to the license pool on the server. .. warning:: If you change the server node name or port number after you roam the license, you will not be able to return the license early. ------ ****************************************************** If you want to extend the period of the Roamed License ****************************************************** If your plans change and you would like to keep the license until after the roaming time has expired, but cannot reconnect the system to the network, you can extend it by having someone on the network extend the roam in the RLM web interface. Note that this only works before your original roam period has expired, and only on a v12.3 or later server (and client). .. note:: This capability must be explicitly enabled by your ISV; it does not appear automatically. If the “Extend Roam” column in the License Status screen (shown below) does not appear, this means your ISV does not support the ability to extend a roam remotely. If your ISV does support this, to extend the roam, someone on the network views the license status and finds the license you have 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 similar to the following: .. image:: ../_images/extend-roam.png 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, and the following screen will appear: .. image:: ../_images/extend-roam-2.png If “Yes – Extend user's license” is selected, the roam will be extended on the server side, and the screen will display the roam extension code: .. image:: ../_images/extend-roam-3.png Now, on the disconnected client, set the environment variable RLM_ROAM_EXTEND to the roam extension code: .. code-block:: text 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: .. code-block:: text 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 that if you extend the roam past a daylight-savings-time transition day, you may get one hour more or less than you might expect (when viewing the RLM web interface), but the roam ends at midnight. ------ ******************************************************************* 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 starting with v11.2, however, earlier versions of RLM could not return the roamed license. 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. (This technique will work for earlier versions of RLM as well).