DOCUMENTATION

From rPath Wiki

Contents 1 rPath Appliance Platform Update Service Administration 1.1 Install 1.1.1 Obtain Installation Media 1.1.2 Prepare for Installation 1.1.2.1 Hardware Specifications 1.1.2.2 Additional Planning Notes 1.1.2.3 Listening Network Ports 1.1.2.4 Disk Usage Considerations 1.1.3 Installation Process 1.2 Configure 1.2.1 Initial Appliance Configuration Wizard 1.2.2 Add Appliance Entitlements 1.2.2.1 Entitlement Key for the Appliance 1.2.2.2 Administrative Entitlement 1.3 Update 1.4 Update the Appliance Prior to 2.0.0 1.5 Alert for Versions Before 2.0.0 1.6 Maintain 1.6.1 Appliance Repository Maps 1.6.2 Appliance Command Line 1.6.3 Backup Strategy 1.6.3.1 Back Up Critical Configuration and Repository Data 1.6.3.2 Recover from a Catastrophic Failure 1.6.3.2.1 Recovery with Critical Data Backup 1.6.3.2.2 Recovery without Critical Data Backup 2 rPath Appliance Platform Entitlement Service Administration 2.1 Install 2.1.1 Obtain Installation Media 2.1.2 Planning and Requirements 2.1.2.1 Hardware Specifications 2.1.2.2 Additional Planning Notes 2.1.2.3 Listening Network Ports 2.1.2.4 Disk Usage Considerations 2.1.3 Installation Process 2.2 Configure 2.2.1 Configure the Appliance 2.2.2 Configure the Entitlement Server 3 Logs and Reports

rPath Appliance Platform Update Service Administration

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.

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

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:

Port Number	Protocol	Purpose
22	TCP	Secure shell server (SSH)
80	TCP	Hyper Text Transport Protocol (HTTP)
161	TCP	Simple Network Management Protocol (SNMP)
161	UDP	Simple Network Management Protocol (SNMP)
443	TCP	Secure Hyper Text Transport Protocol(HTTPS)
8003	TCP	rPath Appliance Platform Agent

Disk Usage Considerations

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

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)

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.

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.

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-.

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.

Update the Appliance Prior to 2.0.0

For Update Service appliance version 1.0.0, an rPath field engineer must perform updates using the update script described on this page. This script handles the migration of the appliance software and associated repository mirrors hosted by the appliance. Note also that this script MUST be used to update an existing version 1.0.0 of the appliance, and it will result in updating to version 2.0.0 which can be updated by appliance administrators from the rPath Appliance Platform web interface. DO NOT attempt to update the the appliance manually using Conary commands.

Two script files are required for migration:

• migrate-rm-1.0-to-2.0.sh: The main script that is executed to perform the migration
• migrate_users.py: A supporting script file that should be present in the directory from which you will execute the main script.

To execute this script, you will first need rPath Appliance Platform command line access.

After accessing the command line interface, follow these steps to update your rPath Mirror to version 2.0.0:

If you will be obtaining the update script files from a remote computer using scp, you must first temporarily install openssh-client on the rM with the following command:

#> conary update openssh-client

After you have obtained the scripts, you should erase the openssh-client package:

#> conary erase openssh-client

Then, execute the migrate-rm-1.0-to-2.0.sh script to initiate the update and migration:

#> ./migrate-rm-1.0-to-2.0.sh

When the script completes successfully, the Update Service is restarted and the migration is complete.

Alert for Versions Before 2.0.0

The crontab:runtime component was arbitrarily excluded in prior versions of the rPath Appliance Platform Update Service (formerly rM or rPath Mirror). This is not an issue after updating to 2.0.0. If you have a version prior to 2.0.0, use the rM command line access to check to see if crontab:runtime is installed using the following command:

conary q crontab:runtime

If the command returns no data prior to the next command prompt, or if the command indicates the component was not found, install the component using the following command.

conary update crontab:runtime

The update command should install the component from the appropriate repository indicated by your install label path. If you have issues installing crontab:runtime, contact rPath for support.

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.

Appliance Repository Maps

Repository maps on appliances map the hostname part of a project's label to a complete URL of the project repository. This is the same values maintained with repositoryMap directives in Conary configuration (conaryrc).

For appliance distributed from rBuilder Appliance repositories, this could be the hostname. However, when an Update Service appliance handles updates for distributed appliances from rBuilder Appliance, the label's hostname must map to the Update Service hostname instead.

Packaging the repository map settings for distributed appliances is one possible solution. However, this presents challenges maintaining those settings when mappings change on the Update Service appliance.

The recommended solution, requiring less maintenance, is for the distributed appliances to obtain the repository map settings from a central location. The Update Service appliance serves these settings from the following URL where <appliance_hostname> is the fully qualified domain name assigned to the Update Service appliance:

http://<appliance_hostname>/conaryrc

Navigate to this URL in a web browser to view these repository map settings.

Add the following line to the Conary configuration for each distributed appliance to prompt Conary to obtain repositoryMap settings from the Update Service appliance, replacing <appliance_hostname> with the fully qualified domain name assigned to the Update Service appliance:

includeConfigFile   http://<appliance_hostname>/conaryrc

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.

Directory or File	Notes
/srv/conary/	The Conary database, repository data, and configuration files
/etc/	The system configuration directory
/var/lib/raa/raadb	The rPath Appliance Platform Agent database file

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.

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.

rPath Appliance Platform Entitlement Service Administration

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.

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

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:

Port Number	Protocol	Purpose
22	TCP	Secure shell (SSH)
25	TCP	Simple Mail Transport Protocol (SMTP)
8003	TCP	rPath Appliance Platform Agent (rAPA)

Disk Usage Considerations

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

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)

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.

Configure the Entitlement Server

After rPath Appliance Platform Entitlement Service appliance configuration, installers should complete the initial Entitlement Server configuration.

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.

Logs and Reports

The rPath Appliance Platform Entitlement Service appliance provides on-demand reports that can pull information from multiple Update Service appliances. Run these reports as necessary to view entitlement usage and access information. The available reports are described in the following sections.

Pull Logs

Click the click here to pull logs from all services link in the Pull Logs tab to download the current logs for all services. These logs are the record of what XML-RPC calls were made to the Entitlement Service appliance, including who made the calls. Downstream Entitlement Service appliances (using services from the current appliance) query these logs as part of their operations. This same data is used to create the on-demand Usage Breakdown reports.

Entitlements Active

The Entitlement Active report shows the quantity of entitlements enabled by each product during a specified period of time. Click the Entitlements Active tab in Logs and Reports to run this report. Click the linked dates beside Start date and End date to expand a tool for selecting new dates, and click OK to run the report for the selected dates. View the report in the table below the selected date range. Click Convert this report to TSV format to access a report file which can be saved and opened in a spreadsheet program.

Usage Breakdown

The Usage Breakdown report lists the last IP addresses used for a given product and entitlement over a specified period of time. Click the Usage Breakdown tab in Logs and Reports to run this report. Click the linked dates beside Start date and End date to expand a tool for selecting new dates, and click OK to run the report for the selected dates. View the report in the table below the selected date range. Click Convert this report to TSV format to access a report file that can be saved and opened in a spreadsheet program.

Entitlement Access

The Entitlement Access report is available from the Entitlements list in the appliance. Click Report beside an entitlement on that page to view the list of repository contents to which that entitlement has access.

<< PREVIOUS: Entitlements

NEXT: Back to the Entitlement Service appliance guide main page >>