FAQ:Adding Software to a User-Extensible Appliance

From rPath Wiki

Answer: This guide demonstrates the process for adding packages to an appliance with an emphasis on the package group structure comprising the appliance. This information will be useful to those who are building or maintaining a user-extensible appliance.

Suppose you are working with a deployed appliance, or a community appliance and have a requirement for additional software that is not defined in the appliance's group. Furthermore, you do not have access to the appliance's repository to add the software to the appliance by editing the appropriate group recipe. The following will describe what constitutes a user-extensible appliance, and demonstrates adding packages to such an appliance.

What Makes an Appliance User-Extensible?

A user-extensible appliance can be made up of multiple groups and packages which define the appliance. Each of these packages are added to a group with the group recipe command, r.add. Packages can be added to a group recipe with an argument to r.add specifying that they are to be selected and installed as part of the appliance by default (byDefault=True), or that they can be optionally selected for installation by the appliance user (byDefault=False). See the r.add command API documentation for more information.

In addition to the manner in which packages are added, a user-extensible appliance must use Conary's updateall command to update packages by retrieving and installing the appropriate changesets. If the appliance uses the rPath Appliance Agent (rAA) to manage updates, the rAA configuration element updatetroves.migrate must be set to False in the rAA custom configuration file (/etc/raa/custom.cfg).

By configuring an appliance in this way, any packages that have been added to the appliance after it has been deployed (by the appliance's end-user, for example) will be automatically updated along with the appliance's defined set of packages.

You should be aware that in building an appliance in this manner, your appliance's users will have the ability to extensively modify the appliance's software stack, potentially causing adverse consequences to the appliance's operation.

If you need strict control over the packages which define your appliance, then you might wish to consider building a provider-managed appliance. As the name implies, packages on this type of appliance are managed by the appliance provider, and any packages added after deployment will be removed automatically when the appliance is updated.

Adding a Package

For an example of adding a package to a deployed appliance, suppose the appliances you administer occasionally via their command line interfaces do not provide your preferred text editor. You can add the editor's package to your appliance with the Conary package management tool.

Before proceeding with the command example below, log in to your appliance as the root user per your appliance's documentation.

In this example, we are adding the Vim editor from the rPath Linux project to our deployed appliance:

[root@localhost ~]#conary update vim-minimal=conary.rpath.com@rpl:1
    Install vim-minimal(:runtime)=6.3.90-2.5-1

Now, a minimal instance of the Vim text editor is installed and available for use on the appliance.

Updating With rAA

When updating the package on a user-extensible appliance, rAA will install the new package you have included with the appliance by updating the package directly.