Administrative REST interfaces
The Amlen Bridge provides the ability to create admin endpoints.
Using the administrative REST interfaces
There is an admin endpoint defined during the installation as a service or using Docker. This endpoint uses a self-signed certificate that is provided with the installation. You can modify this configured admin interface, and you can define additional admin interfaces with different security and interface bindings, but each one must listen to a separate port.
For example, you can have one that listens on localhost and another one on a private network. It is best practice to restrict the admin interface so that it is not exposed to the public internet. Always use secure connections, which requires you to provide a server certificate and key. It is best practice to restrict the interfaces that the admin endpoint listens on. You must also provide your own certificate.
You must have at least one defined user to use the REST APIs. All defined users are authorized to use all REST calls. You must use basic authentication and specify a user and a password.
You do not need to specify
all fields when an object is modified, you only need to specify those that are changed. This means
that you must also explicitly delete any complex object you wish to delete from configuration.
Complex objects are those represented as JSON objects. You can delete complex objects using a
DELETE REST method or by changing the global configuration with the value of the
object set to null.
All paths that are shown in the following tables come after the initial path /admin/.
For a description of the connection object, forwarder object, and endpoint object properties, see Configuring the Bridge.
The following table shows the paths
that can be used with the GET method:
| Path | Description |
|---|---|
| config | Return the complete dynamic config for this bridge instance. |
| config/connection/[match] | Return matching connection config. If match is missing or contains an asterisk, return all matching connections. Only the inner levels of the object are returned. |
| config/endpoint/{match} | Return matching endpoint config. If match is missing or contains an asterisk, return all matching endpoints. Only the inner levels of the object are returned. |
| config/forwarder/{match} | Return matching forwarder config. If match is missing or contains an asterisk, return all matching forwarders. Only the inner levels of the object are returned. |
| config/user/{match} | Return matching user config. If match is missing or contains an asterisk, return all matching users. Only the inner levels of the object are returned. |
| connection/password/{password} | Return the obfuscated connection password as text. |
| endpoint/{match? | Return the matching endpoint statistics. The match can be missing or can contain * wildcards |
| forwarder/{match} | Return the forwarder status and statistics. The {match} can be left out or can be a name including * wildcards. |
| info/{kind} | Show bridge execution information. If the {kind} is missing or “all”, a JSON object showing all info is returned. If kind is “version”, “container”, “hostname”, “servername”, “platform”, “processor”, or “buildlabel” the specific info value is returned as text. |
| password/{user}/{password} | Return a user object with the obfuscated password matching the specified user and password. This can be used to get an obfuscated password when manually modifying the config files. |
| set/{match} | Return a config object showing the value of selected properties. Both static and dynamic properties are returned. If the item to match does not include a wildcard, then the value is returned without any JSON wrappers. |
| time | Return the time as known to the server in ISO8601 format |
The following table show the paths that can be used with the POST method, and provide an associated description:
| Path | Description |
|---|---|
| accept/license/{usage} | Accept the license and specify the license type as: “Developers”, "Non-Production”, or
“Production”. If you do not accept the license, use accept/license/None. |
| config | Post a config from the outermost level of config. At this level complex objects are represented by a JSON object named by the object type which contains a set of named objects of that type. The objects are described in Configuring the Bridge. |
| keystore/{name} | Write a file into the key store. The contents must be a X.509 objects in PEM format. |
| quit/{rc} | Terminate the bridge process cleanly. The {rc} is the return code send to the operating system and is optional and default to 0. When running the installed bridge, using a value of 2 will cause the bridge not to be restarted. Using other rc values will cause the bridge to be restarted. This POST does not take any content. |
| set/{property}/{value} | Set the specified property to the value. The following properties may be set: LicensedUsage, LogLevel, ShutdownWait, TraceConnection, TraceLevel, TraceMessageData, and TraceSelected. The values of LicensedUsage, LogLevel, and TraceLevel are persisted, the others only affect this process. This POST does not take any content. |
| start | Start the bridge processing. This only has an effect if the bridge was set to not automatically start, or the delay has been set very large. This POST does not take any content. |
| truststore/{name} | Write a file into the trust store. The contents must be a X.509 objects in PEM format. |
The following table show the paths that can be used with the DELETE method, and provide an associated description:
| Path | Description |
|---|---|
| config/connection/{name} | Delete a single named connection |
| config/endpoint/{name} | Delete a single named endpoint |
| config/forwarder/{name} | Delete a single named forwarder |
| config/user/{name} | Delete a single named user |
| config/routingrule/{forwarder}/{name} | Delete a single routing rule from a forwarder |
| keystore/{name} | Delete a file from the key store |
| truststore/{name} | Delete a file from the trust store |
The installation comes with the default self-signed certificate. The certificate must be replaced with an installation-specific certificate, which can come from a Certificate Authority or it can be self-generated. To change the certificate, put the certificate and key into the /var/imabridge/keystore/ directory and update /var/imabridge/bridge.cfg to specify the new files. Update the fields Endpoint.admin.Certificate, and Endpoint.admin.Key with the names of the files, and Endpoint.admin.KeyPassword with the key password. Also, verify that Endpoint.admin.Secure is set to true. To increase security, you can limit the admin endpoint to only a single network interface. For example, to limit the admin interface to only localhost, set the field Endpoint.admin.interface to “localhost”.
To generate a self-signed certificate with a private key, you can run the following openssl commands:
openssl rand -base64 8 -out myserver.keypw openssl genrsa
-aes128 -passout file:myserver.keypw -out myserver_key.pem 2048 openssl req -new -x509 -days 3650
-key myserver_key.pem -passin file:myserver.keypw -subj "/CN=<common_name>/" -out
myserver_crt.pem The full set of subject name elements can be specified in the subj argument:
"/C=<country>/ST=<state>/L=<location>/O=<organization>/OU=<unit>/CN=<common_name>/"