rBuilder/Administration Guide:Appliance Administration

From rPath Wiki

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.

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.

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.

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.

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.

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.