rPath Appliance Platform/Entitlement Service:Appliance QuickStart

From rPath Wiki

Use this QuickStart page to set up a new Entitlement Service appliance.

Assumptions

This guide assumes you have obtained hardware to meet minimum requirements and used installation media and the customer-assigned entitlement from rPath to install the appliance and step through the initial configuration wizard in the rPath Appliance Platform Agent interface (http://<hostname>:8004). The following example values are used throughout is guide; be sure to replace them as needed in each step:

• Entitlement Service hostname: res.example.com
• Update Service hostname: rus.example.com
• rBuilder hostname: rba.example.com
• Project labels to which entitlements apply: prodweb.example.com@corp:1, proddb.example.com@corp:1

Access the Interface

All operations for managing entitlement services and the Entitlement Service appliance are performed in the rPath Appliance Platform interface: https://<hostname>:8003 where <hostname> is the fully qualified domain name (FQDN) of the Entitlement Service appliance (such as res.example.com). After initial configuration, ensure you are logged on as admin (or a user with an admin role) to the Entitlement Service appliance agent interface.

Workflow for Entitlement Service Setup

The basic workflow for setting up the Entitlement Service appliance is as follows:

1. Set up providers and associated services for upstream Update Service repositories.
2. Set up access controls for labels and troves in the Update Service repositories.
3. Set up products to associate with services.
4. Set up product channels.
5. Generate entitlements.

1 -- Set up Providers and Services for Update Service Repositories

Your Update Service is a provider that must be configured in your Entitlement Service appliance. As described in the following sections: generate an administrative entitlement in the Update Service appliance, use that information to add the Update Service appliance as a provider, and associate the provider with services.

1.1 -- Generate an Update Service Administrative Entitlement

Generate an administrative entitlement in the Update Service appliance that will provide access to repositories containing appliance components:

(Update Service) Manage Administrative Entitlement --> Generate --> OK

Copy the information displayed in the Update Service interface for use in configuring the Entitlement Service. The following is an example of Update Service administrative entitlement information:

• Resource Type: rBuilder Mirror -- This is the previous brand name of the Update Service appliance.
• Server Name: rus.example.com
• Server URL: https://rus/conary/
• Entitlement Class: management
• Entitlement: 3ia0w6up0yzaq7us2l7zlx53a5agl12ix4lhqufj9hrimoehbuky8

1.2 -- Add the Update Service Provider

Add the provider in the Entitlement Service appliance to communicate with your Update Services.

rPath Entitlement Server --> Services --> Providers (tab) --> Add a provider

The following is an example entry related to the previous information:

• Provider name: Example Update Service
• Resource type: rPath Update Service
• Entitlement class: management -- This was obtained from the Update Service as previously explained.
• Entitlement key: 3ia0w6up0yzaq7us2l7zlx53a5agl12ix4lhqufj9hrimoehbuky8 -- This was obtained from the Update Service as previously explained.
• Host: rus.example.com -- This was obtained from the Update Service as previously explained.
• Managed channel: -- Leave this blank for Update Service providers.

1.3 -- Associate the Update Service Provider with Services

After setting up your Update Service as a provider, associate that provider with services. rPath Entitlement Server --> Services --> Services (tab) The following is an example entry:

• Service: productweb -- Choose a name based on the software to which the service provides access.
• Repository Hostname: productweb-rus.example.com -- This is the repository hostname associated with this service, not the hostname of the Update Service appliance. The repository hostname identifies the repository where appliance components reside, and users entitled to this service can access specified components in that repository.
• Provider: Example Update Service -- Select the Update Service provider just created.
• Can Mirror: No -- This may be left at the default setting (No).

Additional new services (in a disabled state) may be listed after you have created your service, representing all the preexisting access groups on the Update Service appliance.

2 -- Set up Access Controls for Update Service Repository Contents

Though the configured services provide access to the Update Service repositories, you must specify the access controls (permissions) on those services to identify which repository contents can be accessed using a particular entitlement. Typically, repository contents have Conary labels that identify the release of an appliance product. Troves (a term used to describe repository contents) can be specified when an entitlement should not provide access to all contents on a label. (rPath's recommended release management includes specifying a label to associate with an appliance product, and all troves on the release label should apply to the appliance product.) Your appliance developers, using your rBuilder, should provide the appropriate label and trove values associated with a particular product (using regular expressions when applicable).

rPath Entitlement Server --> Services --> Access Control (tab) --> Add another permission

The following is an example entry:

• Description: productweb-all
• Services Affected: productWeb -- Hold down the control (Ctrl) key to select two or more services from the list that are affected by this access control.
• Trove: ^productweb(|:.*)$ -- Use the trove names or a valid regular expression (such as .*:runtime) as determined by your appliance developers and your release management strategy, or use "ALL" to identify all troves on the labels specified in this access control entry.
• Label: productweb.example.com@rpl:1 -- Provide an exact label to entitle as determined by your appliance developers and your release management strategy, or use "ALL" to identify all labels in the repository associated with the "services affected." A regular expression may not be used here.
• Advanced: -- rPath recommends leaving the default permissions of read-only, which is sufficient to provide Conary updates; do not add other permissions unless you are certain this is absolutely necessary.

Use the Edit and Delete actions for each existing list item to modify or delete access controls.

3 -- Set up Products to Associate with Services

Products in the Entitlement Service appliance define the services which should apply to a particular appliance product. Though the Update Service labels may imply a product's identity, they are only part of "services" to which a product can associate. A product connects the actual entitled appliances to those services, and thus to the associated repository contents from which they can receive updates.

rPath Entitlement Server --> Products --> Products (tab)

The following is an example entry:

• Product Name: productweb -- DO NOT use spaces or special characters.
• Product Description: ProductWeb -- This is optional.
• Entitlement Length: 32 -- Only modify this if you wish to override the set entitlement length for automatically generated entitlements.

Click Services next to the new product to shift to the Product Services tab. Ensure the new product is selected in the drop-down list, and use the left and right arrows to move services betwen the Services Available and Services Selected lists. Click OK to save the changes to the product services so they will not be lost when you navigate to another page.

4 -- Set up Product Channels

Set up a product channel to represent each sales channel for a product. Direct sales to consumers occur on DIRECT channels, and sales through resellers occur through channels created for each reseller.

rPath Entitlement Server --> Products --> Product Channels (tab)

Verify that a direct channel is created for each product you have created. If you do not sell directly to consumers, and product resellers have their own entitlement services, you may need to disable this DIRECT channel; see Establish a Managed Product Channel Structure for Resellers after this workflow for more information.

5 -- Generate Entitlements

Entitlements must be generated for the following types of product sales:

• Appliance products may be directly sold to consumers on a DIRECT channel (on entitlement for each direct sale to an appliance product consumer). One entitlement should be generated for each directly-sold product.
• Resellers may sell appliance products and provide their own entitlement structure "downstream" from you, using their own Entitlement Service appliances. Reference the Establish a Managed Product Structure for Resellers section at the end of this document for more information.

rPath Entitlement Server --> Entitlements --> Generate Entitlements (tab)

The following is an example entry for generating entitlements on a direct channel:

• Channel in which to place new entitlements: productweb-DIRECT -- Select the product channel from the drop-down list to identify the product channel to which the entitlements apply, which should indicate the product and its resellers.
• Comment (optional): (none)
• Generate new entitlements (count): 500 -- Use a whole number of entitlements you need to generate for the product channel.

6 -- Include entitlements.xml in Appliance Products

Ensure that each appliance product includes the file /etc/conary/entitlements.xml that is appropriate to its product channel:

• Entitlement Service administrators: Use the entitlements.xml link in Products --> Product Channels to download the appropriate file to correspond with a direct or managed channel, and provide this file to appliance developers. Then, generate entitlements associated with the products on those appropriate product channels.
• Appliance developers: Use a Conary package to install the file in /etc/conary/entitlements.xml on each appliance product.
• Appliance consumers: Use the rPath Appliance Platform Agent after installing the appliance product to step through the configuration wizard, entering the provided entitlement string when prompted.

The entitlements.xml file ensures that the entitlement provides the product (appliance) updates granted by entitlement.

Establish a Managed Product Channel Structure for Resellers

After the previous setup is complete, use the following sections when necessary to set up a managed product channel structure for resellers.

Create Product Channels for Resellers

Create a new product channel for each product reseller. Select a product from the drop-down list, and create the new product channel with the following considerations:

• Name the product channel to reference the product reseller.
• DO NOT use spaces in the product channel name.
• After creation, verify that two new channels appear in the list: one with the reseller name that you typed, and one with that name and a -MANAGE suffix directly below with an arrow pointing to the channel above it.

Generate Entitlements for Resellers

Generate an entitlements for a reseller on your managing (MANAGE) channel for each configured reseller. The following is an example entry for a managing channel:

• Channel in which to place new entitlements: websellercorp-productweb-MANAGE
• Comment (optional): ProductWeb for Web Seller Corporation.
• Generate new entitlements (count): 1

Verify the newly generated entitlements are listed on the Entitlements tab after creation.

Add Entitlements as a Reseller

As a reseller for products using an upstream Entitlement Service, add one or more entitlements as needed.

rPath Entitlement Server --> Entitlements --> Add Entitlements (tab)

The following is an example entry:

• Product Channel: rpath-prodexample-MANAGE -- The class to place new entitlements should match the product channel to which the entitlement services should apply.
• Default comment (optional):
• Entitlements: -- List each entitlement string by placing each new string on a new line in the text box, or use the Entitlements (upload) field to upload a text file of entitlements in the same format. If desired, type a space after each entitlement string, and type a comment on the same line to aid in identifying the entitlement with its recipient.

Coordinate Entitlement Services between Vendors and Resellers

Coordinate entitlement services between downstream Entitlement Service appliances used by product resellers:

• Disable the direct channel for each product (sales) channel in which the product is only provided to resellers who use a downstream Entitlement Service appliance to entitle products. (Each direct channel has an associated entitlements.xml link.)
• Create a product channel for a product for each of the product's resellers. The managing (-MANAGE) channel and the entitlement is automatically grouped with other information from your Entitlement Service appliance to provide the necessary information to the downstream Entitlement Service appliance.
• For each product reseller, ensure the downstream Entitlement Service appliance creates a service associated with your local Entitlement Service appliance ("Add Provider"). Supply information to the administrators to set up the provider using the following information. The following is an example entry:
  • Resource Type: rPath Entitlement Appliance -- This must always be the downstream Resource Type value.
  • Service: productweb -- This is the product name on your Entitlement Appliance to which the product channel belongs.
  • Server Name: res.example.com -- This is the FQDN for your Entitlement Service appliance.
  • Server URL: https://res.example.com:8003/rAA/entwebui/ -- This field should be filled in automatically by the Entitlement Service appliance, but it can be modified if necessary to ensure a correct URL.
  • Entitlement Class: websellercorp-productweb-MANAGE -- This is the managing channel on which the new entitlement resides.
  • Entitlement: VN1gfKcMdkfoPE93jr03kS02kr04kfGf2ks9;02ked0gfLe0284:5jWLWqnskCik -- This is the new entitlement string you created for the managing channel.
  • Managed Channel: websellercorp-productweb -- The new managed channel that was created on your Entitlement Service appliance (without the -MANAGE suffix).

Synchronize Entitlements

Synchronization of entitlements will push out Services and Permissions, Products and Channels, as well as all entitlements to all mirrors. This is Synchronize Entitlements pushes out all entitlements to your mirrors. This ensures that if something is desynchronized it is resynchronized with the click of a button. See the Entitlements Synchronization Section for more details.