5. 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.
The following steps are required to use a plug-in module:
- Load the module and declare the name of the module.
- Define the AMPS object that the module contains and give the object a name and pass any required options.
- 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. Steps 2 and 3
above are separate 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).
The available features of a Module
are listed in the following
Module Parameters table.
Element | Description |
---|---|
Name
|
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
|
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 (for example, AMPS automatically searches the |
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. |
Module Parameters
The following section
provides an example of an AMPS configuration using an authorization 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.
<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>
Sample global config of authentication and entitlements module
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. 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 similar to Listing Security Transports.
<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>
Security transports example
Listing Security Transport shows how our
fix-tcp-001
transport is secured with the authenticate_customer001
authentication
module, and the entitlement_customer001
entitlement module, which is defined in a
global Modules
section similar to the one listed in
Sample global config of authentication and entitlements module.
Similarly, the fix-tcp-007
transport is secured
with the authenticate_customer007
authentication module and the
entitlement_customer007
entitlement module. In contrast, the
json-tcp
transport does not define modules, and instead uses the
authentication and entitlement modules specified at the instance level.