Introduction

A SwiftMQ Router has one configuration file called routerconfig.xml. This file is read during startup and written on changes followed by a CLI save command.

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.

Modification Operations

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>
XML

Any attribute of an element can be modified by specifying a new value. For example, to set a new router name just set the name attribute:

    <router name="edge1">
    ...
    </router>
XML

So it will start a router with the name edge1.

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:

Operation

Description

clear

Removes all entries of an entity list.

add

Adds a new entity to an entity list.

remove

Removes an entity from an entity list.

replace

Replaces an existing entity that matches the name with a new one.

Examples

clear

This modification removes (clears) all AMQP listeners:

<swiftlet name="sys$amqp">
  <listeners _op="clear">
  </listeners>
</swiftlet>
XML

add

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>
XML

remove

This modification removes the MQTT listener with the name mqtt:

<swiftlet name="sys$mqtt">
    <listeners>
      <listener _op="remove" name="mqtt"/>
    </listeners>
</swiftlet>
XML

replace

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>  
XML

Applying Preconfig Files

Preconfig files are specified via this System Property on the router's command line:

-Dswiftmq.preconfig=<preconfig1>,<preconfig2>,...
CODE

Multiple files are delimited by comma 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.

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 jms-tls.xml, no-jms-tls.xml, routing-connector.xml and no-routing-connector.xml and combine them as needed.