rPath Technical Guide:Entitlement Service Administration

From rPath Wiki

The rPath Appliance Platform Entitlement Service appliance is a software appliance dedicated to managing software access for independent software vendors (ISVs) using rPath-derived products. Using an Entitlement Service appliance, an ISV can manage access by entitlements for its products through an rPath Appliance Platform Agent web interface.

This documentation is primarily for system administrators and IT personnel who possess familiarity and experience with installing, configuring, and maintaining Linux or Unix systems and software.

Install

Plan for and install rPath Appliance Platform Entitlement Service appliance using the following sections for reference.

Obtain Installation Media

To obtain rPath Appliance Platform Entitlement Service appliance installation media, please contact your rPath sales representative or field engineer for more information.

Planning and Requirements

Prepare for installation by verifying that the hardware you have selected for the rPath Appliance Platform Entitlement Service appliance meets recommended specifications as listed in the Hardware Specifications section of this document. You may also wish to assemble any information specific to your installation, such as networking parameters or other site-specific settings, and have this information available during the installation.

The Entitlement Service Appliance is packaged as a software appliance. As such, it is configured to run on dedicated hardware, including all locally-attached disk storage. DO NOT INSTALL ON HARDWARE CONTAINING DATA YOU WISH TO KEEP -- THIS INSTALLATION WILL WIPE ALL LOCAL STORAGE!

Hardware Specifications

The hardware you select for the Entitlement Service appliance should meet the following minumum requirements:

• CPU: 32-bit x86 architecture
• RAM: 512 MB
• HDD: 40 GB
• Removable Media: CD/DVD for installation media and preloading mirrors
• Network Interface: A suitable network interface with either a static or dynamic IP address accessible by an unchanging resolvable fully-qualified domain name

rPath™ recommends that the appliance is configured to receive an IP address by DHCP prior to installation.

Additional Planning Notes

Verify the following points before proceeding with installation:

• The selected hardware has a functional removable storage drive capable of supporting the installation media (CD or DVD) and that the machine has been configured to boot from this media.
• The selected hardware has a working network interface and will be assigned valid networking parameters to be accessible from other hosts on the same network segment.

Listening Network Ports

The following table details the listening network ports on a live appliance including port number, protocol, and purpose:

Disk Usage Considerations

Starting with rPath Entitlement Service version 4.0.0, a new partition schema has been implemented.

Graphical representation of the new rPath Entitlement Service partition schema

Partitions are created in the following manner:

• 100MB is reserved for the boot partition (type: ext3)
• 4GB is reserved for /var/log (type: ext3)
• The swap partition is automatically set at RAM size doubled (type: swap)
• The remaining space is encompassed by the / (root) partition. (type: ext3)

Please note that the partitions may not be created in the order presented in the image

Installation Process

When installing an rPath Appliance Platform Entitlement Service appliance from install media (such as a DVD), follow the same steps as with installing other appliances built with rBuilder. The Appliance Installation Process steps through each screen in typical a graphical install.

Configure

After installing rPath Appliance Platform Entitlement Service appliance, step through initial configuration to prepare it for use. Use the following sections as a guide.

Configure the Appliance

After rPath Appliance Platform Entitlement Service appliance installation, step through the rPath Appliance Platform Agent configuration wizard. The rPath Appliance Platform Agent is provided for web-based administration of the Update Service appliance.

To access the administration interface, use a computer system connected to the same network segment used by the appliance and a web browser with JavaScript support enabled. Access the appliance from the web browser by browsing to the following URL, replacing <appliance_hostname> with the fully qualified domain name assigned to the appliance:

Use the following steps to set up rPath Appliance Platform Agent for the Update Appliance:

1. Use the default credentials for login: username of admin and password of password.
2. Step through the initial configuration wizard to configure some common administrative tasks. Note that each configuration can be changed later using the appropriate links from the menu:
   1. Change the admin user password.
   2. Set email (SMTP) configuration for email sent from the appliance.
   3. Set notification addresses for notification messages from the appliance.
   4. Upload any entitlements required by the Entitlement Service appliance, including the entitlement provided for the appliance by rPath.
   5. Choose an initial backup configuration.

rPath Appliance Platform Agent (rAPA) was formerly known as rPath Appliance Agent (or rAA), and many components associated continue to carry this older branding.

Configure the Entitlement Server

Access the Entitlement Server Configuration page for the Entitlement Service appliance in the rPath Appliance Platform Agent web interface, and click Configuration to customize these values and override defaults prior to creating and managing entitlements.

Each of the three text boxes is followed by a brief explanation of its role in the Entitlement Service:

Company Tag

This value is a permanent string representing your entity (company or business) and used when creating product channels. If you change this value at any time, it will only affect channels created after the change. When choosing your tag, do not use spaces and avoid these special characters: ampersand (&), less-than sign (<), greater-than sign (>), single quote ('), double quotes (").

Entitlement Length

This value is the length used when generating entitlements. The default value is 128 characters, but it can be any whole number up to 255 characters. Additionally, each product can be configured to override this value.

Entitlements Per Page

This value is the number of entitlements that will be displayed when browsing a list of entitlements in rPath Appliance Platform Entitlement Service. The default value is 25. This list is displayed as part of the Entitlements page.

Update

Update the rPath Appliance Platform Entitlement Service appliance using the Updates option in the rPath Appliance Platform Agent (rAPA) web interface.

If necessary, be sure to update the entitlement for the Entitlement Service appliance itself using the Manage Entitlements rAPA page.

Maintain

Maintain the rPath Appliance Platform Entitlement Service appliance using the Appliance Administration resources provided for appliances. Administrators should rarely need to perform tasks outside of the appliance's rPath Appliance Platform Agent web interface.

Manage Entitlements

Administrators of an rPath Appliance Platform Entitlement Service appliance may or may not overlap with the regular rPath Appliance Platform/Entitlement Service users who are creating and managing entitlements for distributed software appliances. The following sections provide some entitlement management options for appliance administrators that go beyond that of typical appliance users.

Add Entitlements

Add entitlements to the Entitlement Service appliance in one of two ways: rPath Appliance Platform Agent or XML-RPC.

rPath Appliance Platform Agent

The rPath Appliance Platform Agent provides a web interface with options for bulk addition of entitlements. Use the Entitlement Service appliance to generate a specified number of random entitlement strings, or use the text input to paste entitlements generated from another source.

Each entitlement can have an optional comment associated with it that allows administrators to identify to which customer it belongs. The entitlement will be pushed to every service to which the product is associated so that when used on a system, the system can find updates on all of the appropriate repositories.

XML-RPC Interface

The Entitlement Service appliance provides XML-RPC for adding entitlements using the following parameters:

• Call URL: https://admin:password@host.example.com:8003/rAA/entwebui/EntitledCustomers/
• Method: addEntitlements(channel, keyArray, comment="") where channel is the name of the product channel, and keyArray is a list of entitlements to add to the channel; the comment parameter is optional and corresponds to the optional comment in the Appliance Agent.

Revoke Entitlements

Revoke an entitlement in the rPath Appliance Platform Agent by clicking the "Revoke" button corresponding to the entitlement. This immediately removes the entitlement from every service, and access is be denied.

The XML-RPC equivalent for revoking entitlements uses the following parameters:

• Call URL: https://admin:password@host.example.com:8003/rAA/entwebui/EntitledCustomers/
• Method: deleteEntitlements(channel, keyArray) where channel is the name of the product channel, and keyArray is a list of entitlements to add to the channel