Configuring Modules

The Modules section of the AMPS configuration file is used to load, configure and define any plug-in modules used for this installation of AMPS. AMPS supports a wide variety of plug-in modules, as described in the Extending AMPS Guide (available from support).

The following steps are required to use a plug-in module:

1. Load the module and declare the name of the module.

2. Define the AMPS object that the module contains, give the object a name and pass any required options.

3. Use the module in a specific context.

For many modules, such as Authentication and Entitlement modules, steps 2 and 3 are performed at the same time. However, they are handled separately when a module must have the same definition across multiple contexts (for example, a MessageType which may be used in a Transport, a SOW, a View, and replicated to other instances).

Described below are the features available for a Module. Expand each item for more details.

Name (required)

A plain text name for the module.

This will be used as a reference when the module is used elsewhere in the AMPS configuration, and is also the name that AMPS will use for logging messages related to the module.

Library (required)

The shared object file that contains the compiled module. This must contain a path to the file.

When using relative paths, those paths are evaluated relative to the current working directory of the AMPS process. For example, to load a file from the current working directory, you must specify the directory (./my_awesome_module.so).

AMPS automatically searches the lib directory of the AMPS distribution for shared objects. If you install the shared object in the lib directory of the AMPS distribution, you can simply provide the filename of the shared object without using a path.

Options

A list of supported features for the implemented library.

AMPS allows you to pass options to the module by specifying elements within the Options element. The exact options that the module requires, if any, are determined by the creator of the module.

The following section provides an example of an AMPS configuration using an authentication and entitlement plug-in module. In our example, a custom authentication module named libauthenticate_customer001.so has been written to manage the authentication portion of AMPS authentication. Similarly, a custom entitlements module has been written named libentitlement_customer001.so to manage the permissions and access of the authenticated user.

The first step is to define the global Modules section of the AMPS configuration, and then list the individual modules, as shown below:

<AMPSConfig>
    ...

    <Modules>
        <Module>
            <Name>authentication1</Name>
            <Library>libauthenticate_customer001.so</Library>
            <Options>
                <LogLevel>info</LogLevel>
                <Mode>debugging</Mode>
            </Options>
        </Module>
        <Module>
            <Name>entitlement1</Name>
            <Library>libentitlement_customer001.so</Library>
            <Options>
                <LogLevel>error</LogLevel>
                <Mode>prod</Mode>
            </Options>
        </Module>
    </Modules>

    ...
</AMPSConfig>

We now have an authentication module and an entitlements module that we can reference elsewhere in the AMPS configuration file to enable authentication and/or entitlements for supported features. For example, we can create one type of Authentication module for the instance as a whole, and then create instances of a different type of Authentication and Entitlement modules for each Transport, to ensure that our Transports are properly enabling authentication and entitlements.

As shown in this example, the Authentication and Entitlement modules configured for an individual Transport are used for that transport, and the instance level modules are used as a default for transports that do not specify any Authentication or Entitlement.

This is accomplished via an entry along the lines of the following:

<AMPSConfig>
    ...

    <!-- my_default_security would be loaded in the Modules
         section. -->

    <Authentication>
        <Module>my_default_security/Module>
    </Authentication>
    <Entitlement>
        <Module>my_default_security/Module>
    </Entitlement>

    ...

    <Transports>
        <Transport>
            <Name>fix-tcp-001</Name>

            ...

            <Authentication>
                <Module>authenticate_customer001</Module>
            </Authentication>
            <Entitlement>
                <Module>entitlement_customer001</Module>
            </Entitlement>
        </Transport>
        <Transport>
            <Name>fix-tcp-007</Name>

            ...

            <Authentication>
                <Module>authenticate_customer007</Module>
            </Authentication>
            <Entitlement>
                <Module>entitlement_customer007</Module>
            </Entitlement>
        </Transport>

        <Transport>
            <Name>json-tcp<Name>
            <!-- does not specify Authentication or entitlement, uses
                 instance-level modules -->

            ...

        </Transport>
    </Transports>

    ...
</AMPSConfig>

The above example shows how our fix-tcp-001 transport is secured with the authenticate_customer001 authentication module, and the entitlement_customer001 entitlement module, which would be defined in a global Modules section. Similarly, the fix-tcp-007 transport is secured with the authenticate_customer007 authentication module and the entitlement_customer007 entitlement module. Those modules would be defined in a global Modules section. In contrast, the json-tcp transport does not define modules, and instead uses the authentication and entitlement modules specified at the instance level.