Product Portal

Anonymous trial licensing (where the end user downloads your software or installs it from a CD/DVD and is not required to interact with your operations personnel in order to obtain a trial license (unless you want to require them to do so)) can be accomplished as follows:

Externally visible functionality as experienced by the end user (assumes the end user’s email address is used as their userid):

The first time the user attempts to activate your software for trial licensing, they are required to enter their email address in a form / provide it in a configuration file.  The activation succeeds, and the software continues to run until the expiration period. In the interim, or in parallel, if the end user attempts another installation and activation under the same email address, the activation fails, and your sales personnel are alerted in real time with details.  Should your sales personnel decide to allow multiple evaluations, they can locate the evaluator’s license on the license server and enable it for multiple trials.

License schema: you would maintain a “trial licenses” named-user (not anonymous-user) domain that has a maximum checkout duration equal to the maximum trial period.  The domain would have an administrator user account with a password known to your application.

Application: your application code would, at the time of trial activation, first attempt to register the customer email address or equivalent as a named user in the Orion server with a quota limit equal to the maximum number of serial trials permitted on that machine / email address (typically 1).  This would be via the “registerUser” API call in the Orion client library, under the auspices of the domain’s administrator account.  If registration fails because the user already exists, it is not (yet) an error; however, the current state of the user license is left unperturbed.  Following registration, the trial license is activated via a “checkout” followed by a “saveCheckoutState” to save the activation record.  The checkout will fail if the quota limit recorded in the server is exceeded.

The above protects against reusing an email address for multiple activations, but requires the user to input an email address.  A simplification that does not require the user to input anything is to introspect the user machine’s machine fingerprint and use that as the named-user name instead.  Then, multiple serial activations on the same machine are prevented.

Of course, none of the above approach will prevent a determined serial evaluator from simply using different email addresses on multiple machines; the intent is to make it harder for serial evaluators and to limit their ability to do so, as well as utilize a mechanism that enables tracking and accountability (the email address).

Orion lets you specify an explicit username at the time of checkout, even if the checkout is from an anonymous-user domain.  This is to simplify management and auditing.  The active user list that is displayed under the anonymous-user domain in the administration UI will display the names specified by the checkouts, and audit trail entries will be tagged with these explicit usernames.

There are a couple of points to be aware of:

1. If no explicit username is provided by the application, the Orion server invents a unique name beginning in “anon”.
2. In the application, if you are using the default domain name, normally you’d pass in a null value for the domain name.  However, in this scenario, since there are two default domains (one for named-user and one for anonymous-user), Orion assumes you mean the default named-user domain if you specify an explicit username.  Therefore, when specifying explicit usernames for checkouts from the default anonymous-user domain name, it is necessary to explicitly provide the default anonymous-user domain’s name (“default_nuser”).

Assuming you’re referring to anonymous-user floating licenses (where you don’t pre-register users and optionally assign them passwords), you can achieve this objective in one of the following ways:

• If feasible and realizable, use the host access control mechanism.  Your application can qualify the machine name with an identifier that is uniquely associated with your enterprise customer.  A simple example is to qualify the machine name with the network domain name (works only for on-site users), or with a designated and configured enterprise customer ID.  On the server, your administrator can define a host access control rule that permits access to an enterprise customer’s domain only for machine ID’s having the enterprise customer’s network domain name or enterprise customer ID.
• Use an encoded domain name that is hard to guess – in essence a “password” known only to your administrator and your end customer’s administrator.
• Define an auxiliary “pool authorization” named-user domain and register under the domain a named user together with a password.  Your application can be coded to first perform a password-qualified named-user checkout from the domain’s representative named user under “pool authorization”, and only if that succeeds, proceed with the anonymous-user checkout.  Of course this only solves the problem of access from your specific application.

Of course, if you’re offering a floating named-user model to your customers, the named user can have a password for authentication.  Nevertheless, even in this scenario, it is desirable to have an enterprise-wide identification / authentication mechanism.

The considerations as well as the solution are identical to the case for hosted floating licensing, discussed in the previous question.

This is automatic, as Orion always tracks usage – all you need to do is to ensure that the corresponding license  is not set to quota limited, so that no limits are specified and therefore no out-of-quota error is raised.   You can even set an initial usage count if you don’t want it to start at 0.  You can also reset the count at any time, for example to start a new billing cycle.

If you want to define a soft limit and alert your customer / be alerted in the event the soft limit is exceeded without preventing the user from continuing to use your product or service, you can configure the license to be quota limited, and set the quota limit value to the soft limit, and define a generous quota expiration grace parameter.  Then configure your event alerter to email the necessary alerts in the event that the soft user limit is exceeded.

When you generate your redistributed Orion product license, set the ILS:INHIBIT-DB-RESTORE system option to true.  This will prevent your customer from being able to restore database backups and thus rolling back usage state.

Of course, this also means your customer’s sole resort for recovering from a corrupted database is to reinstall the Orion database from a gold master and obtain a new license from you.

It is far more convenient and secure to offer usage based enterprise licensing as a hosted license pool.

When Orion is redistributed, subscription licensing is implemented by re-issuing product licenses at the start of each subscription period.

Normally, updating the product license does not reset the cumulative usage count, so ordinarily you’d have to issue subscription licenses with progressively higher quota limits, which is both cumbersome and inaccurate because you don’t know what the usage count was at the end of the prior subscription.

The problem with quota limits is avoided by specifying the ILS:RESET-QUOTA-USAGE-ON-PROD-UPD system option to true in the product license.  This will automatically reset the quota usage to 0 at the product license and default domain levels.  Your end customer’s administrator has the appropriate privileges to reset current quota usage levels of individual domains and named users.

 

You can define named-user licenses to be “relative time-limited” instead of “absolute time limited”, and specify a number of days to expiration.  For example if you created a 30 day relative time-limited license 1 year ago, and the license was activated by a customer 28 days ago, then the license would expire 2 days from today.

Similarly, you can define domains used for floating licensing to be relative-time-limited, so that the expiration date for a specific domain is determined upon occurrence of the first checkout from it.

You can force the user to stay checked out for a minimum duration by configuring the “minimum checkout duration” parameter at the domain level under which the users are registered.  Then your proxy checkout on your cloud server application on behalf of the user, which will be proxy-node-locked to the user’s mobile device via the server-side session handle parameter, will not be able to perform a successful checkin until the minimum duration has elapsed.  Note that this is a configuration step – no application integration programming is required.

You don’t need to perform the integration at the thin-client device level.  Furthermore, the standard Orion product distributions don’t provide client libraries for mobile devices, not even for Android (even though it is based on Java).

Because your devices connect to your server application, all you need to do is to integrate your server with the appropriate Orion client library, and perform the appropriate checkouts by proxy.  The Orion client library allows you to specify a logical machine name (ie. it is not required that the parameter be derived from the machine on which the server is running) as well as a logical user name (ie. it is not required that the parameter be derived from the operating system user account under which the server is running).  Therefore, for fully connected mobile applications, anything that would ordinarily be done on the mobile device can be done on the server by proxy.  This includes specification of a machine name corresponding to the remote device, which could map to its IP address or server-side session handle.

When the application and the license server are on separate machines, the two systems’ clocks might not be 100% precisely in sync right down to the millisecond.  Therefore, in the restoreCheckoutState() API call used for activation, it is important to specify a non-zero value for the time-tolerance parameter – at least a few hours is recommended for offline activation.  Even for local operation, a non-zero time tolerance parameter should be specified in order to account for clock drift over time.

Of course, the first place to check is the machines’ system clocks themselves, to verify that they are in fact in sync.  In particular, verify that you are checking the combination of the time and timezone settings.  Note also that system clock checking is not sensitive to time zones.  For example, if your application is running on a machine whose clock shows noon Pacific Standard Time, and the license server is running on a machine whose clock shows 3pm. Eastern Standard Time, nothing is amiss and the time tolerance is not required to be greater than 3 hrs merely owing to the timezone differences.  But if either machine has the above times with the wrong timezone setting (eg. both are at Pacific Standard Time but the machine in San Francisco shows noon and the machine in New York City shows 3pm.) then you will of course encounter the error.

That’s most likely because your checkout is specifying a common checkout machine ID and session ID combination for all the checkouts.  The semantics of a checkout are that if a checkout is active and you perform another checkout with the same machine ID and session ID, Orion merely extends the current checkout.

The remedy is to assign a separate session identifier parameter for each distinct user.  This could be the operating system thread ID, for example.  Alternatively, if you have the information available, you can specify the user’s remote client machine as the machine ID.  In either case, you’re defining a unique (machine ID, session ID) parameter pair for each distinct user.

This will only happen for (a) domain and user level option updates, for redistributed Orion servers for which you (as an Orion License Server customer) explicitly generated and distributed product licenses, and (b) user-level option updates while logged in as domain administrator for the corresponding domain, for hosted Orion servers where you defined the ILS:RESTRICT-DOMADMIN for the domain.  It will happen under any of the following scenarios:

1. the end customer’s administrator attempts to change the value of a string-valued option in any way
2. the end customer’s administrator attempts to increase the value of an integer-valued option
3. the end customer’s administrator attempts to add a new option of their own

The restriction is intentional.  The product options control available features.  Integer-valued product options define feature levels (the higher the value, the higher the functionality level).  The above restrictions enable you to prevent your end customers from upgrading the functionality you have defined for them, and at the same time permits your redistributed-Orion end customers to define more-restricted sub-policies for domains that they set up (which they are allowed to do).

By default, the Orion server is configured to access its embedded database in “in-process” mode.  In this mode, only one process may access the database files.  If you have multiple Orion server instances simultaneously active and configured to reference common database files in in-process mode, then only requests to the first-accessed Orion server instance will succeed – any request to the second Orion server instance will yield the “database already in use” error.  The same is true when the entity accessing the database files is another process running an Orion administration utility, whether using Orion’s command line tools or your own utility built on top of the Orion administration APIs.

The simplest solution to bypass the issue is to configure the database for access in server mode, as explained in the “Setup, Management and Deployment Guide” chapter of the Orion server product documentation.  There is however a drawback to configuration in server mode – the Orion server’s backup management job will be unable to perform backups on such a database.  It is therefore preferable to architect the system to avoid the need for multiple processes to access a common Orion database.

It should also be noted that sometimes abnormal termination of an Orion server process, especially on Windows, leaves a spawned Java process running and maintaining its lock on the database.  When this happens, attempting to start and use a new Orion server instance will produce this error as well.  The remedy is to identify the zombie process (a “java” process) and force-kill it, or at worst reboot the server machine.

The root cause is most likely an out-of-memory condition in the Orion server.  This could be an out-of-physical-memory condition, or an out-of-Java-virtual-memory condition.  Unfortunately, the Java runtime isn’t always very good at raising a straightforward and understandable “out of memory” error (or better yet, an early warning alert) under extreme conditions.

The root cause for the out-of-memory condition may be any of the following:

1. A straightforward out-of-Java-memory condition owing to insufficient memory for your user license population and / or audit trail retention period.  For your workload, the default Java virtual memory setting (or a setting you explicitly specified) for the Tomcat servlet engine or other J2EE application server on which you have deployed the Orion server application needs to be increased.  Refer to the “Setup, Management And Deployment Guide” chapter of the Orion server documentation for instructions on how to tune the Java virtual machine memory setting.  Ensure that your Java virtual memory setting is comfortably below the available physical memory on the machine.  For extremely large user license populations in the millions, a 1GByte virtual memory setting is ample.  For more common user license populations in the 1000′s or 10′s of 1000′s, a 256 Mbyte virtual memory setting suffices.  And for simple low-end configuration (for example what you’d use for conventional enterprise floating licensing), the default memory configuration is ample provided your audit trail cleaner job is enabled to run on a reasonable schedule (see below).
2. A disabled or mis-configured audit trail cleaner job.  If the audit trail cleaner job is disabled or its frequency is curtailed, or the audit retention period is set to an excessively long duration (eg. years), audit trail entries accumulate over time until any attempt to perform searches or run reports on the audit trail bring the server to a grinding halt.  The remedy is to enable the audit trail and ensure it is configured to run with an appropriate frequency.  Also ensure that the cleaner does not retain an excessive number of records online.  Note that the audit trail cleaner can be configured so that cleaned-out audit trail entries can be archived in sequential files, and that the archive retention period is limited only by the amount of disk space available.

This means the license database was moved from its original installation after an Orion server license enabling directory via the ILS:LOCK-DIR system option was installed and active.  By default (ie. if the system option is not specified at the time of license generation), directory locking defaults to “deferred”, which means the directory is locked upon the first command from an application.  Directory locking is for the ISV’s protection when redistributing Orion, as it protects from multiple licensed installations on the same machine and under the same operating system user account.  See the “License Administration User Guide” chapter of the product documentation for the semantics of directory locking.

For fuzzy machine fingerprinting, both the Orion server and the fingerprinting utility (which are implemented in Java) rely on C/C++ fingerprinting library that is included with the Orion server distribution.  But the C/C++ library does need to be installed.  In particular, the DLL / shared-library (whose name ends in “.dll”, “.so”, “.dylib” depending on your platform) needs to be reachable from the PATH / LD_LIBRARY_PATH / other platform-specific environment variable.  And if the Java code can’t successfully load the library at the time of fingerprint generation / checking, it gracefully degrades to generating / checking a platform-independent hostname-only fingerprint.

The root cause for the symptom is that in instance the environment was set up correctly for loading the C/C++ fuzzy fingerprinting library and in the other case it wasn’t.  For example, the fingerprinting utility may have generated a complete fingerprint because the logged-in user had the correct environment, whereas the Orion server may not have been able to find the fingerprinting library because its operating environment may not have been configured correctly.  Check both environments, and verify the node-lock fingerprint file that you receive from your customer prior to generating their floating license key.

Of course, if you use Orion product activation technology for distributing floating licenses to your customers (available with the latest Orion server release), the above will not be an issue since node locking is hidden and automatic.

When the Orion server uses its embedded database in its recommended in-process configuration (which is also the configuration for the default zero-configuration database), part of the database is cached in memory for access by all threads in the servlet engine under which the Orion server application runs. However, the servlet engine maintains a separate memory heap for each configured servlet application context.  Both the Orion runtime access and the built-in Orion admin UI operate under a common “ils” servlet application context.  If an external service is added, it too must be configured to operate under this same servlet context, otherwise the two contexts won’t be able to see a common state.  This is true even when using Agilis’ old SOAP-based Administration Web Services, although not an issue for Agilis’ new REST-based Administration Web Services.

The recommended fix is to configure the servlet engine so that everything is under Orion’s “ils” servlet application context, per standard J2EE procedures.  If for some reason this is not an option, the issue can be worked around by configuring the database to operate in server mode – instructions for how to do so are in the “Setup, Management And Deployment Guide” chapter of the Orion server product documentation.

This means that your administration privileges don’t allow you to cancel checkouts.  In a hosted environment, this is because the domain your’re logged in to as domain administrator has the ILS:RESTRICT-DOMADMIN system option set.  In a redistributed environment, your customer may get this if you set ILS:CANCEL-CHECKOUT-PRIV in their Orion key to an administration level and your customer logged in as a lower-privilege administrator.  For further details, refer to the respective system options defined in the “License Administration User Guide” in the Orion server product documentation.

This means that the user being dropped / disabled is currently in a checked-out state, and your administration privileges don’t allow you to cancel checkouts – so the operation is not allowed to proceed.  In a hosted environment, this is because the domain your’re logged in to as domain administrator has the ILS:RESTRICT-DOMADMIN system option set.  In a redistributed environment, your customer may get this if you set ILS:CANCEL-CHECKOUT-PRIV in their Orion key to an administration level and your customer logged in as a lower-privilege administrator.  For further details, refer to the respective system options defined in the “License Administration User Guide” in the Orion server product documentation.

The remedy is to either wait for the checked-out users to check their licenses back in, or (if it is an option) perform the administration operation with a higher level privilege that is permitted to cancel checkouts.

This means that the domain being dropped or disabled currently has one or more checked-out users, and your administration privileges don’t allow you to cancel checkouts.  This can only happen in a redistributed environment, and your customer may get this if you set ILS:CANCEL-CHECKOUT-PRIV in their Orion key to an administration level and your customer logged in as a lower-privilege administrator.  For further details, refer to the respective system options defined in the “License Administration User Guide” in the Orion server product documentation.

This means that your system administration privileges don’t allow you to cancel checkouts, and the product you are attempting to drop or disable has at least one domain that has at least one user checked out.  This can only happen in a redistributed environment, and your customer may get this if you set ILS:CANCEL-CHECKOUT-PRIV in their Orion key to NONE.  For further details, refer to the respective system options defined in the “License Administration User Guide” in the Orion server product documentation.

The remedy is to wait for all checked-out users to check their licenses back in before retrying.

Most likely, customers having difficulty connecting to your license server over the Internet have a DMZ or an HTTP proxy server based firewall configured in their corporate environment.  They need to be using the appropriate license server URL specification that specifies their http proxy server.  If they installed (and, if needed, configured) an Orion license proxy server in a DMZ at their premises, then the license server URL needs to be specified to route through the Orion license proxy server.  Hopefully your developers ensured the license server URL specification was parameterizable so it can be set appropriately by your respective individual end customers, and hopefully your development team made the proxy configuration information available as part of your product documentation.

For complete details on the syntax and semantics of license server URL specifications as they pertain to HTTP proxy servers and / or Orion license proxy servers, please see your product documentation, or (if this information didn’t make into your product documentation) ask your developers to see the “ISV application development guide” and “Orion client library API reference” chapters of the respective client library SDK.  If using the Orion license proxy server, also see the “License proxy server user guide” chapter of the Orion server product documentation.

The license database will increase over time because the audit trail is populated with events over time.  Ensure your audit trail cleaner job is enabled to run on a regular schedule (its default is a 24-hour period).  For details, see the “Job control system administration guide” chapter of the Orion server product documentation.

If the audit trail is growing too quickly and / or you need to maintain an unusually long online audit trail retention period, you can slow the population of the audit trail by enabling auditing for just the products, domains and named users of interest, and turning it off for all others.  See the “License administration user guide” chapter of the Orion server product documentation for details on how / where to set the ILS:AUDIT system option to achieve this objective.

Most likely, the redistributed Orion server was using the default zero-configuration mode but was not started while positioned at the expected ils2.0/web/bin folder, so it could not locate the default database at the expected “../database” relative-path folder.  The remedy is to shut down Orion, position to the above folder and then start Orion again.

Another possible explanation is if a service with name “default” was defined in the wdoprops.ini configuration file in the user home folder, but its mapping was incorrectly specified eg. to a non-existent folder.

If the corresponding product’s Orion license key was node-locked or directory-locked, the Orion license database cannot be relocated – a new Orion license needs to be issued.

The above is when the Orion server is license-protected with EasyLicenser.  If it is license-protected with a hosted Orion server using product activation technology, a node-locked installation can be relocated by disabling the product(s) prior to shutting down and relocation, and then re-enabling the product(s).  The rest is automatic.