License Management

Each time a user submits a request using pbrun or when an administrator runs the File Integrity Monitor, there is a check with the license services that a valid license is present. Without a valid license, EPM-UL does not accept requests from users.

Introduced in version 10.0, a license string consists of a JSON (JavaScript Object Notation) string that details expiry, facilities, and services.

There are two types of licenses:

  • Temporary: The HostId attribute is set to temporary and is installed automatically to allow customers to evaluate EPM-UL.
  • Standard: Supplied by BeyondTrust once a customer has purchased the product. A standard license has a HostId attribute that associates the license with the primary license server of the EPM-UL installation.
Temporary License String:
{"PBULPolClnts":20, "SudoPolClnts":20, "RBPClnts":20, "ACAClnts":1, "AKAClnts":20, "FIMClnts":20, "SOLRClnts":1, "Owner":"Temporary License", "Comment":"Temporary License", "AutoRetire":7, "Recycle":7, "Expires":"2018-03-11 00:00:00", "Terminates":"2018-04-10 00:00:00", "HostId":"temporary", "HMAC":"UtGE3tD6qK2UwutY3GFOqodjdq30pEDAW2cKb5/OaMc="}

A temporary license is installed automatically if a standard license is not provided when the primary license server is installed. It enables 20 client seats for all services and enables all facilities. The license is valid for 60 days.

When requesting a standard license, you are asked to provide the output of pbadmin --info --uuid from the host that will run the primary license service. This displays the UUID (Universal Unique Identifier) that identifies the host. From this, BeyondTrust can generate a license that is associated directly to the host, with the appropriate facilities and services. This can then be imported into the primary license server.

pbadmin --info --uuid Output:
7faf7681-4d42-4b69-00bf-dad93b4a3dfb
Standard License String:
{"PBULPolClnts":200, "SudoPolClnts":200, "RBPClnts":200, "ACAClnts":1, "AKAClnts":0, "FIMClnts":0, "SOLRClnts":1, "Owner":"My Company Corp", "Comment":"Standard License for My Company", "AutoRetire":7, "Recycle":7, "Expires":"2018-03-01 00:00:00", "Terminates":"2019-03-01 00:00:00", "HostId":"7faf7681-4d42-4b69-00bf-dad93b4a3dfb", "HMAC":"UtGE3tD6qK2UwutY3GFOqodjdq30pEDAW2cKb5/OaMc="}

The license string introduced in version 10.0 of EPM-UL consists of a list of attributes that are human-readable and detail the entitlement of the license. These attributes are:

RBPClnts: <num> Details the maximum number of clients that are licensed to use EPM-UL role-based policy. A value of 0 means there is no entitlement. A value of -1 means unlimited clients.
AKAClnts: <num> Details the maximum number of clients that are licensed to use EPM-UL Advanced Keystroke Action functionality. A value of 0 means there is no entitlement. A value of -1 means unlimited clients.
FIMClnts: <num> Details the maximum number of clients that are licensed to use EPM-UL File Integrity Monitor. A value of 0 means there is no entitlement. A value of -1 means unlimited clients.
ACAClnts: <0|1> Details whether the license allows the use of Advanced Control and Audit.
SOLRClnts: <0|1> Details whether the license allows the use of SOLR Indexing functionality.
Owner: <name> Details the owner of the license.

Comment: <string>

 A simple string that can be updated to include any further information you wish to include.

AutoRetire: <num>

 Details the minimum duration in days after which a license is automatically retired due to client inactivity, allowing the license to be used by another client.

Recycle: <num>

 Details the minimum number of days after a client has been manually retired before it can be used again.
Expires: <date> Details when the license runs out, after which messages are displayed within the log files, and eventually to the end users, to remind the administrator to renew the license. The product continues to run without otherwise affecting functionality.
Terminates: <date> The cut off date for the product, after which it ceases to function.
HostId: <string> Details the host UUID designated to the primary license server.
HMAC: <string> Provides security to the license and customer to ensure that the license is authentic and correct, and has not been corrupted or altered.

 

The license server hosts manage licensing information by storing the client’s host ID in the Endpoint Privilege Management centralized license database to keep track of client connections. Licensing management is provided by the pbadmin tool, using the --lic options. The first installation of the license server is the primary license server. This installs a temporary license if no standard license is provided. Any machine that runs a client component consumes an EPM-UL license, even if the machine is also a policy server host or log host.

Beginning with version 7.1, EPM-UL can optionally track the last access date and node name of the clients.

Prior to version 8.5, policy servers used the connecting client's IP address as the identifier to differentiate it from other client hosts. However, IP addresses could not always assure client host uniqueness.

For instance, a host with multiple network interface cards (NICs) can have multiple IP addresses. The IP address of a client host that previously connected to a policy server could be changed.

Starting with version 8.5, EPM-UL uses UUIDs (universally unique identifiers) instead of IP addresses to identify and track connected clients. The UUID is derived from operating system calls and is unique to that host.

Starting with version 10.0, licenses are synchronized across all servers in the Endpoint Privilege Management enterprise installation. This makes licensing administration easier by giving a single pool of licenses available to the whole application, which can be managed from a single host.

Client Limit Enforcement

Starting with version 8.5, a policy server softens enforcement of its license limit to give customers time to contact BeyondTrust and adjust their license.

EPM-UL clients up to 10% over the license client limit are allowed to connect to the policy server without producing any error.

If the policy server receives client connections between 11%-20% over the license limit, a warning is written in syslog and the policy server diagnostic log file. If the policy server receives client connections between 21%-50% over the license limit, the initiating client program also receives a warning message. When a new client connection exceeds the license limit by more than 50%, an error displays, and the policy server rejects any new connection requests at that point.

Command Line Management

Licenses are managed on the primary license server using the program pbadmin. Only the root user can run pbadmin.

Usage

pbadmin --lic [<options>] [ <file> <file>…]
-u '{ param }' Update primary license server license where the { param } argument is the supplied JSON formatted license.

-u <path>

--force

Update primary license server license from file. Force the license update on secondary license server.
-G Retrieve license string and attributes.
-l [<wildcard(s)>] List client license usage summary.
-l Add an extra -l to list client usage detail.

-l [{

["fqdn" : "<wildcard>",]

["retired" : <true|false>,]

["updated_older" : <epoch>,]["updated_newer" : <epoch>,]

["updated_older" : { "years" : n, "months" : n, "days" : n, "hours" : n ]

["updated_newer" : { "years" : n, "months" : n, "days" : n, "hours" : n ]

 

List clients with attributes.
-s <[-|+]attribute> Sort the list of records by attribute name (ascending/descending).
-L [<service>] List Client Service License Usage Summary.
-L Add an extra -L to list all client service details.

-r {"uuid" : "<uuid|wildcard>"}

-r {"uuid" : ["<uuid|wildcard>", "uuid", …]}

-r {"fqdn" : "<fqdn|wildcard>"}

-r {"fqdn" : ["<fqdn|wildcard>", "fqdn", …]}

 Retire clients to free up licenses based upon UUID, FQDN, or wildcard.
-R

Refresh license statistics from the primary license server.

License Management

pbadmin is used to import standard licenses using the -u option. It can be used to list client and service statistics, and it can be used to retire old client licenses.

As of version 10.0, License Management is centralized and can be carried out on the primary license server using the command pbadmin.

The command line administration tool provides methods to update the license string, to list summary statistics and to retire clients to free up licenses.

All of the commands that list statistics can be run from any server that provides a service. All commands that update the database, such as updating the license itself or retiring clients, should be run on the primary license server:

pbadmin --lic -u '{ "PBULPolClnts":200, "SudoPolClnts":200, "RBPClnts":200, "ACAClnts":1, "AKAClnts":0, "FIMClnts":0, "SOLRClnts":1, "Owner":"My Company Corp", "Comment":"Standard License for My Company", "AutoRetire":7, "Recycle":7, "Expires":"2018-03-01 00:00:00", "Terminates":"2019-03-01 00:00:00", "HostId":"7faf7681-4d42-4b69-00bfdad93b4a3dfb", "HMAC":"UtGE3tD6qK2UwutY3GFOqodjdq30pEDAW2cKb5/OaMc="}'

This command updates the installation with the license string provided by BeyondTrust to a standard license.

Listing Clients

To view a list of client hosts that are using the license on a license server, use the pbadmin --lic -l command option. Doing so produces a list similar to the one in the following example:

# pbadmin -P --lic -l
    {
    "uuid": "7faf7681-4d42-4b69-00bf-dad93b4a3dfb",
    "fqdn": "pbuild",
    "addr": "[{\"family\":4,\"port\":0,\"addr\":\"192.168.16.138\"}]",
    "lastupdated": "2018-01-17 09:31:37",
    "retired": "never",
    "recycle": "never"
    }
    {
    "uuid": "e5368b17-e78b-416c-ae1a-14c6273cccb6",
    "fqdn": "host2",
    "addr": "[{\"family\":4,\"port\":0,\"addr\":\"192.168.16.140\"}]",
    "lastupdated": "2018-01-17 09:31:40",
    "retired": "2018-01-17 09:31:40",
    "recycle": "never"
    }
    {
    "uuid": "f5d5edd2-2ed0-4fe3-bbb5-46e6ce295b22",
    "fqdn": "host3",
    "addr": "[{\"family\":4,\"port\":0,\"addr\":\"192.168.16.141\"}]",
    "lastupdated": "2018-01-17 09:26:40",
    "retired": "never",
    "recycle": "never"
}

Note the retired license in the list.

Retiring Clients

If a client is removed from the network, then its slot in the license database remains active. To retire a client host from the license database, specify the -r command option for pbadmin.

To retire one client:
# pbadmin --lic -r '{ "uuid" : "2ddf83e6-aabf-4dbe-a70e-f73a3d73aea6" }'
    *** WARNING ***
    You have elected to retire clients from.
    Clients which are retires will be usable to reconnect to the application
    For a period of 7 days, regardless of the number of unused licenses remaining.
    If you are sure you want to do this, please specify the '--force' option
    # pbadmin --lic -r '{ "uuid" : "2ddf83e6-aabf-4dbe-a70e-f73a3d73aea6" }' --force
To retire multiple clients:
# pbadmin --lic -r '{ "uuid" : ["2ddf83e6-aabf-4dbe-a70e-f73a3d73aea6","…"]}' --force

This example demonstrates the retirement of a client host with 2ddf83e6-aabf-4dbe-a70e-f73a3d73aea6 UUID from the active licenses. This action frees up one license slot for another.

License Settings

For the list and description of settings related to license management, see Licensing.