• Antelope Release 5.8 Linux CentOS release 7.4.1708 (Core) 3.10.0 2018-04-25

 

NAME

notes_licensing - antelope software licensing

DESCRIPTION

This describes the licensing used by Antelope programs and libraries.

BACKGROUND

The Antelope software package is a hybrid of closed and open source code and commercial and public domain intellectual property. Most core functions in Antelope are closed source with protected intellectual property. This protection comes about, in part, by the use of software licensing which restricts where, how long and to what extent the various proprietary Antelope programs and libraries can be used.

Software licensing can be accomplished in a variety of ways. We decided many years ago to make the licensing as simple and as inclusive as we could. One method of licensing is to base it upon the identity of the computer host upon which the software is running. We refer to this kind of licensing as node licensing. An Antelope node license enables a particular computer host to run as many instances of Antelope as desired by as many different users as desired. With a node license, it does not matter where the computer host is located or what its ip address may be. This kind of licensing is perfect for portable computers like laptops which will move around and have different ip addresses assigned through DHCP or other mechanisms.

Another kind of licensing used by Antelope is ip-based licensing. An Antelope ip-based license enables any host computer with a particular ip-address or belonging to a particular subnet. This kind of licensing is convenient in situations where the ip-addresses are fixed but the computer hardware may vary. As with node licensing, ip licensing normally allows as many Antelope instances and users as desired. This is not particularly convenient for mobile computers which will have varying ip-address assignments.

NODE LICENSES

Antelope node licenses provide a simple way to enable particular computers to run Antelope. For many years this has been the most popular form of licensing. However, node licensing requires that the computer host be uniquely identifiable. In the early years of Antelope this was never a problem since the first Antelope distributions ran only on SUN Microsystem computers and all SUN computers have unique hardware identification serial numbers that are easily software accessible without root permissions. We also have had no problems with computer host identification when we ported Antelope to Apple/MacOSX systems. Like SUN, Apple brands all of its hardware with software accessible unique serial numbers.

Unfortunately, hardware identification was and continues to be a persistent problem with PC-based Linux systems. Although some PC manufacturers brand their computers with unique serial numbers, this is not at all consistent. Also, the manner in which hardware serial numbers can be obtained by the software is not standardized or even available in some cases, as it is consistently with Apple hardware.

Another challenge for us has been the proliferation of virtual machines. Although a virtual machine normally runs Linux, it is possible to run MacOSX virtual machines as well. Unfortunately, virtual machines are antithetical to node licensing. The reason is that virtual machines by their nature have no unique identification that is not easy to modify by the user. Virtual machines hide the underlying hardware details from both the application programs and the user. Most virtual machines can be perfectly cloned so that many copies with the same exact identification can be run at the same time at different places. This situation completely defeats node licensing.

ANTELOPE PC/LINUX NODE LICENSING

Starting with version 5.3, Antelope node licensing has been changed so that only systems with real hardware serial numbers can obtain node licenses. For Apple systems, this is no different than previously. However, for PC Linux systems this means that only systems with hardware serial numbers and software access to those serial numbers will be given Antelope node licenses. The rest of this section applies ONLY TO NODE LICENSES ON PC/LINUX SYSTEMS.

Starting with Antelope 5.8, which was built to run on RHEL/CentOS version 7, the Antelope licensing modules will attempt to obtain Linux hardware serial numbers through the Antelope amd(1) daemon. The daemon process must be previously configured to be started at boot time using the S99amdd(8) scripts. These scripts must be executed with root permission. These are normally executed automatically during installation.

In previous versions of Antelope, the system serial numbers were obtained through the standard Linux daemon hald. This daemon process was normally configured to be started at boot and provided a software method for obtaining system serial numbers without needing root permission by the application processes. Unfortunately, starting with RHEL/CentOS version 7, hald is no longer in the Linux distributions. The Antelope daemon amd(1) replaces the functionality of hald. Both amd and hald must be run with root permission as daemon processes started at boot time.

Note that not all hardware manufacturers brand their computers with serial numbers and not all hardware manufacturer serial numbers can be obtained through amd(1). Therefore, even if you are running RHEL or CentOS 7.x on your system and amd, it may not be suitable for an Antelope node license. After installing Antelope and making sure that amd(1) is running, you can check out your system as follows. 


arapaho% sudo $ANTELOPE/bin/ald_getsysserial
[sudo] password for danny:
CGTGSW1
If you don't get something that looks like a real serial number, then you will not be able to get a node license for the system. The ald_getsysserial(1) command must be run as the root user. It does not communicate with the Antelope amd(1) daemon. This is the first serial number check you should try providing you know the root password. If you do not get a valid serial number, then you will not be able to get a node license for the host.

If ald_getsysserial(1) returns a valid serial number and you have configured amd(1) to be running using the S99amdd(8) scripts, then you can check your system as follows. 


arapaho% antelope_admin -action amd getid
amd getid ok and = CGTGSW1
If you don't get the same serial number as ald_getsysserial(1), then the most likely reason is that amd(1) is not running. Note that you can get the system serial number through amd(1) without root permission. This is how all of the Antelope applications get the system serial number for node license verification.

Virtual machines are much more of a problem. For the reasons we gave previously, BRTT WILL NOT ISSUE NODE LICENSES FOR VIRTUAL MACHINES. If we had a way of being able to tie a virtual machine to the underlying hardware serial number, we would issue node licenses for virtual machines, but we know of no way to do this.

ANTELOPE INTERNET LICENSING

Because of the problems with node licensing for certain Linux systems and for virtual machines in general, we put a substantial effort into revamping our internet based licensing. Most of the rest of this document will discuss our new internet licensing system.

The basic concept behind Antelope licensing is to be able to connect a particular running instance of an Antelope program with a particular customer who purchased Antelope. Effective node licensing is one way to do this. Another way is to look at the computer's assigned ip-addresses to see if one of them corresponds to the customer's public ip-address. In the past the assigned ip-addresses were obtained through ifconfig, a Unix system program that can be used to list all of the currently configured ip interfaces. This method worked for many years until the advent of more complex network configurations in which the public identity of a particular computer host was unknown to that host. This method has also recently come under attack by hackers who were able to set up fake ip configurations for the purpose of fooling the licensing software.

In the new internet licensing system the local host ip-addresses are not obtained by running ifconfig. Instead, the host computer ip-address is obtained by connecting to one of several BRTT license servers running at various facilities. These license servers send back the ip-address that they see at their end of the connection. By definition, this ip-address must be a public routable ip-address. This outside public routable ip-address is used by the local host running Antelope to effect the licensing. For this system, computer hosts with private ip-addresses will be seen on the outside with either the facility's router address or another outside address through NAT. This provides a mechanism for providing effective internet licensing even in secure facilities situations with strong firewalls.

Because licensing is checked by every Antelope program when it starts up, we have provided a caching mechanism so that the returned ip-address is stored in an encrypted form on a file on a local filesystem. As long as the cache file exists and the file is not too stale, subsequent license requests will use the cache file instead of opening connections to one of the remote license servers. It is possible to configure the licensing system so that the license cache file can be stored on a non-volatile area that should survive reboots. We also provide a special proxy program that can be used to deal with issues relating to firewalls and connectivity.

INTERNET LICENSING ADMINISTRATION

To reiterate a point that may have not been obvious, there are no administration issues for node licenses. As long as your computer hosts can be uniquely identified, the node licensing works exactly as it has always worked. If your computer hosts cannot be uniquely identified, we will not issue node licenses for those hosts. License administration only relates to the use of internet licenses.

We have put considerable effort into a default scenario in which there will be little or no administration tasks required for internet licensing. In our default scenario, your host computers have complete access to the outside internet, or you can easily configure your firewall to provide access. If that is the case for you and if your outside internet response is average in its speed, then you can probably use internet licensing with no administration tasks, except in some rare situations where you may need to repair corrupted license cache files. Most of the license administration tasks relate to situations where your host computers have poor outside internet access, either because of infrastructure or because of strict security.

In order to describe the internet license administration tasks, we should start by describing how the internet licensing works in detail. When a licensed Antelope program or library starts up, it first looks at your $ANTELOPE/data/pf/license.pf license file to see what kind of license you have. If it is an internet license, then the program will first attempt to get its outside internet address from a license cache file. By default, the license cache files are stored in a directory, /tmp/.lcache_1.1. Inside of that directory are two files, a lock file, lock, and the encrypted license cache itself in fl. The lock file is to keep multiple Antelope processes from trying to write to the cache file at the same time. If the cache files exist, and there are suitable read permissions, and the file contents are good, meaning that they can be decrypted properly, and the age of the last update to the cache file is not too old (too old means no more than 2 days), then the ip address stored in the cache is used as the host's external ip address and it is compared to the licensed address in $ANTELOPE/data/pf/license.pf. If the cache files do not exist, or if there are not suitable read permissions, or the file contents are not good, or the age of the last update to the cache file is too old, then the Antelope program or library will attempt to connect to one of our license servers to obtain the external internet address for that host.

Our license servers run as TCP/IP daemons on several independent hosts that should be generally available to anybody on the internet. We run several license servers on hosts in our Boulder office, as well as several servers on cloud hosts at sites external to our office. All of the servers are identical and any one of them can properly service license requests. In order to keep an up-to-date list of the available license server ip-addresses, we have a list on our web site at http://www.brtt.com:80/addresses.txt . 


arapaho% wget -q -O - http://www.brtt.com:80/addresses.txt
****BRTT ADDRESSES****
162.242.217.36
23.253.124.82
23.31.71.129
23.31.71.136:80
We can see here four license servers. The default port is 6405. We have one license server running in our office on port 80, normally used for web servers, since that port is often not blocked by firewalls. The Antelope licensing software will automatically connect to our web server to obtain this list. It will then try each of the addresses to see if it can get a proper response. The first license server that produces a proper response will be used. A proper response is one that decrypts properly and has an age that is not too far in the past or future. It is important for your Antelope hosts to maintain reasonably accurate local system clocks (accurate to within tens of minutes). The decrypted result is the apparent external ip-address for the host making the request.

If an ip-address is obtained from one of our servers, then it is compared to the licensed address in $ANTELOPE/data/pf/license.pf. If an ip-address is obtained from one of our servers, an attempt is also made to automatically update the license cache file. If any of the license cache files do not exist, then attempts will be made to create these files. If an ip-address cannot be obtained from any of our license servers for any reason, then if the license cache file was ok except that the age was too old (more than 2 days), as long as the age is not more than 30 days, a warning is printed and the cached internet address is used. If the license cache files cannot be read or the cached response is more than 30 days old, then an error message is printed and the program will not run. There is a throttle to keep these automated license server request attempts from happening too often in situations where the cache is stale (older than 2 days) but not yet older than 30 days.

This describes the default internet licensing behavior. If that behavior is acceptable to your operation, then there should be no required regular administration tasks. However, there are situations where infrequent administration may be required. In particular, these tasks relate to maintenance of the license cache files.

ADMINISTRATION OF LICENSE CACHE FILES

The license cache files are meant as a free ticket for most of the Antelope processes to obtain their external ip-addresses without the need to access our license servers. If everything is set up properly, the time to read and decrypt the cache files is miniscule. This works great as long as the license cache files do not become corrupted. If they do become corrupted it is sometime necessary to fix them manually.

The license cache file directory, /tmp/.lcache_1.1 by default, is usually created automatically by the first Antelope process that needs to access it. That means the owner will be whoever is running the Antelope process when the cache file is first accessed. The licensing software will automatically set the permissions for /tmp/.lcache_1.1 to drwxrwxrwx so that everybody has read and write permission in that directory. These permission settings are not effected by umask settings. The two files in /tmp/.lcache_1.1 have permissions automatically set to -rw-rw-rw- so that everybody has read and write permissions for the cache lock file, lock, and the cache file, fl. As long as somebody does not come along and change these permissions outside of the licensing system, the cache files will work ok. If the permissions should get changed, for instance if the write permissions are removed, then it may become necessary to recreate the files. If you are the owner of the files, then it may be possible for you to remove the files completely so they will be recreated with the proper permissions automatically the next time they are accessed.

Another way to maintain the license cache files is through the use of the program antelope_admin.

The license cache file directory is automatically created if needed whenever the lock file or the license cache file is created. Typically, in order to remove and recreate the files you would do the following. 


ruper% antelope_admin -action lockrm
lockrm ok

ruper% antelope_admin -action cacherm
cacherm ok

ruper% antelope_admin -action lockcreate
lockcreate ok

ruper% antelope_admin -action cachecreate
cachecreate ok

ruper%
Notice that this will not fill in the cache file with the ip address, but it will make sure the cache files exist and have the proper permissions. If you encounter any error messages then the most likely reason is due to ownership and/or permission problems that may require root login to fix. If you login as root, the best thing is to simply remove all of the files and then recreate them with antelope_admin as a non-root user. Keep in mind that cache file administration using antelope_admin is usually not necessary.

Note that all of the license cache files must reside on a locally mounted file system. There are also checks to insure the files have not been copied or moved from some other location. The files need to be created and maintained directly with the Antelope licensing software. if you attempt to copy them or move them or edit them or try to put them in a remotely mounted filesystem you will encounter problems.

LICENSING CONFIGURATION

All of the Antelope licensing software has been written so that it does not itself require licensing and does not use any of the Antelope libraries. All of the Antelope licensing software uses a consistent set of environment variables to configure its operation. Following is a list of the environment variables used to control the licensing software.

These environment variables can bet set in the normal Unix manner, or they can be set in the $ANTELOPE/data/pf/license_env.pf file, or in a license_env.pf file along the path specified by the PFPATH environment variable. Following is an example of setting an Antelope licensing environment variable in license_env.pf. 


ruper% cat /opt/antelope/5.3/data/pf/license_env.pf

ANTELOPE_LICENSE_SERVER_ADDRS		198.72.123.219 sunlight.brtt.com 23.31.71.129 23.31.71.136:80
ANTELOPE_LICENSE_CONNECTION_TIMEOUT	20.0

ruper%
In this example the TCP/IP connection timeout is set to 20 seconds. Note that the parsing of the license_env.pf file is primitive and does not use the Antelope stock library. Therefore, advanced constructs such as pf file substitution will not work properly. license_env.pf files in each directory in PFPATH are read and parsed. The single string $ANTELOPE in the PFPATH environment variable will be substituted with the environment variable in ANTELOPE, but this is the only environment variable substitution that is done when parsing PFPATH. If PFPATH is unset, then the default is $ANTELOPE/data/pf. If an environment variable is set both in a license_env.pf file and as a Unix environment variable, then the Unix environment variable value supersedes the value in license_env.pf. If an environment variable value is set in license_env.pf but needs to be unset at run time, then the Unix environment variable can be set to special value unset to cause it to be treated as unset by the licensing software.

OTHER LICENSING PROGRAMS

Included in the Antelope release are two programs that have specially built to support licensing, antelope_admin and ald_proxy. These program are statically linked, do not require an Antelope license to run and do not depend in any way on the Antelope distribution. ald_proxy is an internet proxy program used in situations where direct access to the license servers is not possible becuase of security reasons. antelope_admin has a number of other uses beside maintaining the license cache files. 

ruper% antelope_admin -action req ipe
action_req: client: 10.10.10.4:63442 G891304K20H response: 23.31.71.131:63442 - age = 0.100591

ruper%
This use of antelope_admin will attempt to get an ip-echo from either the license cache files or from one of the license servers in the same manner as an Antelope program, except the cache will get automatically updated if it is older than 60 seconds. The client: 10.10.10.4:63442 G891304K20H part of the response shows the ip-address that the requesting host thinks it has plus the host serial number. The response: 23.31.71.131:63442 part shows the ip-address of the host as seen by the license server. The age is how old the response is in seconds.

You can force the response to come from the license cache file with the following. 


ruper% antelope_admin -c -action req ipe
action_reqc: client: 10.10.10.4:63449 G891304K20H response: 23.31.71.131:63449 - age = 240.698708, 241.406905

ruper%
This is the cached version of the response which matches the version obtained from the license server. In this case that the cache is about 240 seconds old. Responses from a license server with no interactions with the license cache files can be gotten using the -d option (see antelope_admin(1)).

A special program, ald_proxy, is part of the standard distribution and is included to provide a license proxy mechanism. This program, like the other licensing programs, is statically linked, does not require an Antelope license to run and does not depend in any way on the Antelope distribution and can therefore be run on any host computer with or without an installed Antelope distribution or license. ald_proxy provides an internet proxy for connections to external Antelope license servers. This would be used in a very secure environment in which most of the Antelope host computers had no access to the outside internet. ald_proxy would be run on a machine outside of the firewall on port 6599 and would connect to license servers in the normal manner using all of the configuration environment variables. Hosts inside the firewall would connect to ald_proxy through the use of the ANTELOPE_LICENSE_SERVER_ADDRS environment variable which would be set to the proxy host address. A single hole in the firewall to the proxy host computer would be the only necessary outside connection.

SEE ALSO 

amd(1)
S99amdd(8)
antelope_admin(1)
ald_proxy(1)

AUTHOR

Danny Harvey
Printer icon