A SwiftMQ Router has one configuration file called
routerconfig.xml. This file is read during startup and written on changes followed by a CLI
Preconfig is a way to modify an existing (standard) router configuration before the router is started. A preconfig is stored in one or more XML files and contains modifications of a
routerconfig.xml so that the resulting router configuration exactly matches your router node's configuration. This is especially important for Docker-based installations.
A preconfig XML file looks similar to the router configuration file. It starts with a
<router> element and optionally includes modification operations as subelements:
<router> ... </router>
Any attribute of an element can be modified by specifying a new value. For example, to set a new router name just set the
<router name="edge1"> ... </router>
So it will start a router with the name
Further elements can be modified by referencing them just like in the router configuration file. The modification must start with an
<swiftlet> element and goes down to the element that should be modified. If something should be modified, an attribute
_op needs to be added which can contain the following values:
Removes all entries of an entity list.
Adds a new entity to an entity list.
Removes an entity from an entity list.
Replaces an existing entity that matches the name with a new one.
This modification removes (clears) all AMQP listeners:
<swiftlet name="sys$amqp"> <listeners _op="clear"> </listeners> </swiftlet>
This modification first clears all routing listeners and adds one with the name
plainsocket on port 5001. It also clears all static routes and adds 5 new routes:
<swiftlet name="sys$routing"> <listeners _op="clear"> <listener _op="add" name="plainsocket" port="5100" /> </listeners> <static-routes _op="clear"> <static-route _op="add" name="edge2"/> <static-route _op="add" name="edge3"/> <static-route _op="add" name="edge4"/> <static-route _op="add" name="edge5"/> <static-route _op="add" name="edge6"/> </static-routes> </swiftlet>
This modification removes the MQTT listener with the name
<swiftlet name="sys$mqtt"> <listeners> <listener _op="remove" name="mqtt"/> </listeners> </swiftlet>
This modification replaces the JMS listener with the name
plainsocket with a new one which includes a connection factory:
<swiftlet name="sys$jms"> <listeners> <listener _op="replace" name="plainsocket" port="5001"> <connection-factories> <connection-factory name="ConnectionFactory"/> </connection-factories> <host-access-list/> </listener> </listeners> </swiftlet>
Applying Preconfig Files
Via the router’s command line
Preconfig files are specified as a single argument on the router's command line:
Multiple files are delimited by commas without leading or trailing spaces. They are applied in the order of definition.
If the router starts, it applies all changes against its
routerconfig.xml found in its
config/ directory before any Swiftlet is started. It then saves the changes to the
routerconfig.xml and continues to start the Swiftlets.
Via the preconfig processor
Alternatively, preconfig files can be applied to a
routerconfig.xml without starting a router but by running the preconfig processor:
./preconfigproc <preconfig1>,<preconfig2>,... <routerconfig.xml>
If you run the script under windows with
CMD.EXE, put the first parameter in double-quotes:
./preconfigproc.bat "<preconfig1>,<preconfig2>,..." <routerconfig.xml>
The output is the original
routerconfig.xml with the applied changes from the preconfig files in the order of definition.
Single versus multiple Preconfig Files
A single preconfig file that configures your node is appropriate if the node as a whole is kind of feature-static.
However, if your node should sometimes have a TLS-based JMS listener and sometimes not or it should sometimes have a routing connector to some other node and sometimes not, it makes sense that you don't store the JMS and routing listener modifications in your main preconfig file but provide a
no-routing-connector.xml and combine them as needed.