FAQ:Changes in rAPA 3

From rPath Wiki

Because this transition may be a challenge for appliance developers working with rAPA, the following sections cover some key information to help in making that transition, including how CherryPy has been implemented to replace the need for TurboGears and LightTPD.

Configuration Changes

The configuration for rAPA in /etc/raa/prod.cfg has several changes that may impact any custom.cfg set up by appliance developers. See the following tables for configuration directives that have been added, removed, or renamed, and see the section that follows the tables to see how plugin access to the configuration values has changed.

Renamed Directives

Removed Directives

New Directives

Configuration Access Changes

The way the configuration values are accessed by rAPA plugins has also changed. In 2.2.x and prior, configuration values were accessed by plugins by calling turbogears.config or cherrypy.config. In 3.0.0 there is a wrapper method in raa.web called getConfigValue. When calling getConfigValue, pass a directive name, default value, and a path. Though the path is indicating a section within the configuration file, it typically represents the plugin directory and its subdirectories to which the configuration applies. The path is optional when using getConfigValue, and if it is not passed, the method uses the current requests path to look for a configuration value.

If a path is passed into getConfigValue, the method only looks in that section of the configuration and nowhere else. However, when a path is not passed with getConfigValue, the method traverses the path backward looking for a matching configuration section, and then it checks the global section of the configuration file. For example, suppose the current requests path is /top/sub/next: the getConfigValue method searches for the specified directive in a config section named /top/sub/next, then for /top/sub, then for /top, then for /, and then finally searches the global section of the config file. If a value is never found, the default value is returned, if it was set, or None is returned.

This new configuration access access provides the opportunity for developers to use different values for the same variable depending on the scope to which that value should apply. When setting directives in configuration files, consider using path-named sections as a way to override directive values from the global section or other parts of rAPA.

XML-RPC Facade Changes

The XML-RPC facade is now at the URL <hostname>/xmlrpc-request instead of <hostname>/xmlprc. The XML-RPC facade allows a user to use <hostname>/xmlrpc-request/<exposed method> to call an XML-RPC exposed method from the browser as if making the call using an actual XML-RPC client. One can use this to see the method as plan text with no styling or templating; for example, if an XML-RPC call would typically return a Python dictionary, one would see that Python dictionary in the web browser in plain text form.

Changes in Plugin Development

The primary change to the rAPA plugins in 3.0.0 are the name changes to the modules they import and reference. Also, rAPA provides wrapper methods in raa.web for all interactions with CherryPy so that a plugin does not have to import CherryPy. This is part of rAPA establishing a consistent API that plugins can use as a reference for plugin developers.

The following table shows the names of the modules as they existed in rAPA 2.2.x and before alongside the newer modules.

The next sections describe the key things to know about how plugin structure and development has changed.

Removal of TurboGears, Updates to CherryPy 3.x

rAPA uses CherryPy 3.x (specifically 3.0.3) for version 3.0.0, and it has removed TurboGears entirely.

If a custom plugin imports TurboGears for any reason, the import and any code using TurboGears features must be removed for the plugin to work in rAPA 3.0.0. Cherrypy 3.x offers similar functionality for some TurboGears features. Reference CherryPy documentation for more information:

• CherryPy homepage: cherrypy.org
• Extend CherryPy using its own plugin system, called tools

If a custom rAPA plugin already imports CherryPy for its functions, the interface to CherryPy may have changed as this is different than the version of CherryPy that TurboGears used (which was 2.2). Because of the extensive changes between CherryPy 2.2 and 3.x, reference the CherryPy documentation when updating plugin code to use the newer CherryPy: http://www.cherrypy.org/wiki/UpgradeTo30

Addition of JSON

In rAPA 3.0.0, POST requests are handled in JavaScript Object Notation (JSON) by default. POST requests are not handled by JSON when a template parameter is specified, or the allow_json parameter is set to False in the raa.web.expose decorator.

For example, the following methods would not be handled by JSON:

@raa.web.expose("template=raa.method")
def method(self):
    return {}

@raa.web.expose(allow_json=False)
def method2(self):
    return {}

Changes in PAM Configuration

rAPA 3.0.0 requires a different configuration when using PAM for external authentication.

The configuration value tools.identity_tool.provider_paths must include the path to the PAM identity provider class. The identity provides loading code imports all modules found under the paths specified by that configuration directive, and it looks for a class with an attribute name equal to the value of the configuration directive tools.identity_tool.provider. rAPA uses the value it finds as the identity provider.

The default configuration for rAPA uses the following values:

[global]
tools.identity_tool.provider = "raa_identity"
tools.identity_tool.provider_paths = ["raa/identity/builtin", "raa/identity/pam"]

This default configuration indicates that all the modules under raa/identity/builtin and raa/identity/pam will be imported until an identity provider class is found (such as class.name == "raa_identity").

To specify the PAM identity provider, use custom configuration to override these defaults:

[global]
tools.identity_tool.provider = "pam_identity"

Appliance developers can still create their own identity provider classes for authentication as referenced on rPath Appliance Platform Agent:External Authentication in the rPath Wiki. However, setuptools is no longer used, and developers must add the path to the identity provider class to the tools.identity_tool.provider_paths configuration and set tools.identity_tool.provider equal to the value of the name attribute in the class.

API Updates

rAPA 3.0.0 has the following API signature changes:

• Disk usage plugin: the plugin was removed, so diskusage.DiskUsage.index is no longer present
• User management plugin:
  • Arguments in usermanagement.UserInterface.changePassword have changed as follows:
    • BEFORE: pwd1, pwd2, pwd3
    • 3.0.0: oldpwd='', pwd1='', pwd2=''
  • Arguments in usermanagement.UserInterface.deleteUser have changed as follows:
    • BEFORE: id
    • 3.0.0: username
• Services plugin: services.Services.saveSchedule and services.Services.unscheduleService have been removed as their functionality has been removed

rAPA 3.0.0 has the following return value name and type changes, the names referring to the keys in the return Python dictionary:

rAPA 3.0.0 API includes the following method name change: the config method has been renamed to viewConfig. This is the method called to get a view of the current configuration data for the rAPA instance. In rAPA 3.0.0, change config to viewConfig when making this request in a URL, such as in the following:

https://localhost.localdomain:8003/viewConfig