Licensing#

Overview#

Posit Package Manager uses a built-in license management system. A license controls the number of available repositories, as well as the expiration of your product subscription. This page covers how to:

• Check the status of your license
• Activate a new or updated license
• Troubleshoot various licensing errors

Product Tiers#

The documentation applies to all product tiers of Posit Package Manager (Basic, Enhanced, Advanced), unless the section is specifically marked Enhanced or Advanced , in which case it only applies to the indicated tier(s).

Licensing Status#

Initially, Package Manager operates in evaluation mode and then requires activation for continued use. If you cannot complete your evaluation of Package Manager, see the Extending Evaluations section for more information.

To determine the current license status of your system, run the following command:

$ sudo /opt/rstudio-pm/bin/license-manager status

$ sudo /opt/rstudio-pm/bin/license-manager status-offline

Activation Options#

After purchasing a license to Package Manager, you’ll receive a license file used to activate the license on a given system. Activate your license file with the instructions described in the License File section below.

Using License Files (Recommended)#

A license file is an encrypted text file with a name having the shape <expiration-date>_<product-code>_<organization>_<license-key>.lic.

Activation options:

• Local license file

Using License Keys#

A license key is a combination of letters and numbers with the shape AAAA-BBBB-CCCC-DDDD-EEEE-FFFF-GGGG.

Local activation options:

• With internet access
  • Through a proxy server
• Without internet access

Persistent/Floating Server activation options:

• With internet access
• Without internet access

License File#

A license file is an encrypted text file with a name having the shape <expiration-date>_<product-code>_<organization>_<license-key>.lic.

The file fully describes the purchased product license. It includes details such as the expiration date and entitlements permitted by the license. License files do not communicate with an external licensing provider, making them suitable for containerized, offline, and air-gapped environments. License files are the recommended way to provide a license to Posit Package Manager.

The Licensing FAQ provides information about common issues and questions that you may have when activating or switching your current activations to license files. If the issue persists, please reach out to Posit Support by creating a support ticket.

Activation#

Transfer the license file to the server hosting Posit Package Manager, ensure ownership and read permissions for the PPM service user, and activate it with the commands:

$ sudo chown rstudio-pm <license-file>.lic
$ sudo chmod 0600 <license-file>.lic
$ sudo cp -a <license-file>.lic /var/lib/rstudio-pm/
$ sudo systemctl restart rstudio-pm

You need to restart Package Manager after activation for licensing changes to take effect.

Deactivation#

If you are renewing your license or want to move your license of Posit Package Manager to another system, you can perform license deactivation by removing the license file from the server location and restarting Package Manager.

Deactivate a license file by removing the file and restarting Package Manager.

$ sudo rm /var/lib/rstudio-pm/<license-file>.lic
$ sudo systemctl restart rstudio-pm

License Key#

In rare cases, you may need to activate a license key, described below. However, most customers are best served by using license files, instead. License files work well in all environments including ephemeral ephemeral, container-based, or air-gapped environments.

Online Activation#

Connectivity Requirements#

To activate or deactivate Package Manager, internet connectivity is required for communicating with the licensing server. More information on specific networking access is available on this Posit documentation Licensing page. If your server is behind an internet proxy or not connected to the internet at all, the sections below describe what's required to successfully activate.

Additionally, your server should have a synchronized system clock, using ntp or some other clock syncing service. If the server's clock is sufficiently incorrect, licensing verification fails.

If you have internet access and are not using an internet proxy, activate your license key with the commands below:

$ sudo /opt/rstudio-pm/bin/license-manager activate <license-key>
$ sudo systemctl restart rstudio-pm

Proxy Servers#

If your server is behind an internet proxy, you may need to add an additional command line flag indicating the address and credentials required to communicate through the proxy. This may not be necessary if either the http_proxy or all_proxy environment variable is defined (these are read and used by the license manager when available).

If you do need to specify a proxy server explicitly, you can do so using the --proxy command line parameter. For example:

$ sudo /opt/rstudio-pm/bin/license-manager \
    --proxy=http://127.0.0.1/ activate <product-key>

Proxy settings can include a host-name, port, and username/password if necessary. The following are all valid proxy configurations:

• http://127.0.0.1/
• http://127.0.0.1:8080/
• http://user:pass@127.0.0.1:8080/

If the port is not specified, the license manager will default to using port 1080.

Online Deactivation#

If you want to move your license of Posit Package Manager to another system you should first deactivate it on the old system with the command:

$ sudo /opt/rstudio-pm/bin/license-manager deactivate

Then, activate your license on the new system by following the steps directly above in the Online Activation section.

Offline Activation#

If your system has no connection to the internet, it's also possible to perform an offline activation. To do this, we recommend using our offline activation app, which will walk you through the process: Posit Offline Activation

To activate your license offline, you first generate an offline activation request as follows:

$ sudo /opt/rstudio-pm/bin/license-manager activate-offline-request <product-key>

Executing this command prints an offline activation request to the terminal. Copy and paste the entirety of this request into our offline self-service application, or send it to Posit Support. You will receive a reply with a file attachment that can be used to activate offline as follows:

$ sudo /opt/rstudio-pm/bin/license-manager activate-offline <activation-file>

After activation, restart the Package Manager server:

$ sudo systemctl restart rstudio-pm

Offline Deactivation#

If you are renewing your license or want to move your license of Posit Package Manager to another system you can perform license deactivation offline by executing the following:

$ sudo /opt/rstudio-pm/bin/license-manager deactivate-offline

Executing this command prints an offline deactivation request to the terminal which you should copy and paste and enter into the offline activation application or send to Posit Support.

Then, activate your license on the new system by following the steps directly above in the Offline Activation section.

Floating Licensing#

In rare cases, you may need to activate a license key on a floating license server, described below. However, most customers are best served by using license files, instead. License files work well in all environments including ephemeral ephemeral, container-based, or air-gapped environments.

Traditionally, an admin must activate a license key on each Package Manager instance by running the activate and deactivate commands. Floating licensing allows you to run a standalone licensing server and then have each Package Manager instance communicate with this licensing server to lease a license. This configuration can be useful if Package Manager is ephemeral (e.g., in a docker container). In this case, you can use the Package Manager License Server. Please note that a specific license key is necessary for floating licensing. Please contact Posit Support to obtain a key that supports floating licensing.

License Server Activation#

Online Activation#

If you have internet access, complete the following steps to activate a floating license on the persistent server:

1. Install the License Server on a persistent server with network access to the Package Manager instance(s) and activate your license key on the License Server.
2. Configure Package Manager to use the License Server.
3. Optionally, change the Package Manager License Server defaults.

Install the License Server#

Follow these instructions in a persistent server running the Package Manager License Server.

Download the Package Manager License Server and then install the server and activate the license:

$ sudo dpkg -i <rspm-license-server-version.deb>
$ sudo rspm-license-server activate <license-key>
$ sudo rspm-license-server start

$ sudo yum install --nogpgcheck <rspm-license-server-version.rpm>
$ sudo rspm-license-server activate <license-key>
$ sudo rspm-license-server start

$ sudo zypper --no-gpg-checks install <rspm-license-server-version.rpm>
$ sudo rspm-license-server activate <license-key>
$ sudo rspm-license-server start

Configure Package Manager to use the License Server#

Once the Package Manager license server is installed and activated, configure Package Manager to use the license server.

Follow these instructions in Package Manager or script them into your configuration management tools that will be building, starting, and stopping Package Manager.

1. Edit the Package Manager configuration file:

   /etc/rstudio-pm/rstudio-pm.gcfg

   [Licensing]
   LicenseType = remote
   

2. In the server running Package Manager, execute:

   Terminal

   $ sudo /opt/rstudio-pm/bin/license-manager license-server <rspm-license-server-host-or-ip:port>
   

   By default, the Package Manager license server runs on port 8969. The license-server command only needs to be run once. If the same Package Manager server subsequently starts and stops, it saves the Package Manager License Server address. However, if you rebuild the server or image running Package Manager you will need to re-run the license-server command.

3. Restart Package Manager or send it the HUP signal:

   Terminal

   $ sudo systemctl restart rstudio-pm
   

Changing the Package Manager License Server Defaults (Optional)#

Port#

The port used by the Package Manager license server can be changed:

<bind port="8969"/>

After modifying /etc/rspm-license-server.conf, restart the Package Manager license server:

$ sudo rspm-license-server restart

License Leases#

When using floating licenses, you can optionally determine how long the license leases last by setting the lease length value on the licensing server. This value is in seconds. For instance, to make license leases last 30 minutes, use the following syntax:

<lease length="1800"/>

The lease length controls how frequently the Package Manager instances need to contact the licensing server to renew their license leases.

A shorter lease length will increase tolerance to failures on Package Manager instances by making leases available for reuse more quickly. Package Manager will release its lease immediately if shut down normally. If abnormally terminated, the lease will not be released until it expires.

A longer lease length will increase tolerance to transient failures on the network and the Package Manager license server. Any such issues that can be resolved before the lease is due for renewal won’t interrupt use of Package Manager.

We generally recommend using a longer lease length. Use a short lease length only if your environment routinely encounters abnormal terminations of the server or the container/instance on which it runs.

Changing the Lease Expiration and Renewal Default#

This configuration can be scripted into the build process for ephemeral instances.

Under normal conditions, Package Manager will automatically renew its license lease in a configurable interval as described above. However, there are situations in which it would be unable to automatically renew. Examples of these situations include a network problem, or an issue on the host running the license server.

When Package Manager cannot obtain a license lease, either because there are no leases currently available or because it can’t reach the licensing server, it will begin automatically attempting to acquire a lease every 10 seconds. This interval is configurable; for instance, to retry every 30 seconds instead, set the following value:

[Licensing]
RemoteRetryFrequency = 30s

If you don’t want Package Manager to attempt to reestablish a license lease automatically, set the value to 0 to disable retries. In this case, you need to manually restart Package Manager or send it the HUP signal to reestablish the lease. This can be useful if you often run more instances than you have keys for, and wish to have more control over which Package Manager instances receive license leases from the limited pool on the license server.

Offline Activation#

If you are running the Package Manager Licensing Server in an offline environment, you need to perform an additional offline activation. First, generate an offline activation request:

$ sudo rspm-license-server activate-offline-request <license-key>

Executing this command prints an offline activation request to the terminal. Copy and paste the entirety of this request into the offline self-sevice application, or send it to Posit Support. You will receive a reply with a file attachment that can be used to activate offline as follows:

$ sudo rspm-license-server activate-offline <activation-file>
$ sudo rspm-license-server restart

$ sudo rspm-license-server deactivate-offline-request <product-key>

License Server Deactivation#

If you are permanently decommissioning your license server or need to transfer its license to a different license server, deactivate (remove) its license as follows:

sudo systemctl stop rstudio-pm
sudo rspm-license-server stop
sudo rspm-license-server deactivate
sudo /opt/rstudio-pm/bin/license-manager clear-license-server

Troubleshooting Floating Licensing#

Run the following troubleshooting steps on the persistent Package Manager license server.

To validate that the Package Manager License Server has been successfully activated, run the activation-status command. This will report the version of the server as well as the license key and the number of available slots.

$ sudo rspm-license-server activation-status

If your server is activated but you’re still having trouble with floating licensing, you can tell the Package Manager License Server to emit more detailed logs. Change the log level to notification:

<log file="/var/log/rstudio-licensing.log" level="notification"/>

Then, restart the License Server, tail the licensing log, and start your Package Manager instances.

$ sudo rspm-license-server restart
$ tail -f /var/log/rstudio-licensing.log

At the notification level, the licensing log will tell you the total number of licenses associated with your key, and how many are currently in use. It will also notify you when Package Manager instances acquire leases, and when those leases are released, renewed, or expired. No rotation is done for this log, so it’s recommended to use the warning level in production.

Evaluations#

Extending Evaluations#

If you are unable to complete your evaluation during the evaluation period, contact your Customer Success Representative or Posit Sales (sales@posit.co) to speak about your evaluation process and how we may be able to help with the remaining items you need to test.

Connectivity Requirements#

Beginning Evaluations#

Generally, there are no network requirements during the evaluation period. Inside virtual machines or sandboxes (such as Docker), however, Internet access is required to begin the evaluation period.

If you have a proxy, you can supply it using the --proxy argument as described in the Proxy Server section above.

If you have no means of connecting to the Internet from inside the virtual environment, you can begin the evaluation by executing the following command:

$ sudo /opt/rstudio-pm/bin/license-manager begin-evaluation-request

Executing this command prints an offline activation request to the terminal. Copy and paste the entirety of this request into the offline self-sevice application, or send it to Posit Support. You will receive a reply with a file attachment that can be used to begin the evaluation offline as follows:

$ sudo /opt/rstudio-pm/bin/license-manager begin-evaluation-offline <evaluation-file>
$ sudo systemctl restart rstudio-pm

Restart Package Manager after starting your offline evaluation for licensing changes to take effect.

Renewing a License#

After purchasing a license renewal, you will receive an email with the license key and/or license file. Next, follow the steps outlined below to activate the license, based on the type of license renewal that you require.

• With a license file
• With a license key (online)
• With a license key (offline)

License File Renewal#

To renew a license file, first transfer the updated license file to the server hosting Posit Package Manager. Then run the following commands to remove the old license file from the server location, ensure ownership and read permissions for the PPM service user on the new license file, and activate it:

$ sudo rm /var/lib/rstudio-pm/<old-license-file>.lic
$ sudo chown rstudio-pm <new-license-file>.lic
$ sudo chmod 0600 <new-license-file>.lic
$ sudo cp -a <new-license-file>.lic /var/lib/rstudio-pm/
$ sudo systemctl restart rstudio-pm

Check the status of the license by running:

$ sudo /opt/rstudio-pm/bin/license-manager status

Online License Key Renewal#

To renew a license online, run the following commands:

$ sudo /opt/rstudio-pm/bin/license-manager deactivate
$ sudo /opt/rstudio-pm/bin/license-manager activate <product-key>
$ sudo systemctl restart rstudio-pm

Check the status of the license by running:

$ sudo /opt/rstudio-pm/bin/license-manager status

Offline License Key Renewal#

For offline licenses, first deactivate and reactivate the server to ensure that it picks up the new license expiration date by running the following commands:

$ sudo /opt/rstudio-pm/bin/license-manager deactivate-offline <product-key>
$ sudo /opt/rstudio-pm/bin/license-manager activate-offline-request <product-key>

Executing these commands prints an offline deactivation request to the terminal. Copy and paste the entirety of this request into the offline self-service application. You will receive a reply with a file attachment that can be used to activate offline as follows:

$ sudo /opt/rstudio-pm/bin/license-manager activate-offline <activation-file>
$ sudo sudo systemctl restart rstudio-pm

Check the status of the license by running:

$ sudo /opt/rstudio-pm/bin/license-manager status-offline

Licensing Errors#

Package Manager uses the license-manager to determine if a valid license is available. Should an error occur when interacting with the license manager, Package Manager indicates that problem in the /var/log/rstudio/rstudio-pm/rstudio-pm.log log. The license manager sends details about the error to the system messages (syslog). Consult both locations should Package Manager be unable to obtain license status.

Server log messages related to this component can be shown by enabling the licensing region. More information about activating log regions is in the configuration appendix.

Repository Count#

In part, Package Manager is licensed by the number of available repositories. In some situations, the web interface may display the message:

The number of repos exceeds the licensed repo count. Please see a system
administrator.

This error may occur if you activate your license after the evaluation and have created more repositories than your license allows. The error may also occur if you downgrade your license. A similar error also occurs if you try to create a new repository after you reach your repository limit.

This error indicates that you are in violation of your license and steps should be taken immediately:

• If you require all of your repositories, or if a mistake has been made with the license, contact Posit Support or your customer success rep.
• Consider restructuring your sources and repository subscriptions. Multiple sources can be combined into a single repository.
• Delete unused repositories.

To delete unused repositories, use the delete command, for example:

$ rspm delete repo --name=<repoName>

Package Manager continues to serve packages from all defined repositories to provide a grace period while you apply changes. However, you are obligated to bring your configuration back into compliance with your license agreement.