iControl 101 - #14 - License Administration

An important aspect of system management is maintaining the licenses on the devices you are responsible for.  The BIG-IP includes a programmatic interface to allow you to query the current license information and upload and apply new licenses to the device allowing the automation of this management task.  This article will discuss the Management.LicenseManagement interface in the iControl API and how you can use it to keep your BIG-IP's license up to date.

Initialization

This article uses PowerShell and the iControl Cmdlets for PowerShell as the client environment for querying the data.  The following setup will be required for the examples contained in this article.

PS> Add-PSSnapIn iControlSnapIn
PS> Initialize-F5.iControl -Hostname bigip_address -Username bigip_user -Password bigip_pass
PS> $LA = (Get-F5.iControl).ManagementLicenseAdministration
PS> $ASCII = New-Object -TypeName System.Text.ASCIIEncoding

Is the device licensed?

The first step will be to determine whether the device has been licensed.  If not, the likely you'll know about it as you won't be able to make use of most of the features since they will be disabled.  The get_license_activation_status() method returns an EnabledState enumeration to let you know whether the device has been licensed.  You'll see from the following response that my device has indeed been licensed.

PS> $LA.get_license_activation_status()
STATE_ENABLED

Is the device in an evaluation mode?

Once you know that the device has been licensed, The next step will be to determine whether your device is under an evaluation license.  Whether you are giving BIG-IP a test drive or are, like me, running a developer license, then you'll want to double check that you are running under an evaluation license.  The is_evaluation_license() method returns a boolean value of true or false depending on whether the current license is an evaluation or not.  You will see below that my BIG-IP is indeed under evaluation.

PS> $LA.is_evaluation_license()
True

License Expiration

The next thing you are likely to ask is when your evaluation license is set to expire.  Never fear, the get_evaluation_license_expiration() method will return the current system time as well as the start time for the evaluation and the date and time the license is set to expire.  This example shows that my license is set to expire at 1210752000.

PS> $EvaluationExpiration = $LA.get_evaluation_license_expiration()
PS> $EvaluationExpiration | fl
current_system_time : 1210257101
evaluation_start    : 1170662400
evaluation_expire   : 1210752000

What?  You don't know how to do conversion from the number of seconds elapsed since 00:00:00 on January 1, 1970 coordinated Universal Time?  That can be corrected by creating a DateTime object based on 12:00am Jan 1, 1970 and then adding the values as seconds.  Then, since the time is in Universal Time, you'll want to adjust the GMT time that your BIG-IP is located at.  The GMT offset can be retrieved from the System.SystemInfo.get_time_zone() method.  The following code will take the previous values and perform the conversions to correctly reflect the local time on the BIG-IP.

PS> $origin = [DateTime]::Parse("Jan 1, 1970 12:00:00AM")
PS> $gmt_offset = ((Get-F5.iControl).SystemSystemInfo.get_time_zone()).gmt_offset

PS> $origin.AddSeconds($EvaluationExpiration.current_system_time).AddHours($gmt_offset)
Thursday, May 08, 2008 2:51:09 PM

PS> $origin.AddSeconds($EvaluationExpiration.evaluation_start).AddHours($gmt_offset)
Monday, February 05, 2007 8:00:00 AM

PS> $origin.AddSeconds($EvaluationExpiration.evaluation_expire).AddHours($gmt_offset)
Wednesday, May 14, 2008 8:00:00 AM

Other Misc methods that may be of interest are the get_copyright_file(), get_eula_file().  The following example uses the ASCII Encoding to convert the returned byte array from the get_copyright_file() method into a string and displays the contents.  If you want the eula contents, then replace the method call with get_eula_file().

PS> $ASCII.GetString($LA.get_copyright_file())
Begin F5 Networks, Inc. Copyright
---------------------------------------
All of the documentation and software included in this product
release is copyrighted by F5 Networks, Inc., except where explicitly noted.
...

The installed License File

Have you ever wondered what the license file looks like once you have one?  Well, the get_license_file() method will return the contents of the current license file.  Again, make sure you convert the returned array of bytes into an ASCII string.

PS> $ASCII.GetString($LA.get_license_file())
#
Auth vers :                        5b
#
#
#       BIG-IP System License Key File
#       DO NOT EDIT THIS FILE!!
...

Registration Keys

Part of the licensing process is the set of registration keys that control the basic features that you are having licensed.  The get_registration_keys() method will return a string array of registration keys that you have configured on the device.

PS> $keys = $LA.get_registration_keys()
PS> $keys
J9Q42-63R73-8S271-91217-3682254
O102366-9462636
O914836-9853398
E169309-8947262
E065642-5132297

System Dossier

Like James Bond has when he's investigating the bad guys, each system has a unique dossier that identifies the system with all of it's features.  This dossier is used to generate new licenses through the F5 license server.  The get_system_dossier() method will return this dossier which is an encrypted string.  Before passing registration keys to this method, it's likely a good idea to check if the crc checksum passes for each of the registration keys.  This can be done with the check_registration_key_crc() method which takes as input an array of strings containing the registration keys and returns an array of boolean values indicating whether the keys passed a checksum validation.

PS> $LA.check_registration_key_crc($keys)
True
True
True
True
True

PS> $LA.get_system_dossier($keys)
5475f4c659b69f8ef875d54b2b956181cfd9d5fc25d27460a8dff1ad9717255a8944604e4155636b084a0f6b007...

Licensing your system

F5 has a licensing server at activate.f5.com.  You'll have to login to that site with a browser, enter the previous dossier and go through the activation process to get an updated license file.  Once you have that license file, you can use that in the install_license() method to activate your system.  Remember that this method takes an array of bytes as input so you'll need to convert the string into the byte array before making the method call.

PS> $lic = Get-Content c:\temp\bigip_license.txt
PS> $LA.install_license($ASCII.GetBytes($lic))

Conclusion

Now you have all the tools you need to automate the licensing of your systems.