rPath Technical Guide:Update Service

From rPath Wiki

The rPath Appliance Platform Update Service is driven by the Update Service appliance. The Update Service appliance is a server dedicated to managing software repositories that provide updates to deployed appliances.

The Update Service appliance is based on the rPath Appliance Platform and provides administration through the rPath Appliance Platform Agent web interface. Much of the installation and maintenance of an Update Service appliance is similar to that of rBuilder Appliance and incorporates typical appliance administration tasks powered by the rPath Appliance Platform. The sections of this guide provide instruction and reference for installing, configuring, and maintaining an Update Service appliance.

Install

Plan for and install the Update Service appliance using the following sections for reference.

Obtain Installation Media

To obtain the Update Service appliance installation media, please contact your rPath sales representative or field engineer.

Prepare for Installation

Prepare for installation by verifying that the hardware you have selected for the rPath Update Service server 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 rPath Mirror 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 use as an rPath Appliance Platform Update Service server should meet the following minimum requirements:

• CPU: Server-class 32-bit x86 architecture with one or more 2+ GHz processors
• RAM: Minimum of 2 GB
• HDD: Minimum of 250 GB high-performance storage (Mirroring rPath Linux requires particular storage amounts per branch, which will grow over time.)
• Consider the storage requirements of your own projects, and add adequate storage for their growth
• Removable Media: CD/DVD for installation media
• Network Interface: A suitable network interface with either a static or dynamic IP address accessible by an unchanging resolvable fully-qualified domain name

The server should be configured to receive an IP address and fully-qualified domain name prior to installation. The permanent FQDN is required for appropriate Update Service interactions with rBuilder and deployed appliances.

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 including port number, protocol, and purpose:

Disk Usage Considerations

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

Graphical representation of the new rPath Update 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 the Update Service appliance from install media (such as a DVD), follow the same steps as with installing other appliances provided by rPath. The Appliance Installation Process steps through each screen in a typical graphical install.

Configure

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

Initial Appliance Configuration Wizard

After the Update Service appliance installation, step through the rPath Appliance Platform Agent configuration wizard. The rPath Appliance Platform Agent (rAPA) 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 the rPath Appliance Platform 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 Update Service, including the entitlement provided for the appliance by rPath™.
   5. Choose an initial backup configuration.

rPath Appliance Platform Agent was formerly known as rPath Appliance Agent (rAA) and many components associated with the rPath Appliance Platform continue to carry that branding.

Configure the Appliance Repository

After the Update Service appliance installation and configuration, configure the appliance repository to receive mirrored contents from one or more rBuilder Appliance instances.

As of version 4.1, this configuration screen has been removed from the Update Service

Access the rPath Appliance Platform interface and perform the following steps:

1. Log in as an administrator user.
2. Click Update Repository Hostname from the left side menu.
3. Use the interface to add each rBuilder Appliance hostname from which mirrored contents will be received.

Click the corresponding [X] to delete any entry if it is incorrect or no longer in use. However, note that any contents committed to the Update Service repository under a particular label cannot be removed from that repository and label.

Configure Users

After the Update Service appliance installation and configuration, the rBuilder Appliance repositories from which the appliance is configured to receive mirrored content require permission to write that content to the Update Service repository.

Common use for this plugin: A user who needs non-entitlement access to a repository or those using the Update Service disconnected from an rBuilder. This plugin will only apply to users with these unique situations

Access the rPath Appliance Platform interface and perform the following steps:

1. Log in as an administrator user.
2. Click Manage Repository Users from the left side menu.
3. Click the Add User tab.
4. Type the user credentials for the new user: username, password, and password confirmation.
5. For Permission, select from the following options:
   Mirroring: The user can mirror contents to the Update Service repository. rBuilder Appliance provides the user’s credentials when mirroring. The write permission for the user is automatically set for this user.
   Anonymous: The user has read-only access to the contents the Update Service repository. No authentication is required. The appliance automatically completes the user credentials for this selection.
   Admin: The user can perform administrative tasks on the Update Service appliance Conary repository. The write permission for the user is automatically set for this user.
6. Click Apply to create the user.

Use other interface options as needed to add, modify, and delete repository users.

User Roles

A role allows you to create a rPath Appliance Platform User user with limited permissions called mirror. The mirror user is only allowed to change update service server names and repository users. A user that has the mirror role will not be able to restore backups, update troves, and other administrative functions.

Here's how to setup the mirror role:

1. Log into the rPath Appliance Platform Update Service.
2. Click on User Management .
3. Click on Manage Groups.
4. Create a new group and assign it the mirror role.

A new user can be now created using the group with the mirror role.

The user with the mirror role can now update the Update Service server names and repository users, but has no administrative access.

Add Appliance Entitlements

The Update Service appliance handles two types of entitlements: an entitlement key for the appliance itself, and an administrative entitlement used by rPath™ Appliance Platform Entitlement Service to create and revoke entitlements for access to the mirrored repository contents.

Entitlement Key for the Appliance

The Update Service appliance requires an entitlement provided by rPath as part of the Update Service appliance purchase.

Use the Manage Entitlements option in the rPath™ Appliance Platform Agent on the appliance to enter this entitlement. This allows your Update Service to access updates published by rPath™.

Administrative Entitlement

The Update Service repository may include contents that require an entitlement from distributed software appliances. An entitlement authenticates these appliances and determines what software in the repository are available to them. These entitlements are created and managed on an rPath Appliance Platform Entitlement Service appliance.

If the Entitlement Service is part of the appliance distribution plan, the Update Service appliance should provide an administrative entitlement to the Entitlement Service appliance. The administrative entitlement gives the Entitlement Service appliance access to push its entitlements to the Update Service appliance, avoiding the need for the Update Service administrators to manually maintain these entitlements.

Use the following procedure to generate an entitlement from the Update Service appliance for use by the Entitlement Service:

1. Log in to rPath Appliance Platform Agent on the Update Service appliance as an administrative user.
2. Click Manage Administrative Entitlement from the menu at the left.
3. Click Generate to generate an administrative entitlement key.
4. Click OK to save the administrative entitlement key.

Update Service administrators must provide the administrative entitlement, entitlement class, and any related information to Entitlement Service users. Entitlement Service users must use this information on the Entitlement Service appliance when creating a new service for the Update Service appliance.

In a recovery or migration configuration, meaning that an administrative entitlement key was already generated by the Update Service appliance, copy the previously generated key from the Entitlement Service appliance instead of generating a new key. Click OK to save this copied value as the administrative entitlement key.

Update

Update the Update Service appliance using the Updates page in the rPath Appliance Platform Agent (rAPA) web interface. Verify the currently installed appliance version at any time by noting the dotted number that immediately follows the string starting with group-.

When updating both rBuilder Appliance and the Update Service appliance, the order in which they should be updated is unimportant: either appliance could be updated first.

If necessary, be sure to update the Update Service entitlements using the Manage Entitlements rAPA page.

For updates prior to version 2.0.0, an rPath field engineer must perform the updates using an update script. See your rPath technical representative for more information.

Maintain

Maintain the Update 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. Some particular tasks that require special consideration are described in the following sections.

This information is now maintained as part of rBuilder Packaging and Automation at docs.rpath.com... for rBuilder 5.2.4, for example, see:

http://docs.rpath.com/rbuilder/5.2.4/rBuilder_5.2.4_Packaging_and_Automation/appendix-adding_conary_configuration.html

Update your bookmarks as appropriate.

Appliance Command Line

Though the majority of Update Service appliance tasks can be performed in its rPath Appliance Platform Agent web interface, some tasks may require command line access. This access is provided for remote connection with secure shell (SSH). Use a SSH client to access the appliance and log in as the root user for administration.

If you are using OpenSSH or a similar client found on many Linux distributions, use the ssh command in fashion of the following where <appliance_hostname> is the fully qualified domain name assigned to the Update Service appliance:

$> ssh root@<appliance_hostname>

The nano text editor is provided for modifying files at the command line in the rare occasion this becomes necessary. Launch the editor with nano -w. The -w option prevents automatic line breaks, which can cause problems with configuration files. Other text editors such as vi are also available and are started from the command line as well.

Backup Strategy

The Update Service appliance can be recovered from catastrophic failure by reinstalling the appliance image to the hardware, restoring the previous configuration, and reestablishing mirrors of the necessary repositories. However, if the appliance is used to mirror several large repositories, recovery of the appliance after such a failure could require a significant amount of time to rebuild the mirrors. Use the information in the following sections to provide faster recoveries.

Back Up Critical Configuration and Repository Data

Back up the Update Service appliance's critical configuration and repository data as shown in the following table. Administrators must backup all of the following data to ensure a complete backup of an Update Service appliance and to expedite the recovery process.

Recover from a Catastrophic Failure

Choose the process from the following sections that matches your recovery situation. If the backup strategy includes the critical configuration an repository data described in the previous section, follow the steps presented in Recovery with Critical Data Backup. Otherwise, follow steps in the Recovery without Critical Data Backup section.

As of rPath Appliance Update Service 4.0, the rPath Appliance Platform Backup Plugin is installed and enabled by default. The plugin can be configured through the administration interface and is identical in operation to the standard backup plugin. Be advised that this backs up all data and creates a compressed archive locally on the rUS for retrieval. Depending on the size of the rUS, this archive may be quite large. Be cautious before attempting these backups.

Recovery with Critical Data Backup

Locate the most recent backup data and take the following steps to recover the Update Service appliance:

1. Install the Update Service appliance as on its first installation and update it (if necessary) to the software version most recently backed up.
2. Restore all of the critical configuration and repository data from the backup.
3. Use command line access to the appliance to restart the httpd and raa services:
   #> service httpd restart
   #> service raa restart
4. Access the Update Service appliance web interface and log in as an administrator to make any additional adjustments and to verify the restore.

Recovery without Critical Data Backup

Use this section as a guide to recover the Update Service appliance when critical configuration and repository data are not backed up.

You will need the following information to successfully recover the appliance:

• Administrator Password: The user credentials for the admin user in the rPath Appliance Platform web interface
• rBuilder Appliance Repositories: The project hostnames for repositories mirrored to the Update Service appliance
• Repository User Details: The Update Service repository user credentials for all projects which were mirroring to the appliance; alternatively, administrators can define new mirror users and update the rBuilder Appliance outbound mirror settings for each rBuilder project.
• Entitlement Key: The entitlement key for the Update Service appliance

Use the following steps to continue recovery after obtaining this information:

1. Install the Update Service appliance as on its first installation.
2. Step through the initial appliance configuration, including modifying the admin user credentials.
3. Configure the Update Service appliance repository by adding each rBuilder Appliance which will mirror to it.
4. Configure the repository users authorized to access the Update Service repository.
5. Add entitlement keys used by the Update Service appliance.
6. After sufficient time for scheduled mirroring to occur, rebuilding the mirrors, verify that the mirrors are accessible and complete. rPath suggests comparing conary rq output between the rBuilder Appliance repository and its mirrored label in the Update Service repository.rBuilder/Administration Guide:Appliance Administration

External Entitlement Verification

rPath Appliance Platform Update Service (rUS) uses an internal entitlement verification scheme by default, but can also be configured to use an external entitlement verification system. For example, if your organization wishes to verify entitlements through a customer relationship management system (CRM), rUS can be configured to query the CRM system's web service for entitlement verification.

This guide explains the necessary rUS configuration for rUS administrators, and details integration requirements for the external verification system infrastructure for external web service developers.

Enabling an external entitlement verification system involves configuration of rUS through web interfaces, and by editing rUS configuration files. The following steps are detailed in this document:

• rUS Configuration Verification - Verifying rUS is updated to the latest software release
• Entitlement Creation - Creating entitlements that grant access to the rUS repository
• Editing rUS Repository Configuration - Enabling external entitlement verification for rUS repository
• Implementing Entitlement Verification Web Service - Information on how rUS calls the HTTP web service and what it expects in return

In addition to detailing the configuration process, this document also describes the external entitlement verification web service communication semantics and query formats in the External Entitlement Verification section.

rUS Configuration Verification

Before configuring rUS to use an external system for entitlement verification, ensure it is updated to the latest software release. Follow these steps to update rUS to the latest version:

1. Access the rUS web interface
2. Click Updates
3. Click Apply Now

The rUS will begin applying updates. When all updates are successfully applied, you can continue using rUS's web interface to configure the repository as detailed in the following sections.

Entitlement Creation

External entitlement verification uses a HTTP web call to a service that verifies entitlement credentials that are provided to the rUS. If the credentials should allow access, the web service provides an entitlement document over the HTTP connection that provides the actual credentials for repository access. Basically, when using the external entitlement verification scheme, you are mapping many "virtual" entitlement keys to a single entitlement key needed for access.

There are two methods for setting up entitlements in an Update Service. First, an rPath Appliance Agent Entitlement Service can be used to define products and create entitlement keys that provide access to those products. Second, entitlement classes and keys can be managed, manually, directly in the rUS. For information on setting up entitlements manually, see the manual entitlement setup page

Once the entitlements are configured, an entitlement key must be created for use by the external entitlement verification web service. In this example, we will use an entitlement class called myProduct and an entitlement key of 03d59e663c1af9ac33a9949d1193505a8460731e.

Editing rUS Repository Configuration

rUS Entitlement Mapping Configuration

Configure rUS to perform external entitlement verification with the entitlementCheckURL configuration directive. Specify the external entitlement verification URL to entitlementCheckURL in rUS's repository configuration file (/srv/conary/repository-custom.cnr) with these steps:

1. Access rUS command line interface
2. Edit /srv/conary/repository-custom.cnr using the installed text editor (for example, vi or nano)
3. Add an entitlementCheckURL directive, and specify the URL to your external verification service:
   entitlementCheckURL http://webservice.example.com/
4. Reload rUS's apache httpd server by executing:

[root@appliance ~]# killall -USR1 httpd

rUS is now properly configured to perform external entitlement verification queries.

Implementing Entitlement Verification Web Service

The following sections describe the rUS repository's interaction with an external verification service, including the format of the repository's GET query, and expected results from the external verification service. Use this information to ensure that your external verification service returns the correct data to queries from rUS.

External Verification Query

Once rUS has been configured for external entitlement verification, the repository will perform such verification through a GET query on the URL value specified in entitlementCheckURL, and include potentially 4 arguments for verifying the entitlement group and key:

• server: The Repository Hostname of the Conary repository that is being accessed
• class: Class name for product entitlement (deprecated)
• key: Identification key required by external verification system (for example customer identifier for CRM system)
• remote_ip: IP address of requesting client (if available)

Suppose, for example, that the entitlement verification will be performed by a CRM web service, and for this example query, the customer's CRM identification code is w45tv-23xda-e4dd2-11zgv. The query sent to the CRM web service will resemble the following:

http://webservice.example.com/service?server=rm.example.com;class=myProduct;key=w45tv-23xda-e4dd2-11zgv

The CRM web service should ideally rely only on the key parameter for validation. Other parameters, such as remote_ip are only provided by newer versions of the Update Service.

Access Entitlement Document

The external entitlement verification service must access appropriate customer information to determine account status for the identification string passed in the query.

If the web service check determines the account should be granted access, it should return HTTP status code 200, and and an XML document containing the access entitlement, and resembling the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<!DOCTYPE entitlement [
<!ELEMENT entitlement (server, class, key)>
<!ELEMENT server (#PCDATA)>
<!ELEMENT class (#PCDATA)>
<!ELEMENT key (#PCDATA)>
]>
<entitlement>
  <server>rm.example.com</server>
  <class>myProduct</class>
  <key>03d59e663c1af9ac33a9949d1193505a8460731e</key>
</entitlement>

If the web service check determines the customer account should not have access to the product, the web service should return HTTP status code 404.

Manual Entitlement Setup

In rare circumstances, when the rPath Appliance Platform Entitlement Service is not appropriate for a rPath Appliance Platform Update Service (rUS) deployment, entitlements can be created manually using the web interface to rUS.

Use the steps outlined in the following sections to configure entitlements manually in rUS.

1. Configure the rUS Repository -- Verify the rUS repository and ensure an administrator account is enabled for the repository.
2. Configure the Access Group -- Define the necessary repository access rights for a specific entitlement.
3. Create the Entitlement Class -- Create an entitlement class to be paired with the access rights defined in the access group configuration.
4. Add an Entitlement Key -- Establish the entitlement key used by the external verification web service to grant repository access.

Configure the rUS Repository

The first step in setting up entitlements manually is to define an administrator user for the rUS repository.

If your rUS has an existing administrator user account, proceed to the rUS repository interface step. Use the name and password of the existing administrator account when prompted.

Use the following these steps to create an administrator account for the rUS repository:

1. Click Manage Repository Users.
2. Type a username and password for the administrator account.
3. Check the Admin permission.
4. Click Apply.

After ensuring there is an administrator account, use a web browser to access the rUS repository interface URL ( such as https://rus.example.com/).

When prompted for a name and password, use the administrator username and password that you just created, or provide the credentials for an existing repository administrator.

Configure the Access Group

After signing in to the rUS repository interface, configure a group that defines permissions for a specific class of users:

1. Click Users and Groups.
2. Click Add Group.
3. Type a descriptive name for the group (such as myProduct). You can include a version number in the group name for partitioning of permissions based on product version.
4. Click Add Group.

After creating the group, specify permissions for that group:

1. Click Add Permission.
2. Use the interface to add permissions associated with this group of users. If you do not need to partition permissions, then you can grant access permissions to the entire repository. In that case, click Add to accept the default access permissions.

To partition the access privileges, select the appropriate label and trove versions before adding the permissions.

Create the Entitlement Class

After configuring the group and its permissions, create a new entitlement class. The entitlement class is paired with the access group to grant permissions to the repository. Use the following steps:

1. Sign into the rUS repository interface.
2. Click Manage Entitlements.
3. Click Add Entitlment Class.
4. Type a descriptive name for the Entitlement Class (such as myProduct), and select the group created in the previous section.
5. Click Add Entitlement Class.

Add an Entitlement Key

Add an entitlement key for all users in the newly created entitlement class:

1. Click X in the Manage column for your new entitlement group.
2. Click Add Entitlement.
3. Type a random string as the key (such as 03d59e663c1af9ac33a9949d1193505a8460731e, though you should create a different key other than this example).
4. Click Add Entitlement.

Distribute the new entitlement key as needed to Conary clients (such as Conary-based appliances built with rBuilder) to grant access to the repository.