Enabling Your Application for Activation
The last step in setting up Activation Pro is adding activation requests to your application, as described in this chapter.
On the client side, you must prepare your activation code and get the activation key to your customer.
Making the Activation Request for Your Customer
Using the Activation API
Once you are familiar with how to use the activation server and the activation GUI, you are ready to integrate the activation request into your application. To do this, embed a call to rlm_activate() at the appropriate point (usually after attempting to check out a license which fails), and, if you are successful at activating the license, perform the following steps:
Call rlm_close() on your handle.
Write out the activated license to a local license filename of your choice (Reprise Software recommends a file named something.lic).
Call rlm_init()
Re-attempt the license checkout.
For details on the activation API request call, see Appendix A - Activation API.
Using the Activation GUI
You can get started right away by using the activation GUI supplied by Reprise Software. We recommend that you start this way, so that you can become familiar with the server side of activation without having to embed any code into your application. However, Reprise does not recommend using this method for production.
In order to proceed, make sure that you have set up the server side as described in Activation Pro Setup and created at least one product definition and activation key as described in the Product Definitions and Activation Keys sections of Your Activation Database.
The activation GUI is built into the RLM web server. Run RLM (you don’t need a license file), point your browser at port 5054 (or the port number you specified in the -ws port# specification) then select Activate License from the menu on the left-hand side. The GUI will guide you through the steps in activating a license.
When the RLM web server activates a license, the resulting license file will be placed in the directory from which RLM was started, and the file name will be “activateN.lic”, where N is a sequence number. Each activation performed will get a new number.
Note
RLM activation will only operate with non-zero RLM_HOSTID_32BIT, RLM_HOSTID_ETHER, or ISV-defined hostid types - all other hostid types will return an error.
Activation API or RLM Web Interface - Which to Use?
The RLM web interface is completely generic, and you can activate licenses for your products using this interface by setting up activation on your web server and specifying your URL. However, it will always be simpler for your customer if you integrate the RLM activation API into your product or installation tools, since you can preset many of the activation parameters, such as URL, ISV name, etc.
Reprise Software strongly recommends that you integrate the API into your product.
Other Client-side Activation Options
Alternatively, you can create a custom stand-alone activation utility for your customers, rather than building it into your application. Follow the steps above for using the Activation API.
Also, you can create an HTML page to activate licenses using your activation server. For an example of this, see “activation_example.html” in the RLM kit “examples” directory. This technique, however, will require your customer to cut and paste the resulting license file into the appropriate file on their system, so it is inferior to integrating the activation API into your application.
Setting the Activation Timeout
In some cases, the activation process will time out, returning an RLM_EH_NET_RERR (-105) error. If your activation server is properly configured, this can happen either due to a proxy server or anti-virus software blocking the return, or if the activation server times out on the reverse DNS lookup of the client. See the next section for info on setting proxy server parameters.
The first thing you should try, however, is increasing the timeout on the client side. By default, this timeout is 15 seconds prior to RLM v14.1, and 20 seconds in v14.1. You set the client-side timeout by setting the environment variable RLM_ACT_TIMEOUT to the # of seconds you desire.
Using Proxy Servers
The RLM Activation client software (either the rlm_activate()/rlm_act_request() API calls or the RLM admin web interface) will make use of a user-defined proxy server. In order to use a proxy server, set the environment variable HTTP_PROXY or http_proxy to the hostname and port number of the proxy server.
For example, to utilize the HTTP proxy server running on “myproxyhost” on port 8765, use the following command on Unix:
% setenv HTTP_PROXY myproxyhost:8765
If your proxy server uses authentication, you use the HTTP_PROXY_CREDENTIALS environment variable to pass the credentials to the proxy server. This will bethe username and password to authenticate you to the proxy server, in the format user:password.
For example, if your username is “joe” and password is “joes_password”:
% setenv HTTP_PROXY_CREDENTIALS joe:joes_password
Note
RLM activation supports only the BASIC authentication type.
You can either set these environment variables before running your application, or use putenv() (or rlm_putenv()) to set them inside your application before calling rlm_act_request().
Proxy Auto-Detection
Beginning in RLM v11.0, RLM will attempt to auto-detect the proxy server on Windows systems. If auto-detection fails, you can set the RLM_PROXY_DEBUG environment variable to get diagnostic information written to stdout. You can also replace RLM’s default auto-proxy detection on Windows, or add your own detection on other platforms. To do this, replace the rlm_get_proxy.obj or rlm_get_proxy.o module in the library. This module contains the single entry point rlm_get_proxy().
rlm_get_proxy() is called as follows:
void rlm_get_proxy(const char *url, char *proxy)
rlm_get_proxy() attempts to locate the proxy server for the specified URL. If a proxy is located, the return string “proxy” is filled in with the hostname and port in the format hostname:port
If there is no proxy, or the proxy is bypassed, rlm_get_proxy() should return an empty string.
The proxy name is allocated by the caller, and is a string of 1000 characters.