Server-Server License Transfer

RLM has the ability to transfer a set of licenses from one license server to another. This capability is described in the Transferring Licenses to Another Server section of the License Administration manual. Licenses are said to be transferred from a source license server to a destination license server.

The destination license server is always an RLM server. As shipped from Reprise Software, the source license server is an RLM license server as well. However, as an ISV, there are two things you can do to enhance the License Transfer capabilities of RLM:

  1. License transfers can be “disconnected”, which means that the destination license server acquires roaming licenses from the source license server.

  2. You have the ability to extend the license transfer capability to enable transfer from a non-RLM source license server. This capability is useful, for example, when you are doing a transition from another license manager to RLM, to avoid the possibility of issuing your customers duplicate licenses.

    Note

    You can define a single non-RLM license transfer extension, i.e., you can only support one other license manager for license transfers.

Support for these 2 scenarios are described in the next sections.

Disconnected license transfer support

Disconnected license transfer, allows your customer to move some licenses from the source server to a destination server for a period of time, and the destination server does not need to maintain contact with the source server during that time. Internally, disconnected license transfer uses RLM’s license roaming capability, so all the controls and restrictions of license roaming apply:

  • You must issue an rlm_roam license to your customer to enable this capability (although we provide a means for you to do this internally in your server so that no separate license has to be shipped).

  • Once a license is transferred to the destination server in this way, the license on the source server cannot be removed or upgraded or the destination license will not be able to be returned to the source server (until it automatically expires).

  • Your control over the maximum roam duration influences your customers maximum time to disconnect the destination server’s licenses.

  • Your customer’s control over ROAM_MAX_COUNT and ROAM_MAX_DAYS in the ISV server options file will limit the number of licenses the destination server can request, as well as the duration of the disconnection.

  • These licenses, like all transferred licenses, are not eligible to be roamed to another system.

The description of disconnected license transfer under Transferring Licenses to Another Server.

If you already issue rlm_roam licenses to your customers, then you need to do nothing further – your customer will only have to put the rlm_roam license in a license file which the destination server reads at startup time, then they will be able to create license transfer definitions with “Days to hold license” (in the license transfer GUI) set to a non-zero value.

Should you wish to make the delivery of the rlm_roam license even easier, you can add the following call to your rlm_isv_config.c file, by providing a valid, signed rlm_roam license:

rlm_isv_cfg_set_server_roam(handle, "<LICENSE isvname rlm_roam 1.0 uncounted hostid=any
sig=xxxxxxx>");

Note

This license must use the following parameters: * version: “1.0” * exp: “permanent” * count: “uncounted” * hostid: “any” * NO other parameters

If you use this call and you ship an ISV server settings file, you will need to re-generate your settings file with RLM v10.1 or later.

Note

These licenses, once roamed to the destination license server, are not available for checkout by an application on that server machine which doesn’t contact the license server – they are only available for checkout by contacting the destination license server itself.

License Transfer from a non-RLM source license server

Should you wish to support a source server that is not an RLM license server in order to do a transition of your customers, you would do the following:

  • Integrate RLM into your application, just as any new RLM customer would.

  • Ship your RLM-licensed product with new RLM licenses to all new customers, and to all existing customers who purchase additional licenses. This is exactly what an RLM customer who did not have a previous license manager would do.

  • Ship your RLM-licensed product, without new licenses to existing customers. Using license transfer, the customer can partition their existing license pool to use some licenses with new products (via the license transfer capability) and some old licenses with old products which utilize your old license manager.

  • Eventually, as the old versions of your product are no longer used, the need for license transfer becomes obsolete when all your customers are using new products with new (RLM) licenses.

Implementing ISV-defined license transfer

In order to enable license transfer from a different source license management system, you need to write the code to perform initialization, checkout, check-in, status, heartbeats, etc., from the other license management system. RLM provides a plugin interface for you to enable this in your ISV server. We call this ISV-defined license transfer.

In order to implement ISV-defined license transfer, there are 2 steps you need to take:

  1. Write the functions to do the transfer, and to register with the RLM ISV server.

  2. Link your license transfer functions into your ISV server.

There is an example of ISV-defined license transfer code on the kit in the examples directory. The code is contained in the file rlm_transfer.c. This module illustrates ISV-defined license transfer by implementing license transfer from a source RLM license server. While this code is not useful (since RLM transfer is built into RLM), it illustrates how to write the transfer functions in terms of the RLM API.

Writing your ISV-defined license transfer code

You begin by writing a source module to perform the other license manager’s basic checkout/check-in operations. Reprise Software recommends using the rlm_transfer.c example code as a guide to writing this code. This code has been integrated and tested with RLM by Reprise Software, and is tested on each release as part of our normal QA test suite.

In this module, you will write 9 independent functions for your license manager “xxx”:

  • check_auth_xxx()

  • fillin_auth_xxx()

  • update_status_xxx()

  • open_xxx()

  • checkout_xxx()

  • hb_xxx()

  • checkin_xxx(),

  • close_xxx(), and

  • rlm_ix_enable()

These 9 functions are described in the sections which follow.

Reprise recommends that you put all source into a single source file, and make all the functions static/private with the exception of rlm_ix_enable(), which must be a public function. You must define all 9 functions.

Once you write this source module, include the object in the makefile to link your ISV server. So, for example, if you name your module “my_xfer.c”, and the other license manager’s libraries are named “other_lm.lib”, modify the makefiles as follows:

Change the lines:

ISV_XFER_SRC =
ISV_XFER_OBJ =
ISV_XFER_LIBS =

to:

ISV_XFER_SRC = my_xfer.c
ISV_XFER_OBJ = my_xfer.obj
ISV_XFER_LIBS = other_lm.lib

In addition, you may need a special rule to build “my_xfer.obj” from “my_xfer.c”. Create this rule here as well.

Parameters for all transfer functions:

Type

Name

Description

(void *)

auth

RLM license auth handle (used only to pass through to other RLM functions).

int

count

# licenses transferred

(void *)

license_handle

The license manager’s license handle.

(void *)

lm_handle

The license manager’s (job) handle.

(void *)

ls

RLM license server handle (used only to pass through to other RLM functions).

(char *)

product

Product name transferred.

(char *)

server

Server where transfer originated.

int

status

Checked-out license status on update.

(char *)

ver

Version of product to transfer.

check_auth_xxx() - check parameters of transferred license

int check_auth_xxx(void *ls, char *product, void *lm_handle, void *license_handle)

This function verifies that a checked-out license is valid for a transfer. Several things could make it invalid - e.g., if it is a user- or host- based license, we don’t want to transfer it. Returns 0 if the license is OK, or -1 if it is invalid.

For RLM licenses, we make sure the license is not a user-based, host-based, named-user, or token-based license.

For other license managers, other types of licenses may be ineligible for transfer. You can decide what is, and what is not transferred by accepting or rejecting it here.

  • product: product name

  • lm_handle: lm handle (RLM_HANDLE for rlm, cast to void *)

  • license_handle: license handle (RLM_LICENSE for rlm, cast to void *)

If you return -1, your check-in and close function will be called by RLM (checkin_xxx()).

fillin_auth_xxx() - fill in RLM license parameters for transferred license

void fillin_auth_xxx(void *ls, void *lm_handle, void *license_handle, void *auth, void *product,
int count)

This function fills in a license authorization from the checked-out license. License parameters are contained in “lm_handle”, and/or “license_handle”.

Some other license managers (e.g. FLEXlm) don’t have a license handle but use the lm handle along with the product name to identify the checked-out license.

update_status_xxx() - update the status of a transferred license

int update_status_xxx(void *ls, char *server, int status, void *lm_handle, int *passes_to_check)

This function updates the transfer status if a checkout fails.

Returns 0 if the checkout can be attempted again, or 1 if it will never succeed.

Also, passes_to_check should be updated with the number of passes before another checkout should be attempted. Each pass is one minute later. So, for example, if the license server is down, we wait 10 passes (10 minutes) before attempting the checkout again in the standard RLM license transfer code.

open_xxx() - open the other license manager

int open_xxx(void *ls, char *lmname, char *host, void **lm_handle, int *unavailable)

This function creates the license manager’s handle that will be used for the license checkout, and sets any required attributes in that handle.

Returns the handle in the “lm_handle” parameter. So, in the example RLM code, this returns an RLM_HANDLE in the “lm_handle” parameter.

checkout_xxx() - check out the product from the other license manager

int checkout_xxx(void *ls, void *lm_handle, char *product, char *ver, int count, void **license_handle)

This function performs the license checkout of product/ver/count. The function return is the license checkout status, and the license handle (if applicable) is returned in “license_handle”. If the license manager has no license handle (e.g. FLEXlm), return NULL for the license_handle.

hb_xxx() - perform a heartbeat on the other license manager

int hb_xxx(void *lm_handle, void *license_handle)

This function performs a heartbeat on the handle; returns status:

  • 0 for good status

  • LM error for error

Some license managers (e.g., RLM) require the license handle for the heartbeat, others (e.g., FLEXlm) require the license manager’s (job) handle. Choose the handle appropriate for your license manager.

checkin_xxx() - check in the product and close the license handle

int checkin_xxx(void *lm_handle, void *license_handle)

This function performs the product check-in and closes and frees the license handle.

The license handle should be closed and freed if the license management system requires this. In RLM, for example, an rlm_checkin() call does the check-in and frees the license handle.

close_xxx() - Close the license manager’s handle

int close_xxx(void *lm_handle)

This function closes and frees the license manager’s handle.

The license manager’s handle should be closed and freed if the license management system requires this. In RLM, for example, an rlm_close() call performs this function.

rlm_ix_enable() - enable ISV-defined license transfer in RLM

This function registers your ISV-defined license transfer functions.

The function name, “rlm_ix_enable” should not be changed, nor should the names of the 2nd and 3rd parameters to the call.

Call rlm_ix_enable as follows:

rlm_ix_enable( "license manager name",  /* License Manager name */
        rlm_ix_transfer,                /* DON'T CHANGE THIS */
        rlm_ix_xfer_done,               /* DON'T CHANGE THIS */
        open_xxx,                       /* Your handle open fcn */
        checkout_xxx,                   /* Your checkout fcn */
        fillin_auth_xxx,                /* Your auth fillin fcn */
        check_auth_xxx,                 /* Your license check fcn */
        update_status_xxx,              /* Your status update fcn */
        hb_xxx,                         /* Your heartbeat fcn */
        close_xxx,                      /* Your checkin fcn */
        checkin_xxx);                   /* Your LM handle close fcn */

RLM support functions

There are 2 support functions you will need when writing your ISV-defined license transfer code. These functions are used in the example, and are described here:

rlm_ix_log(void *ls, char *errtxt)

logs a message to the ISV server debug log. Pass “ls”, the RLM license server handle, from the calling parameters, and a string to log.

rlm_ix_update_auth(void *ls, void *auth, int what, int ival, char *sval)

updates the server’s license “auth” data with parameters from the transferred license.

“what” is which parameter to update (see license.h for definitions), if the value of “what” is an integer, put the value into ival, if it is a string, put the pointer into sval. See rlm_transfer.c in the examples directory for examples on use of rlm_ix_update_auth().