Preconfig

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:

XML

    <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 name attribute:

XML

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

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:

XML

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

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:

XML

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

remove

This modification removes the MQTT listener with the name mqtt:

XML

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

replace

This modification replaces the JMS listener with the name plainsocket with a new one which includes a connection factory:

XML

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

CODE

./router <preconfig1>,<preconfig2>,...

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

Since 12.5.3

Alternatively, preconfig files can be applied to a routerconfig.xml without starting a router but by running the preconfig processor:

CODE

./preconfigproc <preconfig1>,<preconfig2>,... <routerconfig.xml>

If you run the script under windows with CMD.EXE, put the first parameter in double-quotes:

CODE

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