Licensing#
When Package Manager is first installed on a system it operates in an evaluation mode for a period of time and then subsequently requires activation for continued use.
To determine the current license status of your system, you can use the following command:
sudo /opt/rstudio-pm/bin/license-manager status
After purchasing a license to Package Manager, you will receive a product key that is used to activate the license on a given system.
You can activate your license key with the command:
sudo /opt/rstudio-pm/bin/license-manager activate <product-key>
After activation, restart the Package Manager server or send it the HUP
signal.
sudo systemctl restart rstudio-pm
Note
Use a HUP
signal when your configuration changes are limited to properties marked as reloadable. Perform a full restart of Package Manager when changing other properties.
A HUP
signal only reloads configuration settings that have explicitly changed.
Commenting out a setting will not affect the configuration when using the HUP
signal. If you have commented out a setting instead of changing the setting
value, restart the Package Manager service instead of using the HUP
signal.
See the Appendix - Reloadable Properties section to learn which settings may be reloaded via HUP.*
If you want to move your license of Package Manager to another system, you should first deactivate it on the old system.
sudo /opt/rstudio-pm/bin/license-manager deactivate
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.
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
.
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
You first generate an offline activation request as follows:
sudo /opt/rstudio-pm/bin/license-manager activate-offline-request <product-key>
Executing this command will print an offline activation request to the terminal which you should copy and paste into an email to Posit customer support (support@posit.co). 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 or send it the
HUP
signal:
sudo systemctl restart rstudio-pm
Note
Use a HUP
signal when your configuration changes are limited to properties marked as reloadable. Perform a full restart of Package Manager when changing other properties.
A HUP
signal only reloads configuration settings that have explicitly changed.
Commenting out a setting will not affect the configuration when using the HUP
signal. If you have commented out a setting instead of changing the setting
value, restart the Package Manager service instead of using the HUP
signal.
See the Appendix - Reloadable Properties section to learn which settings may be reloaded via HUP.
If you want to renew your license of Package Manager or move it to another system you can also perform license deactivation offline. You can do this as follows:
sudo /opt/rstudio-pm/bin/license-manager deactivate-offline
Executing this command will print an offline deactivation request to the terminal which you should send to support@posit.co.
You can also perform an offline check of your current license status using the following command:
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). You should 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#
Package Manager is licensed, in part, 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 will also occur 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, email support@posit.co 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 will continue 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.
Floating Licenses#
Traditionally, an admin must activate a license on each Package Manager
instance by running the activate
and deactivate
commands. If you start and
stop Package Manager frequently, for instance because you are running
inside a virtual machine or docker container, it is preferable to use floating
licensing. 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. In this case, you can use the
Package Manager License Server (Package Manager License Server).
Overview#
As an administrator you'll need to follow these steps:
- Install the Package Manager License Server on a persistent server with network access to the Package Manager instance(s).
- Activate your license key on the Package Manager License Server
- Configure Package Manager to use the Package Manager License Server
- (Optional) Change the Package Manager License Server defaults
Package Manager License Server#
Follow these instructions in a persistent server that will run 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
A specific license key is necessary for floating licensing. Please reach out to support@posit.co to swap the default license key for a key that supports floating licensing.
Offline Activation#
If you are running the Package Manager Licensing Server in an offline environment you will 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 will print an offline activation request. Copy this request and send it to support@posit.co. You will receive a reply with a file attachment, use the attached file to complete the activation:
sudo rspm-license-server activate-offline <activation-file>
sudo rspm-license-server restart
Renewing or moving a floating license
If you are renewing your floating license offline or if you want to move your floating license for Package Manager to another system, then you should first perform license deactivation offline. To do this, run the following command:
sudo rspm-license-server deactivate-offline-request <product-key>
Evaluations#
Extending Evaluations#
If you are unable to complete your evaluation of Package Manager during the initial 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.
Once you have an extended evaluation key, supply it to the Posit Package
Manager license manager using the extend-evaluation
command.
sudo /opt/rstudio-pm/bin/license-manager extend-evaluation <key>
If you are performing the evaluation on a physical machine (not on virtualized hardware or containers) without a network connection, you may also request an offline evaluation extension key, which does not require an internet connection. This key may be supplied to the license manager as follows:
sudo /opt/rstudio-pm/bin/license-manager extend-evaluation-offline <key>
Note
Offline evaluation extension keys are valid only on machines which do not have Internet access and are not virtualized. For most offline evaluation extensions, you will need to generate an offline evaluation request (see below for details).
Connectivity Requirements#
Beginning Evaluations#
Generally speaking, 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 above. If however you have no means of connecting to the Internet
from inside the virtual environment, you can begin the evaluation as follows:
sudo /opt/rstudio-pm/bin/license-manager begin-evaluation-request
Executing this command will print an offline activation request to the terminal which you should copy and paste and then send to Posit customer support (support@posit.co). 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
Note
You need to restart Package Manager after starting your offline evaluation for licensing changes to take effect.
Extending Evaluations#
You may extend evaluations offline using the same pattern described above
(just use extend-evaluation-request
and extend-evaluation-offline
):
sudo /opt/rstudio-pm/bin/license-manager extend-evaluation-request
Then, when you've received the evaluation file:
sudo /opt/rstudio-pm/bin/license-manager \
extend-evaluation-offline <evaluation-file>
sudo systemctl restart rstudio-pm
Note
You need to restart Package Manager after extending your evaluation for licensing changes to take effect.
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
file. The license manager sends details about the error to the system messages
(syslog). You should consult both locations if Package Manager cannot obtain
a license.
Configuring Package Manager to Use the Package Manager License Server#
Once the Package Manager License Server is installed and activated, you need to 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.
-
Edit the Package Manager configuration file:
/etc/rstudio-pm/rstudio-pm.gcfg[Licensing] LicenseType = remote
-
In the server running Package Manager, execute:
Terminalsudo /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 will remember the Package Manager License Server address. However, if you rebuild the server or image running Package Manager you will need to re-run thelicense-server
command. -
Restart Package Manager or send it the
HUP
signal:Terminalsudo systemctl restart rstudio-pm
Note
Use a HUP
signal when your configuration changes are limited to properties marked as reloadable. Perform a full restart of Package Manager when changing other properties.
A HUP
signal only reloads configuration settings that have explicitly changed.
Commenting out a setting will not affect the configuration when using the HUP
signal. If you have commented out a setting instead of changing the setting
value, restart the Package Manager service instead of using the HUP
signal.
See the Appendix - Reloadable Properties section to learn which settings may be reloaded via HUP.*
Changing the Package Manager License Server Defaults#
These instructions refer to configuration settings on the persistent Package Manager License Server.
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, so for instance to make license leases last 30 minutes you
would 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 in order for the lease to remain valid.
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, but 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 Package Manager Lease Expiration and Renewal Default#
This configuration applies to Package Manager and 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 will be unable to do so, such as 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 you would 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 will need
to manually restart Package Manager or send it the HUP
signal in order 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.
Note
Use a HUP
signal when your configuration changes are limited to properties marked as reloadable. Perform a full restart of Package Manager when changing other properties.
A HUP
signal only reloads configuration settings that have explicitly changed.
Commenting out a setting will not affect the configuration when using the HUP
signal. If you have commented out a setting instead of changing the setting
value, restart the Package Manager service instead of using the HUP
signal.
See the Appendix - Reloadable Properties section to learn which settings may be reloaded via HUP.
Troubleshooting Floating Licensing#
Run these 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.