Command Line Interface – Heirloom Computing

The Licensing-as-a-Service (LaaS) command line interface is used to create subscription files for your users. They install the subscription file (not containing license information) onto the systems you applications are running.

Heirloom Computing, Inc. Licensing-as-a-Service
Cloud Based License and Transaction System

Usage: java HCILicensing [-f licensing.properties]
[-u https://.../licensecheck]
[-s subscription-id] [-e email-address]
[-c transaction-count]
[-i import-file] [-x export-file]
[-p product-code] [-r] [-q] [-l] [-h]
-f -- licensing properties file containing license checking info, default
      'licensing.properties' in your home directory
-u -- license / transaction checking URL, default
   'https://paas.heirloomcomputing.com/rest/2018-01-01/licensecheck'
-s -- subscription-id to check against, replacing or
   initializing licensing properties file
-d -- licensing domain name, default contained in licensing properties file
-e -- email-address authentication to check against, replacing or
   initializing licensing properties file
-p -- product-code to check, default taken from or added to
   licensing properties file
-c -- add transaction count to total, default 1
-x -- export the current license file
-i -- import the given file and merge it with the current license file
-r -- require a check against the LaaS server
-l -- list the current counts, when to check the license again,
   remaining grace period
-q -- quiet, do not print anything
-h -- this list of options
exit code 0 if OK, 1 if expired but within grace period, 2 if expired
outside grace period, or 100 communications problem
(c) 2013 Heirloom Computing Inc., http://www.heirloomcomputing.com/

Command Line Interface Operation

You need a Java Runtime Environment (JRE) installed to operate the command line interface. Download a JRE 1.6 or higher from http://java.com/ Download the command line interface as a Java archive file from your started LaaS Server you started from paas.heirloomcomputing.com > Portal. Use the java command with the -jar flag to reference the command line java archive, followed by the options you require. For example, to get command-line help, issue:

java -jar HCILicensing.jar -h

Create License File

Create a new license file by first finding out the subscription ID, the registered e-mail address on file for that user and the product ID from the Administrator's Interface.

Note: When you start your Licensing-as-a-Service Heirloom cloud instance it will be given a domain name such as "h-123456.instances.heirloomcomputing.com". Use the Heirloom Dashboard to change the "h-123456" volume name to something representative of your organization, such as "hisco" in this example. Have your network administrator define a DNS CNAME (alias) for that name, such as "licensing.hisco.com" an alias for "hisco.instances.heirloomcomputing.com". In this way your client application can direct checking requests to a domain name that your users understand. A self-signed SSL certificate is created when you start your instance, encrypting transmission of all license checking. You can upload a certificate (for "licensing.hisco.com") to eliminate browser warnings when accessing the Admin Panel.

When creating the license file use the domain name you choose as part of the "license check URL" (-u option). Also specify a consistent "license domain" for all of your requests (-d option). By convention, this is the same as your LaaS volume). Also specify the default product ID that will be used for all LicenseCheck() API calls that don't specify an explicit product ID. The customer for which you are creating the licensing must be identified with their customer id (-s option) and e-mail address (-e option).

java -jar HCILicensing.jar \
-s 12345678-1234-1234-1234-123456789012 \
-e end-user@hisco.com \
-d hisco -c 0 \
-p 87654321-4321-4321-4321-210987654321 \
-u https://hisco.instances.heirloomcomputing.com/rest/2013-03-01/licensecheck \
-f licensing.properties

The licensing.properties file results from this process in the current directory. You send this with your product and ask your customer, or copy its contents into an e-mail you send to your customer. Instruct them to create a file 'licensing.properties' and to place it in the home directory of the user(s) running the application or the application server's user's home directory or (if deployed under an Application Server or Servlet Engine) the location of your application.

Shown here is the ability to include the product code directly in the subscription file. However, the product code sent as part of the license checking API or on subsequent command lines will override this value.

Check License

Carry out a license check for the default product and a "transaction count" of 1 with the following command:

java -jar HCILicensing.jar

Check a license for a different product (or feature of a product) by explicitly setting the product-id for that product. Include an explicit transaction count if your application is batching transaction counts.

java -jar HCILicensing.jar -p 87654321-1234-4321-1234-210987654321 -c 12

The command line utility will return a "License is OK" if the check was OK, or a reason why the check did not work. It also sets the return code of the command (0 for OK). A license is OK if the customer has been granted some license for the given product and it has not expired. Multiple licenses may be granted to a customer for the same product with different begin/end dates or enable/disable indicators. The license checking process will find the first valid one and tally the transaction count against it.

Note that these license checks are subject to the "check every" period specified for the restriction associated with the license. To reduce network traffic the command line utility and the API will return immediately within this period without consulting the LaaS server if the prior check was OK. The transaction counts are tallied locally in the license properties file and the file is guarded against tampering. You can require that the license check be done against the server (-r option). A tampered file may be one in which the transaction count has been changed or it has been restored from a prior saved copy. In this case the error about the "signature doesn't match subscription / mac address". Your customer should request a license reset which the administrator can do with the Admin Panel. Of course, that process should go through your customer service center to ensure that your customer is not attempting to work-around the licensing and transaction mechanisms.

Note: Your superadmin account can "relax" these license checking restrictions by changing the appropriate fields in the restriction record through the Web services interface. You can relax the "signature"

Verify License

You can verify whether a license is currently up-to-date without necessarily checking it with the license server. Issue

java -jar HCILicensing.jar -f ../../elasticcobol.properties -l -p hpaas-ebp-rts

to generate a report on the status of the Elastic Batch Platform license:

Heirloom Computing, Inc. Licensing-as-a-Service
Cloud Based License and Transaction System

License not checked against server
   Product:hpaas-ebp-rts
   License Server Will Be Checked: 2014-02-20 23:03:59
   Grace Period: 29days 23hours 48minutes
   Queued Transaction Count: 0

If a license is still within the "grace period" you can require that the HCILicensing command verify it against the license server. Based on the license type this may reset the grace period. Issue

java -jar HCILicensing.jar -r -phpaas-ebp-rts

License File

The license properties file is created with the command line program contains at minimum the subscription_id, email_address, license_domain and check_service elements. The product_id may be supplied as a parameter to the command line or API method.

#Heirloom Computing, Inc - License and Transaction Checking
#Fri Mar 01 13:16:28 PST 2013
check_service=http://myco.instances.heirloomcomputing.com/rest/2013-03-01/licensecheck
license_domain=myco
645d7dce-1b35-49f2-adb4-d027e1abc165.count=\u0001\u0000
email_address=myco@myco.com
product_id=645d7dce-1b35-49f2-adb4-d027e1abc165
subscription_id=00000000-8181-616d-6b72-61686e796569

A better way to see the current status of the license properties file on the client system is to use the HCILicensing command's -l option. Here is an example on a product with a 31-day "check every" restriction:

mnh@pineapple:~$ ./HCILicensing.jar -f licensing.properties -r -c 2 -l
Heirloom Computing, Inc. Licensing-as-a-Service
Cloud Based License and Transaction System

License is OK
License Properties File: licensing.properties
Product: 645d7dce-1b35-49f2-adb4-d027e1abc165
License Server Next Checked: 2013-06-08 23:18:07
Grace Period: 1month 23hours 59minutes
Queued Transaction Count: 0

mnh@pineapple:~$ ./HCILicensing.jar -f licensing.properties -c 2 -l
Heirloom Computing, Inc. Licensing-as-a-Service
Cloud Based License and Transaction System

License is OK
License Properties File: licensing.properties
Product: 645d7dce-1b35-49f2-adb4-d027e1abc165
License Server Next Checked: 2013-06-08 23:18:07
Grace Period: 1month 23hours 58minutes
Queued Transaction Count: 2

mnh@pineapple:~$

The output asks that the default product have its transaction count increased by 2. The first command includes the "require" -r option that forces a check with the license server, sends any queued up transaction counts (plus the requested -c 2). The license was checked and was "OK." The -l option reports that the "check again" indication is reset to 31 days from today. One minute later, a second HCILicensing.jar command is issued which shows the date the (unforced) check will be made and a period of time from now until that date in years, months, hours, minutes and seconds (reported precision is 3 elements). Because the license server was not contacted the -c 2 transaction count is encrypted and stored in the license properties file and is shown as the "Queued Transaction Count."

Proxy Checker

When Internet communications are not allowed from the system under license control, a separate computer that is connected to a network can serve as a proxy license checker. The proxy checker will use the LaaS Command Line utility to transmit transaction counts and check license validity. Follow this process:

Use the command-line utility on the client machine with the -x (export) operands to create a proxy.txt file
Copy the proxy.txt file from the client system using a secure transfer mechanism to the proxy-checker machine
Upload the transaction count to the LaaS Server and verify the license and expiration date with the command-line utility on the proxy-checker machine. Reference proxy.txt with the -f option. Require that the update take place (-r option) but don't include any additional transaction counts other than what's in the proxy.txt file (-c 0 option). This process updates the proxy.txt file with updated license information.
If "License is OK" is printed by the command line utility then reverse the steps. Securely transfer the proxy.txt file back to the client machine.
Use the command-line utility on the client machine with -i (import) operand to merge verified license information with the then-current transaction count information on the client.

You must have one proxy checker for each client application server -- do not combine multiple exported license properties files into a single proxy checker license file before transmission to the LaaS (limited time restriction). You can import a file only once. You cannot tamper with (or edit or restore from backup) the license properties file, the export file, or the import file. If you do an error occurs during one of the steps and you will have to ask that the license be reset by and regenerate the license properties file. The client system may continue to accumulate transactions while the above steps are performed -- transaction counts will be preserved and uploaded the next time. The "check every" indicator will be reset according to the license restrictions by the proxy machine based on the current day and time. A "grace period" of one month would be accomplished with the license restriction "check every" setting of 2,678,400 seconds (31 days). The customer must go through the "proxy checker process" before the end of the period. The command line can be used to list (-l option) when the license server will next be contacted unless a new interval is imported. When the proxy checker uploads the license count the 31-day period of client checking will begin at that time. This is a "grace period" in that if the license is expired it won't be verified again until the next upload. So, the license should be required to be checked (-r option) just prior to the expiry date to obtain the full "grace period."

In order to keep the license & transaction system in sync and export/transfer/upload must be followed by a transfer/import in order for later export/transfer/uploads to work correctly. Think of a "token" representing the ability to contact the license server from being passed from the client (application) machine to the proxy-checker. It, in turn, uses that token to sync with the LaaS server. That token must be passed back to the application by way of the secure transfer and import process. Otherwise, a subsequent export and upload will result in the message "Your signature does not match for this subscription / mac address".