Personal tools
     DOCUMENTATION

rPath Technical Guide:rBuilder Appliance Administration

From rPath Wiki

Jump to: navigation, search

rBuilder is the first and only development tool that simplifies and automates the creation of software appliances and virtual appliances. rBuilder combines powerful features with innovative packaging techniques to yield a repeatable appliance creation process. Appliance development makes use of rBuilder's project structure to organize appliances and their software, and it employs rBuilder to generate appliance images and to release complete appliance products.

rBuilder documentation is now available in the following locations:

Contents

rBuilder 4.1, including 4.1.0 and 4.1.1

User Guide Administration Guide
View online View online
Download HTML (compressed tar file) Download HTML (compressed tar file)
Download PDF Download PDF
Supplemental resources

rBuilder 4.0, including 4.0.0, 4.0.1, and 4.0.2

User Guide Administration Guide
View online View online
Download HTML (compressed tar file) Download HTML (compressed tar file)
Download PDF Download PDF
Supplemental resources

rBuilder 3.x and previous

Documentation for earlier supported versions is similar to the 4.0 documentation. If you are using an earlier version of rBuilder and find a discrepancy in the documentation for 4.0 and later, file a support issue with rPath Support to request the correct information that applies to your version of rBuilder.

Install rBuilder

Plan for and install rBuilder using the following sections for reference.

Obtain Installation Media

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

Prepare for Installation

Prepare for an rBuilder appliance installation by:

  • Reviewing the hardware and network requirements listed here
  • Planning how to deploy and maintain rBuilder on the network
   rBuilder is packaged as a software appliance and is configured to run on dedicated hardware, including consuming all locally-attached disk storage. DO NOT INSTALL ON HARDWARE CONTAINING DATA YOU WISH TO KEEP.

Hardware Specifications

The hardware you select for use as an rBuilder server should meet the following minimum requirements:

  • CPU: Server-class 64-bit x86 architecture with one or more 2+ GHz processors
  • RAM: Minimum of 4 GB
  • HDD: 250 GB high-performance storage
    • Includes storage for one branch of rPath Linux
    • Mirroring additional rPath Linux branches requires particular storage amounts per branch, which will grow over time
  • Removable Media: CD/DVD drive 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
  • Must be able to contact rPath's product repositories using their fully-qualified domain names (FQDNs). rPath provides projects on the following FQDNs:
    • products.rpath.com
    • conary.rpath.com
    • rap.rpath.com
Image:Bulbgraph.png   rPath recommends the server is configured to receive an IP address from DHCP prior to installation and that the server has a resolvable fully qualified domain name (FQDN) assigned to it for installation.

Additional Planning Notes

Verify the following points before proceeding with installation:

  • rBuilder is installed behind a firewall and not directly exposed through outward-facing network interfaces
  • rBuilder requires a resolvable Fully Qualified Domain Name (FQDN) to be assigned to it during installation.
  • The selected hardware has a functional removable storage drive capable of supporting the installation media (CD or DVD), and the system has been configured to boot from this media
  • The selected hardware has a working network interface and which will be assigned valid networking parameters to be accessible from other hosts on the same network segment
  • Deployment plans include using the rPath Appliance Platform as the basis for appliance development, requiring the configuration steps appropriate to add the rPath Appliance Platform (see the Configure page to follow)

Listening Network Ports

The following table details the listening network ports on a live rBuilder appliance, 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, UDP SNMP
443 TCP Hyper Text Transport Protocol Secure server (HTTPS)
8003, 8004 TCP rPath Appliance Platform Agent
35000 TCP, UDP Nagios

Disk Usage Considerations

Each rBuilder project has its own repository, and each repository's size varies based on a number of factors, including the number of committed packages, the number of modifications to repository content, and the magnitude of those changes. While a smaller project repository may only require a few hundred megabytes of storage, larger projects, such as complete operating system distributions, can require many gigabytes of storage. Consider the aggregate size of project repositories when planning disk usage and backup strategies.

Partition Schema

Starting with rBuilder version 4.0.0, a new partition schema has been implemented. Due to this new schema, upgrades from a version prior to 4.0.0 will require a new installation and a back up of data from the previous installation (contact your rPath field support representative for more information).

Graphical representation of the new rBuilder partition schema
Graphical representation of the new rBuilder partition schema

Partitions are created in the following manner:

  • 100MB is reserved for the boot partition (type: ext3)
  • 4GB is reserved for /var/logs (type: ext3, LVM)
  • The swap partition is automatically set at RAM size doubled (type: swap, LVM)
  • The remaining space is split by the / (root) partition (type: ext3, LVM) and an area governed by LVM for jobslaves.
Image:Bulbgraph.png   Please note that the partitions may not be created in the order presented in the image

Logical Volume Management (LVM)

LVM is used by rBuilder in support of jobslaves. Utilizing LVM allows rBuilder installations to increase or decrease partition size at will and adapt dynamically to increases or decreases in activity. The default layout performs a split of the hard disk space available and allocates 4GB for logs, Swap at double the amount of RAM present, and the remaining space for the root partition. These partitions may be varied depending on your needs and can be manually set during installation.

Installation Process

When installing rBuilder 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.

An rBuilder Appliance installation takes approximately 30 minutes.


Configure

When rBuilder first boots after installation, it starts web services and puts administration interfaces into their initial configuration mode. To access the rBuilder administration interface, access the rBuilder from a JavaScript-enabled web browser using a typical HTTP URL formed by the rBuilder's hostname and your local DNS domain (such as http://rbuilder.example.com).

The following sections step through three initial configuration steps:

  1. Complete the rBuilder site configuration to complete rBuilder's settings.
  2. Step through the rAPA configuration wizard to perform initial rBuilder appliance administration.
  3. Add the rPath Appliance Platform as an externally-managed project.

rBuilder Site Configuration

rBuilder should display a configuration page upon the first successful access to the web interface. Use this page to add or modify some initial characteristics of the rBuilder configuration, including specifying branding information, host and domain names, repository setup, and the initial rBuilder administrator account details. Some of the field values are populated with default settings that you can modify as needed.

For Branding:

  • Type your organization's name.
  • Type the URL to your organization's public website or intranet website.

For Server Setup:

  • Type the hostname to be used for access to this rBuilder instance.
  • Type the domain name to be used in conjunction with hostname from above for access to this rBuilder Appliance instance.
Image:Bulbgraph.png   The hostname should differ from any project name used on the appliance. See this TECHTIP for more information.

For Repository Setup: Set this to a value appropriate for your intended usage of rBuilder. rPath suggests working with a field engineer to find a value that corresponds with the organization's product development and release management.

For Initial Administrator Account: Complete this form for the initial administrator account that will have unrestricted access to the entire rBuilder.

Click Save Changes to save the initial configuration. Verify rBuilder redirects to a page confirming successful configuration and providing a Launch button. Click Launch to complete the configuration and go to the rBuilder main page. For ongoing administration, log in as an administrator and use the Site administration area as described in rBuilder/Administration Guide:Site Administration.

rAPA Configuration Wizard

After site configuration for rBuilder, step through rBuilder's rPath Appliance Platform Agent (rAPA) configuration wizard. rAPA is used to perform common appliance administration tasks, such as updates and backups, that go beyond administration of the rBuilder software.

Use the following steps to set up rAPA as used to maintain the rBuilder appliance:

  1. Log in to rBuilder as the initial administrator created during site configuration.
  2. Click Site administration in the user panel.
  3. Click Enter rPath Appliance Agent at the bottom of the Administration Menu panel. Verify a new browser window is launched. It is typical to receive warning messages that the certificate being used was not created by a recognized Certificate Authority, but no action is required regarding these warnings prior to initial rAPA configuration.
  4. When the sign in dialog is displayed, type your user name and password and click Sign In.
  5. Use the rAPA default credentials for login: username of admin and password of password.
  6. Step through the configuration wizard as prompted, including changing admin's password for rAPA, configuring email notifications of appliance events, uploading an entitlement for rBuilder provided by rPath, and selecting an initial backup configuration. See rBuilder/Administration Guide:Appliance Administration as a reference for these rAPA tasks.

Add the rPath Appliance Platform

Before regular rBuilder users add any appliance projects in rBuilder, rBuilder administrators should add the rPath Appliance Platform and any other externally-managed projects provided by rPath or other rBuilder distribution points. The rPath Appliance Platform project provides the Linux Service needed for appliance developers to base appliance products on the rPath Appliance Platform.

Log in as the new administrator user and click the Site administration link. Then, click Add External Project. On first access of the form, the fields are pre-populated with the appropriate values for adding the Linux Service:

  • Project Name: rap
  • Project Title: rPath Appliance Platform - Linux Service
  • Project Label: rap.rpath.com@rpath:linux-1
  • Repository URL: Leave this field blank
  • Authentication: Select to Use an entitlement and provide the entitlement class and key provided by your rPath representative.
  • Mirror Settings: If you have preload disks, select Mirror this repository with a pre-load disk drive and update via network. If you are mirroring across a network connection, select Mirror this repository over a network connection only..

After adding the rap project, rBuilder redirects to the project homepage. If you are pre-loading a mirror for the project, click the Load mirror link on that page and follow the interface steps to pre-load the mirror.

To add other externally-managed projects, or to manage how those projects are tied in with rBuilder, return to the Add External Project task in the Site administration and use the rBuilder/Administration Guide:Site Administration#Externally-Managed Projects page as a reference.

Create a Test Project

Create a project on a newly installed and configured rBuilder to test the completed setup. Create the project as described in rBuilder:Create a Project, and create one or more developers for that project. Then, have those developers test packaging software for the project's repository. Interactions between the appliance development environment and rBuilder should be prompt and error-free.


Site administration tasks are specific to the rBuilder site and include configuring externally-managed projects, configuring outbound mirroring to Update Service appliances, and managing administrative users and maintenance mode. For rBuilder appliance administration, such as performing updates and backups and managing the underlying system processes, see rBuilder/Administration Guide:Appliance Administration.

Site administration is performed in a web interface accessible by rBuilder's site administrators. Site administrators should log in to the main rBuilder interface, and then click Site administration from the user panel. The following sections describe the site administration tasks as provided in this interface.

Create and Manage Users

Use the form on this page to create rBuilder users, especially when rBuilder restricts unregistered users from registering themselves. To assign those users to particular roles on particular projects, use the rBuilder interface as described in rBuilder:Add and Remove Members.

To edit or delete users, or to manage site administrators, click users in the search area at the top of the rBuilder interface. Browse the alphabetical list of users to find a particular user, or use the search tool to help narrow down the choices. Click the User Name value for the user you wish to modify, and use the drop-down list of actions under Administrative Options to take one of the following actions. Click Go after the selection is made to complete the action:

  • Reset Password -- reset the user's password, and email the user his or her new password
  • Cancel Account -- close the user's account so that the user no longer has access to rBuilder
  • Grant Administrative Privileges/Revoke Administrative Privileges -- grant or revoke rBuilder site administration privileges; note this does not include appliance administration with rAPA, which has a different user registration

Externally-Managed Projects

   This documentation needs to be updated. It is no longer recommended to use mirror mode, unless the rBA is disconnected from the internet.

Instead, externally-managed products should be set to "Cache contents of this repository locally as needed." Contrary to the note on the site administration page, a mirror preload disk is *NOT* required for this.

Add externally-managed projects to rBuilder through the Externally-Managed Projects task in site administration. Externally-managed projects will appear in rBuilder just as native projects do, but the external project repository is not stored locally.

Add rPath Appliance Platform from rPath as the first externally-managed project. This should have been done as part of initial configuration as described in the Configure page. Reference that page for the key information used to set up rap as an externally-managed project, including supplying the entitlement required from rPath.

Click Externally-Managed Projects in the site administration interface to add and manage external projects. When adding a new project, click Add a New External Project, complete the form, and click Add. Use the following as a guide when completing the form for the externally-managed project:

  • Project Name and Project Title -- Type the project name and title as you would when creating a project locally. rPath recommends that you use the same project name and title used by the external project.
  • Project Label -- Type a project label used by that project. Note that local rBuilder users will have access to more of the project than just this particular label.
  • Repository URL -- Type the repository URL for the external project, or leave this field blank to have rBuilder use the standard URL format derived from the project's label (such as http://conary.example.com/conary/ for the label conary.example.com@rpl:1).
  • Authentication -- If the external project repository requires authentication, select the appropriate authentication method to use. If the external project is public, you may not need to provide credentials. If the external project is private, and you are a developer or project owner on the remote project repository, type the username and password for that remote repository. If you have been provided an entitlement for access to the external project, type or paste the entitlement key.
  • Mirror Settings -- A local mirror of the external project can provide faster access to the repository contents for both developers and appliance consumers. This requires regular network updates to the mirror to ensure it is up-to-date. Select whether to mirror the entire repository over the network or to start with a set of mirror pre-load discs followed by a network update. If you wish to mirror any labels other than the one provided in the Project Label field, type each of those in the text box provided, separated by spaces. Note that local mirrors are scheduled to synchronize once each hour by default. To change this schedule, or to manually launch synchronization, use the Schedule Inbound Mirroring feature as part of appliance administration with rAPA.
  • Backup Settings -- By default, rBuilder will not include externally-managed projects in its backups. Check this box to include this particular external project among those backups, and be aware of the impact on backup size when adding this project.

Configure Outbound Mirroring

The rPath Appliance Platform Update Service is used to mirror projects in rBuilder to an Update Service appliance (rUS). This provides internally developed software to an external resource from which deployed appliances can obtain updates. Outbound mirroring is a means to configure which rBuilder projects mirror to which Update Service appliances.

Click Configure Outbound Mirroring in the site administration interface to add a project to mirror or to manage existing outbound mirrors. The list on the Outbound Mirrored Projects page displays the name of each rBuilder project, the fully qualified domain name (FQDN) of the target repository on the rUS, and the Conary labels within the project which are mirrored to that rUS. The mirrors are synchronized in the order shown.

Add and Modify Outbound Mirrored Projects

Adding a new outbound mirror is a two-step process: selecting what software to mirror, and selecting the target to which the software is mirrored. First, click Add an Outbound Mirror, complete the form, and click Save to save the new configuration. Use the following as a guide when completing the form:

  • Select the native rBuilder project to mirror from the Project to mirror drop-down list.
  • Select to Mirror all labels or to Mirror only selected labels. Select multiple labels by holding the shift or control key and clicking the desired labels in the list displayed.
  • Select to Mirror contents from selected labels only or to Mirror selected groups and all referenced packages. Select multiple groups by holding the shift or control key and clicking the desired groups in the list displayed.
  • If applicable, check the box to Include source components when mirroring.

When the new outbound mirror is listed, click Add target for that mirror in the list, complete the form, and click Add to add the new target. Use the following as a guide when completing the form:

  • In the Target Update Service text box, type the fully qualified domain name (FQDN) of the target repository on the Update Service appliance.
  • In the Update Service Username and Update Service Password text boxes, type the user credentials needed for the Update Service appliance. This user should have the admin or mirror role in rPath Appliance Platform Agent (rAPA) on the Update Service appliance (see rPath Appliance Platform/Update Service:User Roles for more information about configuring this on the rUS). See the rBuilder 4.0.0 release notes about a known issue when using the mirror role alone for configuring outbound mirroring.

Use the main Configure Outbound Mirroring task page to delete targets, remove projects, and change the order of projects in the list.

Adjust the Mirroring Order and Schedule

Because the mirrors are synchronized in the order shown, the order in which the mirrors are listed is important when one repository's contents depends on another. For example, if you are mirroring rap.rpath.com@rpath:linux-1, this should be listed before other repositories that may depend on it, such as appliances built on the rPath Appliance Platform. Use the up-arrow and down-arrow buttons in the Order column to change the order for outbound mirroring actions.

Mirrors will synchronize between the rBuilder and rUS as configured in the Schedule Outbound Mirroring task in rBuilder appliance administration. Use this task to enable and disable scheduled synchronization and to manually launch a synchronization.

   The Update Service appliance must be configured to receive the mirror updates from the rBuilder. rBuilder will display an error if it cannot connect as configured. See instructions for configuring repository servers in the Update Service appliance.

Manage Maintenance Mode

Use maintenance mode for rBuilder to suspend normal operation and perform maintenance that is not possible when rBuilder is in use. Click Manage Maintenance Mode in the site administration interface to toggle maintenance mode. The task displays the current operating condition and provides a button to toggle to its alternate position. To place the rBuilder in maintenance mode, click Invoke Maintenance Mode. To exit maintenance mode, click Restore Normal Operation.

Hide and Delete Projects

Use rBuilder's Hide Project to limit visibility of certain projects. Hide a project from the project's main page rather than the site administration interface. In Administrative Options on the project's main page, select Hide Project, and then click Go. The project is then hidden to all non-administrative users who are not members of that project.

Delete a project when other means of administration cannot resolve issues, especially with regards to backup and restore operations. A project requires command line access, which is rarely used when performing rBuilder administration. At the command line, run the following command, replacing <projectname with the short name of the project used in the project's URL: 

/usr/share/rbuilder/scripts/deleteproject <projectname>
   Deleting a project will permanently and irreversibly erase all repository contents. If other projects contain shadows of packages from the deleted project, or packages on the deleted project have been cooked into groups, those packages may become unusable. Ensure that no references to the project exist before proceeding with deletion.

Launch rAPA

The rPath Appliance Platform Agent (rAPA) is used to perform appliance administration tasks, such as performing updates and backups. To perform such tasks, click Enter rPath Appliance Agent to launch the rAPA web interface in a separate browser window, and log in with the credentials of a rAPA user on rBuilder. See rAPA's inline help as well as rBuilder/Administration Guide:Appliance Administration for reference when using rAPA.


Appliance Administration

Appliance administration tasks for rBuilder are tasks that a typical system administrator would perform on a regular basis to maintain or troubleshoot the rBuilder appliance. These tasks include scheduling updates, performing backups, managing system processes, viewing logs, downloading system information, and configuring networking and web proxies. For rBuilder site administration, such adding externally-managed projects and configuring outbound mirrors, see rBuilder/Administration Guide:Site Administration.

Appliance administration is performed in a separate rPath Appliance Platform Agent (rAPA) web interface, included in rBuilder and customized to manage the rBuilder appliance. There are two ways to access the rAPA interface:

  • Appliance administrators with site administration access can click Enter rPath Appliance Agent from the site administration interface.
  • All appliance administrators can bypass this step, though, and go directly to https://<rbuilder_fqdn>:8003 where <rbuilder_fqdn> is the fully-qualified domain name of the rBuilder.

Each appliance administrator should use his or her rAPA credentials to log in to rAPA, noting this is separate from the user's rBuilder credentials. The following sections describe each appliance administration task as provided in rBuilder's rAPA interface.

Appliance Logs

Use the Appliance Logs task to view portions of log files on the appliance and to download an entire selected log. Use these logs to monitor appliance health, troubleshoot errors, and provide information to rPath Support. Use the drop-down list to select a log to view, and click Download to download that entire log. Click Refresh at any point to refresh the output to show the most recent information.

Back Up and Restore

Use the Backup and Restore task to specify a particular backup location, to configure a backup schedule, to perform an on-demand backup, and to restore from a backup. Before any backups can be performed, either on-demand or scheduled, rAPA requires initial backup settings. The Backups tab is inaccessible until these settings are saved in the Backup Configuration tab. Use the following sections as a guide when configuring backups and when performing backup and restore operations.

Image:Bulbgraph.png   Critical rBuilder data is in /srv/rbuilder on the rBuilder's filesystem. This critical data (minus caches and temporary files) is included in rBuilder appliance backups. As a result, administrators should be able to recover an rBuilder to full functionality after a failure, except for any changes since the most recent backup.

Configure Backup Settings

Click Yes for Enable Backups to enable backup operations, with or without a schedule. To enable automatic backups on a given schedule, click Yes for Enable Backup Schedule, and use the interface to select the schedule freqency. The remaining configuration for Backup Options should be completed as follows:

  1. In the Number of Backups text box, type the whole number of backups that should be stored at the location specified. Note that the minimum number of backups that the system maintains by default is 2, even if the number is set less. If this number is ever reduced, the number of existing backups does not change until the next backup is performed.
  2. Set up the backup location by selecting the appropriate Backup Type from the drop-down list. Use the following sections as a reference when determining which type to select and what to type in the text boxes.

Click Save to save the backup configuration.

Network File System Share (NFS)

Select this for backup locations accessible by the appliance as NFS shares. The Connection host is the DNS hostname or IP address of the system providing the NFS share, and the Connection path value is the full path of the NFS export and subdirectories where the backups should be stored. In the following example, the NFS export is /mnt/nfsshare, but the connection path indicates to save all backups in the backups subdirectory in that export:

  • Connection Host: sharehost.example.com
  • Connection Path: /mnt/nfsshare/backups
Windows(R) Filesystem Share (CIFS or SMB)

Select this for backup locations accessible as Common Internet File System (CIFS), Server Message Block (SMB), or Samba shares. The title indicates that this is the type referred to when people say "Windows shares" in reference to file systems on Microsoft(R) products. The Connection host is the DNS hostname or IP address of the system providing the filesystem share, and the Connection path is the full path of the share and subdirectories where the backups should be stored. User credentials must be configured if they are required for access to the share, but they can be left blank otherwise. In the following example, the CIFS share is WinShare with a subdirectory of backups, and the credentials are provided for backupuser.

  • Connection Host: sharehost.example.com
  • Connection Path: /WinShare/backups
  • Connection User Name: backupuser
  • Connection Password: ***********

Note that the direction of the slashes in the path are forward ("/") in the style of DNS rather than backward ("\") in the style of Windows file paths.

Mounted Filesystem (Label)

Select this for backup locations that are mounted to the local filesystem on the appliance. The Disk label is the "LABEL" value associated with the mounted filesystem, and the Connection path is the directory path relative to the mountpoint where the backups should be stored. In the following example, SAN_FS_LABEL is the disk label that refers to the mountpoint, and backups is a directory in that mountpoint:

  • Disk Label: SAN_FS_LABEL
  • Connection Path: /backups

On-demand Backups

Click Back up Now on the Backups tab to perform an on-demand backup. These manual backups do not interrupt the normal backup schedule.

Restore from a Backup

When the need arises to restore rBuilder from a particular backup, choose that backup from the list displayed on the Backups tab. Select the backup file from which to restore from one of the following options:

  • To restore from a backup listed in the interface, click the corresponding button in the Restore column for the desired backup.
  • To restore from a backup file on a different resource, click Scan Now to scan mounted filesystems, and click Restore for the backup file that is found.

Click Restore in the dialog box to verify the restore, or click Cancel to cancel the action. Note the warning dialog that advises the appliance will be rebooted when the restoration process completes. When the restore is complete, click OK to refresh the page.

Restoring Non-Mirrored Externally-managed Projects

Externally-managed projects that are not mirrored have direct access to the remote repository rather than a local mirror of that repository. As a result, such projects require no additional restore steps and can be used immediately after restoration.

Restoring Mirrored Externally-managed Projects

As described in other sections, because local mirrors of externally-managed projects have the potential to be extremely large and are redundant copies of an upstream repository, they are not included in rBuilder backups by default. During a restore, mirrored externally-managed projects are converted to non-mirrored projects, allowing the project to directly access the remote repository immediately instead of rebuilding the mirror first. Change the externally-managed project back to its mirrored configuration at any point after the restoration by changing the Mirror Settings value for the project in the Externally-Managed Projects task as part of site administration.

Planning and Troubleshooting

Use the following guidelines when planning, performing, and troubleshooting backups on rBuilder:

  • Before performing backups and restores, put the rBuilder in Maintenance Mode as described in rBuilder/Administration_Guide:Site_Administration#Manage_Maintenance_Mode, and be sure to switch out of Maintenance Mode when a backup or restore is complete.
  • Ensure the backup destination and the backup file within it are world-readable.
  • Use the interface to view the details of a given backup, including start and finish times, file size, and backup file location.
  • Perform a test backup of rBuilder when it is newly installed. Then, install another instance of the rBuilder and test restoring from the backup, imitating a complete restore in case of a catastrophic failure. Verify the backup and restore operations are successful.
  • After a successful test, compare the names of the backup file created and the backup file from which you are restoring. Verify the names are the same except for the time stamp embedded in the name.
  • When necessary, check rAPA logs in Appliance Logs to monitor and troubleshoot the backup and restore operations.

Collection Tool

Use the Collection Tool task to run a collection operation which creates a compressed archive of important rBuilder appliance information. Appliance administrators can download that file to view the information, and rPath Support may request a download of this information from rBuilder when troubleshooting rBuilder appliance issues.

Configuration

Use the tasks in the <guilabel>Configuration</guilabel> submenu to configure certain aspects of the appliance. Use the guide text and help as a reference for each task. The following lists each task and a basic description of how to use it:

  • Configure Conary -- Configure the Conary install label path which determines the location that rBuilder searches for its own appliance updates.
  • Configure Email -- Configure an SMTP relay server and "From" address used when the rBuilder appliance sends email notifications about system events.
  • Configure Networking -- Configure network settings for the rBuilder appliance, including verifying information that is obtained from DHCP.
  • Configure Notification -- Configure the email addresses that should receive notifications about system events.
  • Configure Proxy -- Configure HTTP and HTTPS proxy servers used for Internet interactions.
  • Manage Entitlements -- View and upload an entitlement for rBuilder as provided by rPath, required to obtain regular updates to the rBuilder appliance.
  • Root Password -- Configure the password for the top administrative user (root) on the underlying Linux system.
  • Time Zone and Time -- Configure the time zone in which rBuilder resides as well as the system time or time servers from which time is maintained.
  • Upload SSL Certificate -- Upload an SSL certificate that should be used by the rBuilder appliance during secure network interactions.

Disk Usage

Use the Disk Usage task to view the current used and available space on all mounted filesystems.

Job Control Console

Use the Job Control Console to view information on running and finished "jobs," or task-specific processes running on rBuilder. This includes image building processes. rBuilder uses a master control program (MCP) and a system of job masters and job slaves to handle jobs.

The Jobs tab shows information about the last five jobs that were started, including their status as also reported in the product pages during image creation.

The Nodes tab shows the detail of how jobs are being handled. This tab provides an option to change the maximum number of job slaves that can be running at one time. Change this number as follows to manage system resources:

  • Note that the amount of RAM used for processing jobs is the same no matter how many jobs are running.
  • Increase the number to handle more jobs at one time, but note that the hard disk performance will decrease with more simultaneous jobs.
  • Decrease the number to improve hard disk performance, but note that more jobs will be queued to wait for those available slots.
  • Set the limit to 0 when performing updates and backups on the appliance, putting jobs on hold until slots are allocated again.

Each tab will check every few seconds to report the most recent information.

Pre-load Mirrored Repositories

Mirror pre-loading is a feature provided to rPath customers to add externally-managed projects from rPath (such as the rPath Appliance Platform) with an offline portable media resource. Because the mirrors for such projects are large, this feature is typically offered to customers as a means to quickly establish the mirror or to prevent issues mirroring over an unreliable network connection. This process is coordinated with an rPath representative only who will use this task as part of that process. (See rBuilder/Administration Guide:Site Administration#Externally-Managed Projects for the corresponding site administration feature.)

Schedule Inbound Mirroring

rBuilder maintains a mirror of each project configured as an externally-managed project. These mirrors are updated between the hour selected and the following hour, with the precise time shown in a message dialog when the schedule is saved. Use the Schedule Inbound Mirroring task manage the synchronization schedule and to request an on-demand synchronization.

Use the Enable and Disable radio buttons to enable or disable the synchronization schedule. When the schedule is enabled, use the interface options to select the frequency of the synchronization. Click Save to save these settings.

Click Mirror Now to launch an on-demand mirror synchronization whether or not the mirroring schedule is enabled.

Schedule Outbound Mirroring

rBuilder mirrors particular labels to one or more rPath Appliance Platform Update Service appliances as configured in the site administration task Configure Outbound Mirroring. Use the Schedule Outbound Mirroring task to manage the synchronization schedule with the Update Service appliances.

Use the Enable and Disable radio buttons to enable or disable the synchronization schedule. When the schedule is enabled, use the interface options to select the frequency of the synchronization. Click Save to save these settings.

Click Mirror Now to launch an on-demand mirror synchronization whether or not the mirroring schedule is enabled.

Image:Bulbgraph.png   Site administrators should use Configure Outbound Mirroring to control the order in which this synchronization occurs as described in Site Administration.

Schedule Reboot

Use the Schedule Reboot task to reboot or shut down the rBuilder appliance. Click Reboot Now for an immediate reboot, and click Shutdown Now for an immediate shutdown. Click Schedule Reboot and use the calendar tool to schedule a single reboot at some time in the future. Note that only one reboot can be scheduled at a time, and the rAPA interface will not be available during reboots or following a shutdown.

System Updates

Use the System Updates task to check for available rBuilder updates, schedule regular checks for updates, and to perform on-demand updates. Note that an available update represents all the changes necessary to bring the rBuilder appliance from its current version to the latest available version, eliminating the need to run multiple update operations to bring the appliance up-to-date.

Image:Bulbgraph.png   See rBuilder/Administration Guide:Version-specific Updates for some special considerations when updating between particular rBuilder versions.

On-demand Checks and Updates

Click Check Now in the System Updates tab to launch a new check for updates. Click OK when the check is complete. If an update is available, rAPA will download it and indicate that the update is available. Use the down arrow next to the update listing to expand the list of items that would be affected on the local rBuilder if the update is applied. Click Apply Now to apply the update immediately, or use the Schedule Update option to schedule that update for some point in the future.

Image:Bulbgraph.png   If rBuilder is configured to check for updates on a regular schedule, there may already be an available update. Click Check Now at any time to replace the available update with a more recent update (if one is available).

Scheduled Checks and Updates

Use the Settings tab to schedule regular checks for updates and to select whether rBuilder should apply an update immediately when one is available. If updates are checked regularly, but are not automatically applied, then each new available update will replace any previous downloaded update, and rBuilder will make the latest download available for administrators to apply when ready. When selecting to apply updates automatically after downloading them, consider the impact on the live rBuilder and the need to monitor the appliance health on a regular schedule corresponding to those updates.

Image:Bulbgraph.png   See the View and Apply Rollbacks for information about returning the appliance to a previous state prior to one or more recent updates.

User Management

Use the User Management task to change the current user's password and to manage other users who have access to the rAPA interface for rBuilder. Though rAPA offers appliance developers with options to create multiple roles for rAPA users on appliance products, the rAPA developed for rBuilder provides a single admin role that provides a user with permission to perform all tasks within its rAPA interface. The default admin user group provides this admin role and includes the default admin user. Appliance administrators can create any number of users to add to this admin group.

View and Apply Rollbacks

Use the View and Apply Rollbacks task to roll back one or more appliance updates as performed in the System Updates task. A rollback is a prompt to reverse an update to the appliance software. When each update is made, a corresponding rollback is created. The underlying system places the rollback on top of a stack of previous rollbacks. To roll back the appliance software to a previous state, select how many updates must be reversed, and apply their corresponding rollbacks, starting from the top of the stack.

The rollbacks displayed in View and Apply Rollbacks are those corresponding to the most recent updates, with the highest number being the most recent. Click the corresponding arrow button for a rollback to see what software packages are affected, and click a package name in that display to see how that package will change if the rollback is applied.

Click Do Rollback in the corresponding roll back information to apply the rollback, returning rBuilder to its state prior to that corresponding appliance update. Rollbacks must be applied in chronological order starting with the most recent, as if removing each rollback from the top of the stack when applying that rollback.

rBuilder Migration

This feature is provided especially for rBuilder updates or migrations that require assistance from an rPath representative and it not intended for regular system administration tasks.

Command Line Access

While the majority of rBuilder maintenance tasks can be performed in the rAPA web interface, administrators may have a rare need to access the command line of the rBuilder system. Remote access to the rBuilder command line is possible using a secure shell (ssh) protocol client. Access the rBuilder command line using an ssh command resembling the following, replacing <host> with the actual hostname or IP address assigned to the rBuilder:
$> ssh root@<host>
rBuilder includes the vim text editor. Under typical circumstances, you should not need to edit files directly because all appliance administration is done through the rAPA web interface. If the need arises to use vim, launch the editor with the command vim followed by path and file to edit.


Important Files and Directories

The following sections describe some of the important underlying files and directories in rBuilder. Use the information as a reference when troubleshooting as part of site administration and appliance administration, but do not modify these files in ways that violate a support agreement with rPath.

   Much of this information can be downloaded and viewed using the Appliance Logs or Collection Tool. Rarely should any appliance administrator require command line access to obtain this information.

rBuilder Directories

rBuilder-specific data is maintained within particular directories under /srv/rbuilder on the rBuilder appliance. The directory paths referenced below include a <version> placeholder string to represent an actual rBuilder version string, such as 1.6.3.

Directory Description
/srv/rbuilder/changesets Bind mount point for the directory /srv/rbuilder/jobserver/<version>/srv/rbuilder/changesets, contains the changeset cache for creating installable ISO images
/srv/rbuilder/config Directory for rBuilder's Conary configuration
/srv/rbuilder/rbuilder.conf -- The primary configuration file for the rBuilder, containing settings that enable or disable particular behaviors, specify directory paths, and set unique values, such as specifying the organization name and website
/srv/rbuilder/data Directory for the rBuilder database
/srv/rbuilder/entitlements Directory for entitlements granting access to specific products required by the rBuilder
/srv/rbuilder/finished-images BIND mount point for the directory /srv/rbuilder/jobserver/<version>/srv/rbuilder/finished-images; used to store all finished release images
/srv/rbuilder/jobserver Directory for rBuilder's functionality for processing jobs, facilitating such tasks as cooking groups and generating images
/srv/rbuilder/logs Directory for rBuilder log data
/srv/rbuilder/repos Directory for repository data for all projects managed by this rBuilder
/srv/rbuilder/run Directory for run-time data, such as lock files
/srv/rbuilder/tmp Temporary data directory

Web Server Log Files

The standard web server logs contain useful information about access and error conditions for the server covering both HTTP and HTTPS access. The following table describes these logs and notes their locations:

Log File Description
HTTP Logs
/var/log/httpd/access.log Contains records of all client access to the web interface server in the following format: client address, client identity, user id, date and time, client request, server status code, size of object returned, referer HTTP request header, and user-agent HTTP request header. Note that log fields contain hyphens ('-') where data is not available.
/var/log/httpd/error.log Contains records of all errors resulting from access to the web interface server in the following format: date and time, the log message level, client address, and the error message.
HTTPS Logs
/var/log/httpd/ssl_access.log Contains records of all client access to the web interface server in the following format: client address, client identity, user id, date and time, client request, server status code, and size of object returned.
/var/log/httpd/ssl_error.log Contains records of all errors resulting from access to the web interface server in the following format: date and time, the log message level, client address, and the error message.
/var/log/httpd/ssl_request.log Contains records of all requests to the web interface server in the following format: date and time, client address, the Secure Sockets Layer (SSL) protocol, the SSL cipher, the requested location, and the number of bytes in the served document.

rPath Appliance Platform Agent Log Files

The rPath Appliance Platform Agent (rAPA) has a set of logs on each appliance on which it runs, including rBuilder. The following table describes these logs and notes their locations:

Log File Description
/var/log/raa/raa-service.log This log provides information about operation of the rAPA service, including startup, shutdown, and information on tasks and threads.
/var/log/raa/web This log contains information pertaining to the web rAPA interface.
/var/log/web-access This log file records access to the rAPA web interface, including date-time, client address, URL, result code, returned data size, and additional messages.

System Log Files

Because rBuilder uses a Linux operating system, the rBuilder appliance includes many standard Linux system logs in addition to its software-specific logs. Such logs can be useful for diagnosing problems with the hardware. The following table describes some more frequently referenced logs and notes their locations:

Log File Description
/var/log/dmesg The kernel ring buffer log displays messages pertaining to hardware devices during boot time.
/var/log/messages The messages system log contains notifications from system entities such as the cron(1) daemon and the kernel.
/var/log/secure Security messages, such as those from sshd(8) and sudo(8) are found in this log.

Scheduled Events

The file /etc/cron.d/apache is used to instruct the cron utility to schedule execution of several commands related to rBuilder package indexes and mirroring. These commands are executed as the apache user who has rights to use the web server. The following table lists the commands that are run regularly and describes their purpose and frequency:

Command Purpose Frequency
/usr/share/rbuilder/scripts/update-package-index Updates the local rBA package index Every 12 minutes
/usr/share/rbuilder/scripts/update-package-index-external Updates the package index on externally-managed projects, such as rPath Linux Every 30 minutes
/usr/share/rbuilder/scripts/mirror-inbound Updates locally mirrored projects Hourly
/usr/share/rbuilder/scripts/mirror-outbound Updates externally mirrored projects hourly

Temporary Files

The tmpwatch utility in Linux is used to remove certain files after a specific period of time. Files removed by tmpwatch at regular intervals include the following:

  • /etc/cron.daily/rbuilder-jobserver-x.x.x.tmpwatch which tracks:
    • All temporary job server images are removed after two days after they are created
    • All debugging data generated by the job server is removed two weeks after it is created
  • /etc/cron.daily/rbuilder.tmpwatch which tracks:
    • Cached changeset files are removed two weeks after they are created
    • Temporary rBuilder images are removed two weeks after they are created


Repository Maps for Developers

rBuilder users can be in development teams with several projects covering multiple repositories. One deployment consideration is managing the mappings between the hostname part of a project's label and that project's networked repository, called repository maps.

Part of Conary configuration for each appliance development environment is a repositoryMap directive to match the project label to the project repository. In the configuration, each context has its own repositoryMap value, and appliance developers configure one or more contexts for each rBuilder project on which they develop. As projects are created, more repositoryMap lines must be added to this file, increasing the possibility of incorrect or outdated mappings.

To simplify the management of these repository maps, rBuilder automatically maintains a list of repositoryMap lines. This includes one line for each internal project and one line for each external project with inbound mirror attached. rBuilder serves this list at http://<hostname>/conaryrc where <hostname> is the host name of the rBuilder.

Appliance developers can add the following line to their configuration files to prompt Conary to update the repositoryMap lines to match an rBuilder: 

includeConfigFile   http://<hostname>/conaryrc

Browse to the URL in a web browser to see the content that will be inserted into the Conary configuration. When new projects are created, the information from the URL is automatically updated.

Image:Bulbgraph.png   rPath recommends that appliance developers use includeConfigFile to reduce the maintenance associated with the repository map entries. However, includeConfigFile should not be used in appliance products because of potential proxy conflicts when performing Conary transactions.

For more information on enabling the includeConfigFile directive and using it to manage repository maps, see the Configure Repository Maps FAQ page at wiki.rpath.com.


Version-specific Updates

When performing system updates in rBuilder, be sure to review the rBuilder Release Notes, and take note of the following version-specific update considerations.

Verify the Version and Update

Verify the current version of rBuilder in the footer of rBuilders rPath Appliance Platform Agent (rAPA) interface when performing appliance administration on rBuilder.

Update to 4.1.0

Starting with version 4.1.0, the conary repositories for products in rBuilder should use PostgreSQL databases instead of SQLite databases. PostgreSQL provides better performance, improved concurrency, and higher reliability. After updating rBuilder to 4.1.0, schedule a maintenance window as appropriate prior to migrating to PostgreSQL.

rPath strongly recommends you convert to PostreSQL using the provided link in the menu; until your rBuilder appliance has done this, you are in an unsupported configuration. See the Update Path to 4.1.0 section of this guide for detailed instructions and precautions about this update and migration.

Migrations to rBuilder 4.1.0 require that your current rBuilder version is of 4.0.0 or higher. If you are currently using rBuilder 3.1.4 or earlier, you must first update to 4.0.x before moving to 4.1.0. Because of major changes in the partition structure and job handling, updating to 4.1.x from pre-4.0.x releases requires a backup, new installation, and restore process as described here. Additionally, rBuilder 4.0.0 runs on 64-bit processor architectures only. Because of these changes, rPath is assisting each customer with the 3.x to 4.0.x update process.

Customers with rBuilder 3.1.4 or earlier should contact an rPath representative to schedule an update to rBuilder 4.0.1.

Update to 4.x

rBuilder 4.0.0 was released for new installations only, and rBuilder 4.0.1 and forward have an update path from pre-4.x rBuilder installations. Because of major changes in the partition structure and job handling, updating to 4.x from pre-4.x versions requires a backup, new installation, and restore process with scheduled assistance and removable storage from rPath. See the Update Path to 4.x section of this guide for detailed instructions and precautions about this update.

Update 3.1.3 Interim Release

The 3.1.3 Interim Release adds a new build type Update ISO. If updating from 3.1.2 or earlier, or if performing a new install of the 3.1.3 Interim Release, there is a known issue that affects this new feature. To resolve the issue and to be able to use this new build type, run the following two commands as root on the rBuilder system following the 3.1.3 Interim Release update: 

echo buildTypes UPDATE_ISO >> /srv/rbuilder/jobserver/3.1.3/srv/rbuilder/iso_gen.conf 
/sbin/service multi-jobserver restart

Updates from previous 3.1.3 releases to 3.1.3 Interim Release are not impacted in the same way; contact your rPath support representative for more information about the fix for this update.

Update 2.0.x to a New Version

Update to a new version of rBA using rAA:

  1. Sign in to rBA as an administrative user.
  2. Click Site administration in the user panel.
  3. Click Manage Maintenance Mode on the left panel and put rBA into maintenance mode.
  4. Click Enter rPath Appliance Agent in the Administration Menu panel. Verify a new browser window is launched with the rAA interface.
  5. In rAA, type user name admin and the rAA admin password and click Sign In. Note that the rAA admin user and password is distinct from your rBuilder administrative user.
  6. Click System Updates on the left panel.
  7. Click Check Now to start checking for available updates.
  8. Click Apply Updates to apply the updates shown.
  9. After updates are successful, start the job server and exit maintenance mode to resume rBA function.

Expect rBuilder to have service interruptions during the update.

Updating rBA from 1.6.3 to 2.0.0

   An rPath field engineer must perform rBA updates using the update script described below. Note also, that this script MUST be used to update your existing version 1.6.3 rBA. DO NOT attempt to update the rBA manually by using conary commands.

You can update an existing rBuilder Appliance from version 1.6.3 to version 2.0.0 by using a script that handles the migration of the rBA software and associated repository mirrors hosted by the rBA.

To execute this script, you must use command line access.

Verify the rBA version to be sure you are working with a version 1.6.3 rBA prior to executing the migrate script. If your version of rBA is earlier than 1.6.3, contact rPath for information on updating to rBA 1.6.3 and beyond.

After verifying your existing rBA version is 1.6.3, follow these steps to update your rBuilder Appliance to version 2.0.0:

  1. Execute the migration script.
  2. Update entitlements.

Execute the Migration Script

Execute the migrate-rba-1.6-to-2.0.sh script to initiate the update and migration: 

[root@localhost ~]# ./migrate-rba-1.6-to-2.0.sh

If your rBA has a full rPath Linux local mirror the migration process can require a considerable amount of time.

During the migration process, you may see error messages resembling the following. These messages are innocuous and may be ignored: 

Exception exceptions.AttributeError: <exceptions.AttributeError instance at 0xb7461b4c> in <bound method Connection.__del__ of <conary.sqlite3.main.Connection instance at 0xb745bf8c>> ignored

After the script completes successfully, rBA services are restarted.

Update Entitlements

The last step required for this update is to refresh the rBA's entitlements using the rPath Appliance Agent (rAA), the previous name of the rPath Appliance Platform Agent. Sign in to the rAA web interface, access the entitlement management function and update the entitlements according to this process:

  1. Sign in to the rBA as an administrative user.
  2. Click Site administration in the user panel.
  3. Click Enter rPath Appliance Agent in the Administration Menu panel. Verify a new browser window is launched. It is typical to receive warning messages that the certificate being used was not created by a recognized Certificate Authority, but no action is required regarding these warnings before configuring the rAA.
  4. Sign in to the rAA with your username and password. At this time, you will be presented with the rPath Appliance Agent Wizard. Click OK to continue.
  5. Click Done to complete the network configuration screen.
  6. Click Configuration and then Manage Entitlements.
  7. Click OK to refresh the entitlement.
  8. Sign out of the rAA interface and close the browser window.

Alert for 1.6.3 and Prior Versions

The crontab:runtime component was arbitrarily excluded in prior versions of rBA. This is not an issue after updating to 2.0.0. If you have version 1.6.3 or prior, use the rBA 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.


Application to Appliance: A Hands-on Guide

rPath provides Application to Appliance: A Hands-on Guide as an introduction to appliance development. The guide steps through rPath's recommended appliance development process using rBuilder and rMake. VMware virtural machine and installable ISO images are also provided with a pre-configured development environment. Use references throughout the guide to find rPath Wiki pages with extended information.

Visit the following link to download the guide:

http://wiki.rpath.com/wiki/Application_to_Appliance
Retrieved from "http://wiki.rpath.com/wiki/rPath_Technical_Guide:rBuilder_Appliance_Administration"