Distributor Getting Started Guide (TA8)

Software Potential’s Distributor allows ISVs to securely and quickly implement floatng/concurrent licensing of their applications.This article introduces Distributor and describes the practical steps in using, deploying and configuring Distributor servers.

Overview

Software Potential’s Distributor allows ISVs to securely and quickly implement floating/concurrent licensing of their applications.  One or more Distributor instances can be installed on the customers’ premises allowing:

  • Large installed base of a licensed application where it is not practical to install licenses on each installed instance (Enterprise Licensing)
  • Multiple installed instances of a licensed application where the number of installed instances exceeds the number of available licensed seats for the application
  • Web farm scenarios where the number of instances of the software can vary over time with performance and load factors (Dynamic Licensing)
  • Virtualised environments where secure license storage is not achievable e.g. ability to clone and/or rollback VMs etc (Virtual Licensing).

Distributor has been generally available for ISV’s from the 3.1.1921 release of the Software Potential Service.  Distributor clients can interoperate with server instances of different versions from that release onwards.  

How it Works

When Distributor is used with multiple instances of a licensed application, licenses are stored in a central service and allocated across the multiple instances.  Each application instance has a local Software Potential runtime component which has been configured to use the Distributor Service; the latter can hosted locally on one of the client machines or, more typically, on a different machine accessible on the network to the client machines on which the protected application is running.

When executing protected code which requires a license, the local Software Potential runtime (Agent) will call to the Distributor service to request a license for the protected feature being executed.  The service will return a lease on a license from its available local licenses.

Steps in Setting up Distributor Environment

The process is very straightforward and involves the following activities:

  • Setup your protection environment to protect and package your assemblies for use with Distributor.
  • Setup a Distributor Server.
  • Issue and activate Distributor only licenses on a Distributor Server.
  • Checkout licenses for use with applications disconnected from Distributor
  • View Distributor usage

Step 1 - Setting Up Protection Environment

If you have not already setup the protection environment you will first need to generate and download a permutation and the Code Protector SDK. See the Knowledge Base article http://www.inishtech.com/KB5 for detailed instructions.

  • Generate a new permutation or update your existing permutation to the latest version.

(The required Distributor redistributables are included in permutation versions 3.1.1921 and later.  If you are currently using an earlier permutation version you will need to update your permutation.)

  • To set up your development environment you will  need to:

a. Download and install Code Protector
b. Download and install the permutation into your Code Protector

  • Once you have completed the installation of the permutation you will need to reference the Distributor DLLs in your code (e.g. for use during installation or in a UI to manage checkouts).  To enable this add your Permutation Id to a <PropertyGroup> element in your .cs/vbproj file as follows:
     
  • <PropertyGroup>
        <SlpsRuntimeVariant>Distributor</SlpsRuntimeVariant>
        <SlpsRuntimePermutationId><Permutation ID></SlpsRuntimePermutationId>
    </PropertyGroup>
    <Import Project="C:\Program Files (x86)\InishTech SLP Code Protector\Slps.Runtime.References.targets" />
    

<Permutation ID > is the name of the Permutation file downloaded in the earlier step. Also note that you must select the Distributor variant of the Runtime to ensure the correct Distributor client and server assemblies are available to your .NET project.

These settings ensure that the correct DLLs are always taken from the Distributor folder in the Code Protector Install Directory, keeping the Code Protector version and Distributor DLLs versions in sync.

You are now ready to protect and license methods in your application.

Step 2: Protect Your Assemblies

You can choose to protect your assemblies 

  • Manually via the Code Protector UI as a post build step, or
  • Automatically with code protection integrated with Visual Studio or your MSBuild environment. 

We strongly recommend the latter approach as automation reduces the overhead involved with manual protection and removes the errors which may arise during a manual process.  This guide will explain these two approaches. 

Manual Code Protection

You can use Code Protector UI to protect the app for Distributor. This is a post build process where one loads built assemblies into Code Protector and then uses the Code Protector UI to select methods for protection/licensing.

1. Login to Code Protector with your Software Potential portal credentials

2. Add your assemblies in the project tab, loading these from the appropriate project output directory e.g. bin/Release or bin/Debug  as appropriate

3. Select the correct mandatory protection settings as follows:

 CodeProtectorDistributor-(2).png

  • Select the Permutation you just loaded into Code Protector
  • Select Distributor in Runtime/Agent Variant drop down list
  • Select the appropriate Product Name (as set in Software Potential portal when you defined your product) with which these assemblies are to be assoicated with for licensing purposes

5. Expand assemblies’ structure trees and tick methods for protection / licensing. 

4. Save the Code Protector settings in an configuration file by selecting File -> Save Project (or Save Project As..) to save a <ProjectName>.SLMCfg file in the directory alongside the corresponding .csproj/.vbproj file (where <ProjectName> is the name of the .csproj/.vbproj file).

Please note that you will need to repeat the last two steps each time you modify the method selection e.g. add or remove methods or features.

6. Click Protect to protect the assemblies. You can find the protected output in the bin/Debug.Protected or bin/Release.Protected folder.

Then please follow the instructions in the Configuration of Protected Application and Distributor Server section to configure the app and the Server.

Automated Code Protection

Instead of using the Code Protector UI to manually protect your assembly, it is recommended that the code protection step be integrated into the build process as per the guidance in Knowledge Base article KB12 so that assemblies are protected automatically as part of the build.

It is possible to conditionally control code protection at the build configuration level i.e., each Release or Debug configuration can have protection turned on or off via a compilation flag.

The steps involved are:

1. Create an <ProjectName>.SLMCfg configuration file and save alongside the .csproj/.vbproj file as in manual approach above - but do NOT select any methods for protection.

The reason not to tick methods in Code Protector UI is that in a later step you will mark methods for protection in source code; this means there is no need to update the SLMCfg to add or remove methods to be protected.

2. Set SLPS_PROTECT to the Project Properties|Build|Conditional Compilation Symbols for the relevant configurations (Release/Debug/All)

3. Select the methods in your source code to be protected.

As per our Knowledge Base article http://support.inishtech.com/KB13 marking methods in your assemblies’ source code with [Feature(“FeatureName”)] attribute identifies the marked methods as ones to be automatically licensed during the project build phase; execution of such licensed methods will require a license with the indicated feature included. 

 [Feature( "FeatureC" )]
 static void FeatureC( LocalPluginContext localContext )
 {
  //TODO – Body of Method
 }

To protect a method without associating it with a specific feature, mark the method [Feature]; any valid license will suffice to execute such methods.

4. Build your application as normal to generate protected code in the project output directory (Debug or Release, not Debug.Protected or Release.Protected as is the case in manual activation) from where they can be processed further if required. The necessary Distributor client redistributables are copied to your project output directory as well.

Configuration of Protected Application

To communicate with Distributor your protected application will require an app configuration file that includes an <appSettings> entry specifying the Server Name (or IP address) and Port Number of the service. We recommend using Server Name rather than the IP address because Server Name will rarely change which removes the maintenance overhead of changing the app config file for clients when IP addresses change.

The following is a sample entry using the default port 8371; the customer will need to enter the appropriate server name and port number if Distributor service is not set up on the default port 

<appSettings>
<add key="Slps.Distributor.Service.BaseUri" value="http://<ServerName>:8731/"/>  
</appSettings>

Or

<appSettings>
<add key="Slps.Distributor.Service.BaseUri" value="http://<IPAddress>:8731/"/>  
</appSettings>

It is worth noting that misconfiguration of the above setting is the most common cause of clients being unable to connect to a Distributor service instance in the field.

Configuration of Distributor Server

The folder Slps.Distributor.Host that is copied to your project output folder contains all the Distributor server components required to install and run a Distributor instance on a customer’s premises.

You may wish to change some of the Distributor default settings as follows:

  • All Distributor web admin pages by default display the vendor name as set up in Software Potential. You can use the “value” of the "Slps.Distributor.Web.VendorDisplayName" in the <appSettings> section of the web.config file to display an alternative name if you wish.
  • During the manual activation process the Distributor page displays some default instructions to be followed by the user when handling activation request files etc. You can use the "Slps.Distributor.Web.ManualActivationRequestInstructions" key in the <appSettings> section of the web.config file to enter alternative instruction text to be displayed.

Packaging and Installation

You may wish to package the Distributor client and server components separately e.g. provide separate installers for your protected application (together with the necessary Distributor client DLLs) and Distributor server component.

As part of the installation on your customers’ premises you need to ensure the Slps.Distributor.Host folder is copied to the machine intended to be the Distributor Server. If the required folder is not automatically copied to your project output bin folder then it can be also found in the Code Protector installation directory, usually

C:\Program Files (x86)\InishTech SLP Code Protector\Permutations\<PermutationID>\Distributor\Content\
or 

C:\Program Files\InishTech SLP Code Protector\Permutations\<PermutationID>\Distributor\Content\
 

Step 3 - Setting up Distributor Server

In any case the Slps.Distributor.Host folder contains all the server components as well as a batch file (install.cmd) to install, uninstall and configure the Distributor server components.  In an installer this folder needs to be copied to the target machine and the batch file run to install (or uninstall) the service component.

The Distributor service is installed by executing the install command file with elevated permissions (e.g. running as Administrator)

install.cmd -install


DistributorPic2.png

It can be verified that the SoftwarePotential Distributor service is running by using Windows Services control panel (Run -> services.msc).

DistributorPic3.png
 

Once installed, this service will by default listen to HTTP traffic on ports 8731 for Distributor Server and 2468 for Web Console. (These port assignments are configurable by the customer.)

Configure the protected application for Distributor Service

On each application instance intended to be a Distributor client app, the Slps.Distributor.Service.BaseUri key in the <appsettings> needs to be set with the actual Server name/IP address and port number e.g.
 

<appSettings>
<add key="Slps.Distributor.Service.BaseUri" value="http://DistributorServer:8731/"/>  
</appSettings>

Or 

<appSettings>
<add key="Slps.Distributor.Service.BaseUri" value="http://192.168.0.23:8731/"/>  
</appSettings> 

There is no need to change the default 8731 port number unless the service has been configured with a different port number.

If correctly installed it should now be possible to browse to the Distributor Web Administration portal at http://<DistributorServer>:2468/web where <DistributorServer> is either the fully qualified DNS name or the IP address of the server on which Distributor is installed.

Step 4 - Issue and Activate a Distributor License

Licenses suitable for Distributor are created from the Software Potential portal in the same manner as any other license. They can be created either:

  • Manually on an ad-hoc basis via the Issue New License page or
  • Programmatically via the CreteLicense method on our web service APIs.

Using the manual process, on the Software Potential portal, select Manage Licenses -> Issue New License. Select a retail price, the product and add features as you would do normally when creating any license.

For a Distributor license it is important that:

  • In license limitations section, the Max Instances Per Client value is set to the number of concurrent usages for the license being created i.e. a value of 2 here will allow two people to use your application at once within the Distributor system. 

 DistributorPic4.png

  • The For use with Distributor only option is checked.

 DistributorPic5.png

When completed, click Issue License. This will generate an Activation Key that your customer will need to subsequently activate the license in Distributor.

When creating a Distributor license programmatically the LicenseInfo.Limitations. MaxConcurrentUsage property must be set to a value, and the LicenseInfo.IsDistributor property must be set to True. [As of 3.1.1923 the LicenseInfo.IsDistributable flag is deprecated.]

How to Activate a Distributable License in Distributor

Distributor licenses are activated from the Distributor Web Administration portal at http://<DistributorServer>:2468/web where <DistributorServer> is either the fully qualified DNS name or the IP address of the server on which Distributor is installed. There are two ways to activate a Distributor license depending on whether the Distributor machine has internet access or not.

If internet access is available then to activate a license on the Distributor administration portal:

  • Select the Activation tab
  • Enter into the Add activation key box the license key generated in the previous step, then click Submit

DistributorPic6.png
 

  • The page will display an appropriate message if the activation has been successful and an appropriate error message if unsuccessful.

DistributorPic7.png

If there is no direct internet access available on the server then users can still activate a Distributor license:

  • Select the Activation tab and click on the Manual Activation link.

 DistributorPic8.png

  • Enter the License Key into the Add activation key box and then click Submit.
  • The License Request content will appear in the Request Date field. Copy the content and send it to the ISV (e.g. via email, HTTP or FTP).
  • The ISV then needs to logon to Software Potential portal and go to Manage Licenses tab -> Manual Activation page. Paste the License Request, select Load whereupon the license appears in the License to Activate section.  Select Activate and when the license is activated, download the License file and send it back to user (via email, FTP etc.).
  • The user can navigate to the Distributor Manual Activation page again and use the Browse to find the license file saved from the previous step and Install the license.

How to View Activated Licenses in Distributor

To see the installed license details on successful activation:

  1. Select the Products tab and then Show Licenses - this will display a summary of the license installed
  2. Select the More link to see the details of the license


DistributorPic9.png

That’s it! Distributor is now ready to automatically allocate features to instances of protected applications that have been correctly configured to communicate with it.

Step 5- View License Usages in Distributor

Distributor keeps a record of all current feature allocations (also known as License Usages) to connected clients, including checkouts. To view usages in Software Potential Distributor select the Usages tab in the Distributor Web Admin portal main menu.

If there are licenses for only one product installed the usages page will by default immediately present the active usages, if any, for that product.

If there are license for more than one product installed then you will need to click the Select link for the required product to view the usages for that product.

When the protected application is executing a protected feature, the Usages page will then show that the feature has been allocated to one or more given application instances (for the default 2 minute duration).

DistributorPic10.png

Summary

The Software Potential Distributor component allows one to implement concurrent and floating licensing models for a whole range of application types, from desktop applications to web applications running in server farms.  One or more Distributor servers must be installed on a customer premises; on Distributor service special concurrent licenses are activated, from which the Distributor service then allocates features in response to requests from suitable configured clients.

Enabling your application to support concurrent/floating licensing is a simple matter of, when protecting your application, selecting the Distributor variant included in your permutation package. This ensures the correct Distributor client and server components are available to be packaged along with your application distributable files.

The final step is for your customer to install one (or more) Distributor service instances and to configure (via a single app config setting) the client applications to communicate with the Distributor service instances.