Licensing for PBS Professional; Create, Install, and Troubleshoot
Altair EmployeeLICENSING FOR ALTAIR PBS® PROFESSIONAL®
Joe Miller III – Technical Support Engineer, Altair
Scope
At the time of this writing, PBS Professional 2020.1 and PBS Professional 2021.1 are the only fully supported PBS Professional versions; earlier versions are in limited support or unsupported. There has been a shift in licensing between PBS Pro 19 and 2020+. This document will cover that span, their requirements, comparisons, creation, and installation. Detailed documentation can be found for PBS Professional in the Altair Community (https://community.altair.com/community?id=altair_product_documentation).
PBS Professional 19 closely resembles the requirements and methods of older versions, but the nuances of those older versions (especially prior to PBS Professional 14) will not appear herein.
There are some advanced licensing techniques when applying Highly Available Licensing (HAL) / Three-Server Configuration setup and the need to split licensing into several licensing pools across the servers. This guide will not cover HAL,but is documented in the Altair License Management System Guide.
Introduction to Licensing in PBS Professional
PBS Professional is a licensed commercial software.
PBS Professional requests parts of a license file called feature blocks. They may be delivered in one of two ways, through a local file or through a license server, Altair License Manager.
Challenges
PBS Professional 2020.1 is a historic release in terms of licensing. This and future releases require a new set of features which are required to be delivered through Altair License Manager (ALM), the licensing server.
Some licensing terms overlap but are of different scopes. This overuse needs be addressed.
Knowing all licensing requirements of supported versions may help in upgrading from previous versions or installing PBS Professional for the first time.
Definition of Terms
License File
A plain text file (typically with the “.dat” extension) which contains one or many feature blocks.
Feature Block
Figure 1: Example PBSProNodes Feature Block
A block of data PBS Professional requests. It contains information such as the count, start, and end dates of the feature.
If something is wrong with your feature blocks (Figure 1), such as the count or expiration dates, you will need to reach out to your Altair Account Manager.
Altair License Manager (ALM)
Sometimes referred to as Altair License Server, this daemon reads a license file and distributes features to various requesting Altair products, including PBS Professional. As of PBS Professional 2020.1, ALM 14.5+ is required to distribute license features.
License Pool
The total collection of features available on a license server or license file. A license server may only contain 1 license pool (it will not append multiple licenses).
User Area – Licensing Page
Figure 2: User Area Unused Licenses; example licenses
Access to an online portal (https://secure.altair.com/UserArea/license_man.php) is provided to customers of Altair when first granted licenses. This area is used to verify and download current created licenses or create new supported licenses if available. A company managing many physical locations may work with their Altair Account Manager to have multiple sites/logins.
License Expiration
Licenses expire the day after listed. PBS will not obtain licenses from the license server once they have expired.
Example: If your license expires 30-Sep 2020, your license will no longer distribute starting 01-Oct 2020.
License Scope
The license scope determines what feature blocks will be created in the generated license file. This document only covers license scopes relating to PBS Professional.
Your purchase SKU(s) (e.g., PBS-SUITE-AN) will determine type of scope and available quantity of each.
There are 9 different license scopes you may encounter, as shown in the Figure 2.
Some license scopes are no longer in use or deprecated.
| Scope | PBS 19.2 | PBS 2020.1 |
|---|---|---|
| PBSWorks | Yes | No |
| PBSWorks (2020) | No | Yes |
| Socket | Yes | No |
| HWU | Deprecated | No |
| PBSProNodes | No | Yes |
| PBSProSockets | No | Yes |
| Floating | No | No |
| Node-Locked | No | No |
Creating Licenses
Clicking on “Create New License” will open a form to gather information about your specific license.
| Form Field(s) | Description |
|---|---|
|
| Only when creating HWU scope licenses. For PBS 19, always select “LM-X” license type here. |
|
| Any license scope to use Altair License Manager (ALM) Select “3 Servers” if using a 3-server configuration |
|
| Only when creating PBSWorks scope licenses Only works with PBS Professional 19 |
|
| Only when creating PBSWorks scope licenses Select when you have a PBS failover server |
|
| All license scopes: Amount fields Each license scope form has its own field for entering the quantity to assign to the license. If only creating 1 license file with granted licenses, simply put in the remaining licenses. The HWU scope has its own calculator to determine the correct quantity to assign. Note: ALM and PBS Professional, each, will only accept 1 license file. Though, PBS Professional may point to multiple ALMS. You will need multiple license servers or PBS headnodes to accept different license files. |
** Ethernet is chosen 99%+ of the time.
Deleting and Crediting of Licenses
Please contact your Altair Account Manager for assistance in deleting and crediting your licenses back to available pool.
Installing Your License
For PBS Professional to work, the pbs_server daemon must be able to pull licenses for use through the network (ALM) or a local file. PBS Professional 2020.1 (and all its components) requires a network license. PBS Professional 19 requires a local license.
Note: PBS Professional 19 also allows licenses to be served through ALM, but only using a deprecated/retired scope (HWU). This license scope is no longer actively sold or supported. Some “add-on” features of PBS Works 19 still need to be served through ALM (e.g., Access, Cloud Bursting).
Installing a Network Licenses (ALM)
The steps below assume you have already installed and configured ALM with a valid license and open ports and are planning a simple 1-server install. Please see the licensing guide for documentation to change default ports or add licensing servers.
Validate license features are being accounted for by ALM
# cd $ALM/bin <br />(default $ALM path: /usr/local/altair/licensing<version>) <br /># ./almutil -licstat
You should be greeted with every feature block being accounted for and what is available to pull.
Point pbs_server daemon to your ALM
# qmgr -c "set server pbs_license_info = 6200@licserver"
PBS Professional should be able to pull licenses within a few seconds to be used.
Verify pulled licenses
$ qstat -Bf | grep license
The server’s license_count attribute should show available and used licenses. Example:
[root@minimal ~]# qstat -Bf | grep license pbs_license_info = 6200@licserver pbs_license_min = 0 pbs_license_max = 2147483647 pbs_license_linger_time = 31536000 license_count = Avail_Global:6 Avail_Local:0 Used:1 High_Use:1
Installing a Local Licenses File
Only the PBSWorks scope and Socket scope are served via local license file to PBS Professional 19. All others, including HWU for PBS Professional 19 and all PBS Professional 2020 license scopes are served through ALM (network license).
After the license file is reachable by your headnode, there are only 2 steps:
Point pbs_server daemon to your License File
# qmgr -c "set server pbs_license_info = /path/to/altair_lic"
Verify pulled licenses
$ qstat -Bf | grep license
The server’s license_count attribute should show available and used licenses. Example:
[root@minimal ~]# qstat -Bf | grep license pbs_license_info = /path/to/altair_lic.dat license_count = Avail_Nodes:20 Unused_Nodes:19
License Troubleshooting
Below are the common issues you may see when handling licensing and the next steps to solve. You will find most of them in the server logs (after updating log events). As always, feel free to reach out to PBS Support.
Not Seeing Change of Licenses When Installing New License
PBS doesn’t seem to update to the newly installed license. This can happen when replacing an old license file, but not forcing restart of licensing read to ALM and/or PBS Professional.
Verify New License File
A simple step; make sure you have the new license file on the server and are not serving the old one.
Restart and verify ALM
# /etc/init.d/altairlmxd restart # $ALM/bin/almutil -licstat (default $ALM path: /usr/local/altair/licensing<version>)
Reset PBS Server Attribute
$ qstat -Bf | grep license_info pbs_license_info = <value> # qmgr -c "set server pbs_license_info=<value>"
PBS Professional will re-consider the license path even if it’s the same path. For quick replacement of a license file, this should be enough to re-read the files and start pulling the correct licenses.
For PBS 19 Only: Change log events to 1447
If the simple fix above didn’t work, server log events need to be changed to catch licensing events.
# qmgr -c "set server log_events=1447"
Note: if you are actively looking to continue capturing all events in the logs during this time, you would opt to increase the log events to 2047. This will include only a few more licensing logs, though general licensing issues don't benefit.
The messages and errors below (headings = error) will only be visible in your server logs after you have changed your log events.
Path Component
This error shows an incorrect path to the license file. You need to change the PBS server’s pbs_license_info attribute to point to a file the headnode has access to. Will also display with some improper formatting when pointing to ALM. Example:
08/19/2020 10:15:47;0400;Server@minimal;Svr;Server@minimal;path component /bad/path/to/altair_lic.dat does not refer to a file and does not point at a license server 08/19/2020 10:15:47;0004;Server@minimal;Svr;Server@minimal;attributes set: at request of root@minimal.pbs.j3laptop 08/19/2020 10:15:47;0004;Server@minimal;Svr;Server@minimal;attributes set: pbs_license_info = /bad/path/to/altair_lic
Verify your path to your license file and reset the server’s pbs_license_info attribute.
[ -f /path/to/altair_lic.dat ] && echo "Exists" || echo "Does not exist" (resolve until "Exists") # qmgr -c "set server pbs_license_info=/path/to/altair_lic"
(Err: 6) Unable to read file
This error may occur if your license file is somehow unreadable by pbs_server daemon. This should be rare, as most pbs_server daemons run as root. The error may also show if somehow you have the wrong formatting in pbs_license_info while attempting to connect to ALM.
Example below would trigger the error; having an “@” symbol in the attribute without pointing to ALM.
# qmgr -c "set server pbs_license_info=host@host"
The license file should be in a readable directory and have 644 file permissions.
# chmod 644 /path/to/altair_lic
If connecting to ALM(s), verify format:
# qmgr -c "set server pbs_license_info=<port>@<server1 host>[:<port>@<server2 host>…:<port>@<serverN host>]"
(Err: 8) Invalid License Key
Each feature block of the license contains a “KEY” field. Should the license be altered in any way, including the “COMMENT” section, the key will not validate. The file may have been altered by aggressive cluster management software, through saved backup, or even possible manual alteration.
The simplest method to fixing this error is to download a fresh copy of your license file and re-install. You can get a copy of your license through the User Area or by contacting your Altair Account Manager.
(Err: 9) Feature Not Found
PBS Professional requires specific features to run. If the server does not find the feature blocks in the license file or through ALM, it will throw this error along with the feature blocks searched for.
Often, this is a simple fix, usually not having updated the license on ALM or pointing to the wrong license file.
For ALM (Network License):
# grep -E "^LICENSE" $ALM/altair-serv.cfg (default $ALM path: /usr/local/altair/licensing<version>) (verify license file location for ALM) (update to new license file if needed) # /etc/init.d/altairlmxd restart (restart ALM to re-read license file) # /path/to/ALM/bin/almutil -licstat | grep -E "<f1>[|<f2>…]" (verify available feature(s))
For Local License File:
# grep -E FEATURE /path/to/altiar_lic.dat (verify license features in license file) (update to new license file if needed) # qmgr -c "set server pbs_license_info=/path/to/altair_lic" (force PBS to re-read license file)
(Err: 12) Software expired
The current date is beyond the feature block’s “END” parameter. If you have a new license file, you need to force ALM or PBS Professional to re-read your new license file. If you do not have a new license file, you need to create one through the User Area or contact your Altair Account Manager.
For ALM (Network License):
# grep -E "^LICENSE" $ALM/altair-serv.cfg (verify license file location for ALM) (update to new license file if needed) # /etc/init.d/altairlmxd restart (restart ALM to re-read license file) # /path/to/ALM/bin/almutil -licstat (verify end date on features)
For Local License File:
# grep -E ^END /path/to/altiar_lic.dat (verify end date in license file) (update to new license file if needed)# qmgr -c "set server pbs_license_info=/path/to/altair_lic " (force PBS to re-read license file)
(Err: 15) Unable to connect to license server
PBS is having troubles connecting to your ALM. It only occurs when setting the server’s pbs_license_info attribute to <port>@. This error may arise due to ALM not started, bad/unavailable port, or bad hostname resolution.
# grep PORT $ALM/altair-serv.cfg (verify TCP_LISTEN_PORT for ALM) (open port on License Server and PBS headnode) # qmgr -c "set server pbs_license_info=<port>@<server1 host>[:<port>@<server2 host>…:<port>@<serverN host>]"<br />
(Err: 47) Error receiving message over network
</code></pre> <p>PBS is having troubles with networking. Usually, this is a result of mixing short domain names with FQDN between different parts of PBS. Attempting different pathways to the license server and reviewing the hosts will likely resolve the issue. If using short domain name as headnode, also setup short domain name for ALM.</p> <pre><code style="color: #404040;">
# qstat -Bf | grep license_info (verify the host)<br /># qmgr -c "set server pbs_license_info=<port>@ip.add.re.ss<br />(verify it's working with direct IP)<br />(Check on DNS and pbs_hostn -v <licensehost> to verify host / make network changes as needed)<br /># qmgr -c "set server pbs_license_info=<port>@<server1 host>[:<port>@<server2 host>…:<port>@<serverN host>]"<br />(Change back / test [if desired])
</code></pre> <h4 style="font-size: 13px; font-weight: bold; color: #000000; margin-bottom: 0;">(Err: 51) Network License as Local License</h4> <p>When PBS locates some or all features required for a license to be served through ALM (network license), but no features to be served as a local license file, this error is thrown.</p> <p>Again, only the PBSWorks scope and Socket scope are served via local license file to PBS Professional 19. All others, including HWU for PBS Professional 19 and all PBS Professional 2020 license scopes are served through ALM (network license).</p> <p>Overall, make sure ALM is setup with this license and point PBS to ALM.</p> <pre><code style="color: #404040;"># grep -E "^LICENSE" /path/to/ALM/altair-serv.cfg (verify license file location for ALM) (update to new license file if needed) # /etc/init.d/altairlmxd restart (restart ALM to re-read license file) # /path/to/ALM/bin/almutil -licstat (verify serving of features) # qmgr -c "set server pbs_license_info=<port>@<server1 host>[:<port>@<server2 host>…:<port>@<serverN host>]"
Change log events back to 511
When all issues are resolved with licensing, don’t forget to change server log events back to default (or preferred setting).
# qmgr -c "s s log_events=511"
Conclusion
Licensing is a key part to working with PBS Professional. Through this article, you should be able to resolve most issues that may come about when setting up your licensing.
As always, for any assistance setting up complex licensing, please create a case/ticket through the Community portal.