Alternate Server Hostids

The Alternate Server Hostid capability works in conjunction with RLM Activation Pro and is not supported when used without ActPro.

Overview

An Alternate Server Hostid is a method to lock a license server to a nodelocked, uncounted license, rather than directly to a hostid. The main uses for this are to lock the license server to a rehostable hostid (so your customer can revoke and re-authorize the server), or so that you can disable a license server that is in the field.

The alternate server hostid hostid type (license=serial#) is supported by RLM only on the HOST/SERVER line. A single ISV server can only use a single Alternate Server Hostid locked to a rehostable hostid, i.e., there cannot be two different “license=xyz” hostids in 2 different license files if the two Alternate Server Hostids both use rehostable hostids. Also note that you cannot use an Alternate Server Hostid for an rlm_server_enable_vm license (either as it’s nodelocked ID or as a floating license where the server uses an ASH hostid).

The license server, at startup time, will verify the license specified by the alternate server hostid, and if it is valid, will then perform the operation specified by the “check-type” parameter. The “check-type” parameter specifies whether automatic communications with the activation server are done or not, and if so, how often the activation server is checked. If “check-type” is “none”, no automatic checking is done. If “check-type” is “startup”, the license server will make an rlm_act_keyvalid() call to the activation server at license server startup time. If “check-type” is “daily”, the license server will check at startup and again at midnight on every subsequent night. Finally, if “check-type” is “6hour”, the server checks the license on startup and again every 6 hours. Once the license is verified and any checks are done successfully, the server starts up normally. If a midnight (or 6 hour) check fails, the license server will continue to run for “tolerance-1” checks. If no successful check is done within “tolerance” days/6 hours, the server will exit.

Setting “check-type” to “startup”, “daily”, or “6hour” allows you to turn off a license server by disabling the associated activation key. If the check fails with a “key not valid” error the server will exit immediately (on startup), otherwise, the tolerance parameter specifies on how many days (or 6-hour checks) errors can occur. On the failure the “tolerance” time, the license is disabled.

The license for the alternate server hostid must have the following characteristics.

Note

This is the alternate server hostid license only, these restrictions do not apply to the other licenses you put in the license file.

Also note that this license is generated correctly by Activation Pro when you select the “Alternate Server Hostid” license type, so you don’t have to worry about these parameters (other than setting the product name correctly), which are here for reference:

It must be a nodelocked, uncounted license (ActPro does this automatically when you select the “alternate server hostid” license type).
Product Name: rlm_server (you must set the product name correctly)
options string, as defined below
serial# must be a decimal number of <= 15 digits (activation pro generates this automatically every time it creates an activation key)
issuer=URL-of-activation-server (if you use either the startup, daily, or 6hour option, see below)
hostid: required
akey= required (if using “startup”, “daily”, or “6hour”)

The options string has the following format:

options=serial#:check-type:tolerance

Where:

serial# - is the serial number from the license=serial# specification on the SERVER line

check-type is one of the 4 values:

none: no check with the activation server is done by the license server

startup: check (rlm_act_keyvalid()) with the activation server at license server startup time

daily: check (rlm_act_keyvalid()) with the activation server on startup and every night at midnight.

6hour: check (rlm_act_keyvalid()) with the activation server on startup and every 6 hours subsequent to that.

tolerance: is a # of days (or number of 6-hour checks), N. Used only for the “daily” and “6hour” check-types. The server can fail its check N-1 times in a row without any issues, N failures in a row cause the server to stop serving licenses for this hostid.

Note

The serial number is the part of the hostid that makes the floating licenses in the license file unique, so if you create an alternate server hostid license without Activation Pro (which is not recommended or supported) you should BE SURE to give each of your customers a different serial number. Activation Pro will do this for you automatically.

When creating the product definition for an Alternate Server Hostid license, use ActPro’s “Alternate Server Hostid” License type in the product definition for this – this product definition will generate the SERVER, ISV, and nodelocked LICENSE lines required. Activation Pro also allows you to enter the check type, and tolerance in the product definition. The serial number is generated automatically when an activation key is created, and cannot be changed. You MUST, however, set the product name to “rlm_server”.

When creating your product definition, be sure to select “Yes” in the “Include Activation Key in License” parameter, and if you are using this capability to provide rehostable licenses, select only “rehostable” in the “Allowed Hostid Types” selection of either the product definition or activation key.

If you use the alternate server hostid on the SERVER line, a single instance of rlm can only support your ActPro server, it cannot support other ISV’s servers.

Finally, when you create an alternate server hostid activation key, you almost certainly want to give it an activation count of 1. If you give it a count > 1, your user can create multiple servers which have the same hostid. This means that any license you issue to this hostid will work on each of the servers so activated.

In all use cases for alternate server hostids, the plan is to activate the alternate server hostid first. Once this is activated, call rlm_act_fulfill_info() on the activation key to retrieve the server’s hostid that was generated (it will be of the form “license=xxx”). You can then use this hostid when activating your product licenses.

Warning

If you use alternate server hostids, you MUST set the URL in the ActPro database in the admin->database tab.

Server startup tolerance window

In addition to the tolerance count for 6-hour and daily checks, RLM v14.1 allows you to specify a time window from the last successful contact with the activation server. If you specify this window, and the license server is unable to contact the activation server at startup time, the license server will still start up.

Note

The daily and 6hour checks will still be performed and if the license server remains unable to contact the activation server for the number of times specified, the license server will stop serving licenses.

To set the server startup tolerance, call rlm_isv_cfg_set_ash_start_tolerance(), with the # of minutes you wish to allow the tolerance interval to have. A good value would be 1 or 2 days. For example:

#define DAY 60*24

        rlm_isv_cfg_set_ash_start_tolerance(handle, DAY*2);

Alternate Server Hostid Examples

Example 1. Lock your server to a regular hostid, and check the license every day.

In this example, the server will check the activation key with the activation server every time it starts, plus every night at midnight. If the check fails for 10 days in a row the server will stop serving other licenses for this hostid. You would use a SERVER line and license like this:

HOST localhost license=1234
LICENSE isvname rlm_server 1.0 1-jan-2025 uncounted
hostid=12345678 issuer=http://www.hostedactivation.com
akey=1234-5678-9999-4321
options=1234:daily:10 signature

Example 2. Lock your server to a rehostable hostid, and check the license only at server startup.

For this example, you would use a HOST line and license like this. Note that this example uses a “rehostable” hostid. This allows your customer to rehost the license server, but it also allows you to disable the licenses later. In this example, the tolerance (10– the 3rd parameter in the options string) is unused.

HOST localhost license=1234
LICENSE isvname rlm_server 1.0 1-jan-2025 uncounted
RLM Reference Manual Page 153 of 296hostid=rehost=cc5a340f:84ca2561da285b7cbac719a916b016dcffde6434
issuer=http://www.hostedactivation.com akey=1234-5678-9999-4321
options=1234:startup:10 signature

Example 3. Lock your server to a license with no automatic activation server involvement.

For this example, you would use a SERVER line and license like this. In this example, your customer would activate (and deactivate) this hostid using RLM’s web interface, but the license server would not automatically contact the activation server at any time.

HOST localhost license=1234
LICENSE isvname rlm_server 1.0 1-jan-2025 uncounted
hostid=rehost=cc5a340f:84ca2561da285b7cbac719a916b016dcffde6434
options=1234:none:0 signature

Errors - What happens if the license server can’t contact the activation server, or gets an error?

The license server attempts to automatically contact the activation server for either the “startup”, “daily”, or “6hour” check types. This check may result in an error from the activation server. Depending on when the error happens, it is handled as follows:

For the “startup”. “daily”, and “6hour” types, the license server needs to check the activation key at startup time and periodically afterwards. The errors from the activation server which are tolerated at startup time are minimal.

At startup time, the following status returns will be ignored, and the server will continue to run if the license is still valid:

0 (good status)
RLM_EH_INTERNAL
RLM_EH_NET_RERR
RLM_EH_NET_WERR
RLM_ACT_CANT_WRITE_FULFILL
RLM_ACT_CANT_WRITE_KEYS
RLM_ACT_CANTREAD_DB

Any other status return will cause the license server startup to fail, and the server will only process nodelocked, uncounted licenses from this license file, and no check with the activation server will be attempted in order to recover.

For “daily” or “6hour” checking, at the re-check, any errors will be tolerated, however it will be considered a failure. If the check fails with an error for “tolerance” number of checks in a row, the server will continue to run, but behave as if any served licenses were removed from the license file.

In all cases, the following errors will cause the server to immediately stop serving licenses locked to this hostid:

RLM_ACT_NO_KEY
RLM_ACT_NO_PROD
RLM_ACT_NO_KEY_MATCH
RLM_ACT_KEY_DISABLED
RLM_ACT_KEY_NO_HOSTID

Use Case #1: Using Alternate Server Hostids to support rehosting of License Servers

In order to allow your customer to rehost their license server, use the following procedure:

In rlm_isv_config.c, be sure that you have set the activation server’s URL with the rlm_isv_cfg_set_url() call. The default URL is “hostedactivation.com”, so if you use Reprise’s hosted activation service, you can skip this step. Everyone else needs to set the URL here. None of this will work without the correct URL setting.
In rlm_isv_config.c, be sure to include RLM_ACTPRO_ALLOW_ASH in the “allowed_types” variable in the call to rlm_isv_cfg_actpro_allowed_hostids().
Set the URL in Activation Pro, in the “Admin”/”Database”/“Activation Server URL” section. This causes the correct URL to be placed into the license.
Set up a product in Activation Pro with product name “rlm_server”, license type “Alternate Server Hostid”. Set the check type and tolerance interval here. Check only “rehostable” under “Allowed Hostid Types”. Check “Yes” under “Include Activation Key in License”. Leave the “Other RLM keyword=value pairs” field blank – Activation Pro will fill this in.
Create an activation key for this product. Saving the activation key will cause ActPro to generate a unique serial number in the “ash_sn” column of the “keyd” table. You should issue a single activation key for a single Alternate Server hostid, and you should not delete this key if you ever want to get that serial number back again. Leave the “Other RLM keyword=value pairs” field blank.
Give the activation key to your customer.
Your customer will need to bring up RLM with a license file that has an ISV line for your ISV server, so that your ISV server will start. They can start RLM with a license file containing these two lines:
```
HOST localhost ANY
ISV your-isvname
```
Your customer then goes to the RLM web interface and selects “Status”. At the far righthand side of your ISV server’s line, there is a button labeled “Activate” (the user must have the “edit options” privilege for this button to appear). They should click this button, then enter the activation key you supplied (from step 5, above), and press “Activate/Deactivate Alternate Server Hostid”. If the operation succeeds, your ISV server will write a license file named “rlm_your-isvname_activation_key.lic” in the current directory (if your customer deactivates a rehostable hostid-based license, this license file will be deleted).
Your customer should copy the HOST line from the new license file to their main license file for this server. This can be done with the “Edit License Files” button in the RLM web interface.
Next, when your customer activates licenses to be used on this server, they should use the hostid “license=xxx” from the HOST line in this license file. (Reprise recommends that you keep the rlm_your-isvname_ash.lic file separate from the file with all your regular licenses, since the Alternate Server Hostid file will be replaced on a re-activation.
At this point your customer can deactivate the Alternate Server Hostid license, move the license file and software to another machine, and re-activate it there.

Use Case #2: Remotely Disabling License Servers

In order to be able to disable your customer’s license servers, use the same procedure as Use Case #1, with the following exceptions:

You would always use “startup”, “daily”, or “6hour” for checking, never “none”
You can use a rehostable hostid as in Use Case #1, or you can leave the “Allowed hostid types” blank in order to use a standard hostid.

Use Case #3: What do you do if the user loses his license file(s)?

This is somewhat of a sticky situation, but you can recover as follows:

Get the ASH license itself:
- Call rlm_get_rehost() with the product name “rlm_server”
- Call rlm_act_keyvalid_license() with the ASH activation key and the hostid from the rlm_server license from the previous step.
Extract the license # from the ASH license:
- Write the license from step 1 into a new license file, call rlm_init().
- RLM_LICENSE lic = rlm_checkout(RLM_HANDLE, “rlm_server”, “1.0”, 1);
- char *options = rlm_license_options(lic);
- char *p = strchr(options, ‘.’); if (p) *p = ‘0’;
- sprintf(ash_hostid, “license=%s”, options);
With the ASH hostid, retrieve the other licenses with rlm_act_keyvalid_license()
Write the new license file for the other licenses:
- SERVER localhost license=ash_hostid#
- ISV your-isvname
- LICENSE 1
- LICENSE 2
- …
- LICENSE n

Here’s some example code:

The routine write_license() is assumed to write the license file with the string specified.

  RLM_LICENSE lic;
  char *options = (char *) NULL, *p = (char *) NULL;
  char rehost_hostid[RLM_MAX_HOSTID_STRING+1];
  char ash_hostid[RLM_MAX_HOSTID_STRING+1];
  char license[RLM_MAX_LINE*10];

    i = rlm_get_rehost(rh, "rlm_server", rehost_hostid);
    if (i) { ERROR }
    i = rlm_act_keyvalid_license(rh, acthost, "activation-key-for-ASH-license",
                                                        rehost_hostid, license);
    if ( !i )
    {
      rlm_putenv("RLM_LICENSE=”your-ASH-lf");
      write_license(“your-ASH_lf”, license);
    }

#if 0   /* This was the code to use before rlm_act_fulfill_info() was available */
    rlm_close(rh);
    rh = rlm_init("", argv0, (char *) NULL);
    rlm_putenv("RLM_LICENSE=.");
    lic = rlm_checkout(rh, "rlm_server", "1.0", 1);
    if (lic) options = rlm_license_options(lic);
    if (options) p = strchr(options, ':');
    if (p) *p = '\0';
    if (options) sprintf(ash_hostid, "license=%s", options);
    else ash_hostid[0] = '\0';
    rlm_act_keyvalid_license(rh, acthost, "activation-key-for-floating-licenses”,
                                                        ash_hostid, license);
#else   /* code to use post v12.1, with rlm_act_fulfill_info() */
  {
    char prod[RLM_MAX_PRODUCT+1], ver[RLM_MAX_VER+1], exp[RLM_MAX_EXP+1];
    int date_based, license_type, upgrade_version, count, fulfilled, rehosts, revoked;
    /* all vars on above 2 lines unused */

    rlm_act_fulfill_info(rh, acthost, "activation-key-for-ASH-license", prod, vers, &date_based,
                                &license_type, upgrade_version, &count, &fulfilled, &rehosts,
                                &revoked, exp, ash_hostid);
  }
#endif
    if ( !i )
    {
      char lic2[RLM_MAX_LINE*10];

        sprintf(lic2, "SERVER localhost %s\nISV reprise\n", ash_hostid);
        strcat(lic2, license);
        write_license("activation1.lic", lic2);
        reread_server();
    }