Skip to main content

Configuring Outgoing Replication Destinations

An AMPS replication target is defined in the Replication section of the configuration file, which contains one or more Destination blocks specifying unique replication targets.

To replicate messages to another instance, the configuration file must include at least one Destination. Multiple Destination configurations can be defined, with each one specifying a single outgoing replication connection and message flow from the AMPS instance.

tip

This section describes configuring an instance as a replication source, that is, as an instance that provides messages to another instance.

Configuring an instance to receive replication connections is similar to configuring it for application connections — both require creating a Transport to handle incoming connections. See the Configuring Incoming Replication Transports section and the Configuring Transports section for details.

For further details on replication, refer to other parts of this section - Replicating Messages Between Instances. Additionally, the Highly Available AMPS Installations section describes how to use the features of AMPS, including replication, to create highly-available AMPS installations.

Destination: Defining Outgoing Messages​

Each Destination defines an outgoing flow of messages.

Destination (required)

  • Defines a destination for outgoing replication messages.

  • Required parent tag, which defines a unique replication target.

  • The Destination block must include all required configuration items listed below.

Destination Configuration​

Described below are the configuration items available for Destination. Expand each item for more details.

SyncType (required)

Defines whether the destination is considered when determining if a message is safely replicated and fully persisted before acknowledging the message to the source.

There are two acknowledgment modes:

  • sync

    This Destination must acknowledge a message as persisted for this instance to acknowledge the message as safely persisted.

  • async

    This Destination does not need to acknowledge a message as persisted for this instance to acknowledge the message as safely persisted.

There is no other behavioral difference between sync and async acknowledgment. That is, there is no difference in replication speed, replication priority, or the requirement to replicate messages to the destination.

However, a destination using sync acknowledgment can be considered safe for failover from this instance, while an async destination should be considered to be in an unknown and potentially unsafe state for failover.

To avoid publishers having to retain messages for an extended period of time if an instance is offline, it is possible to downgrade a Destination configured to use sync acknowledgment to use async acknowledgment. When a Destination is downgraded to async acknowledgment, it must be considered unsafe for failover See Downgrading Acknowledgments for a Destination for details.

Transport (required)

The message type, network location, and connection details for making an outgoing connection to replicate messages.

AMPS supports multiple Transport items within a Destination. When multiple Transports are provided, AMPS interprets these as transports for identical redundant servers, listed in priority order.

If AMPS cannot connect to any of the internet addresses in a transport, AMPS tries the next Transport, in the order in which the Transport items appear in the file. When AMPS has tried all of the Transport items, AMPS tries again at the beginning of the list of transports.

To provide failover, use multiple InetAddr elements within a single Transport for servers that can use the same Authenticator context (that is, the same credentials provided with the same authentication scheme).

Use multiple Transport elements if the failover servers require different authentication.

For details on the contents of the Transport element, see the section on Transports in Destinations below.

Group (required)

The group that the downstream destination is a member of. The Group of the downstream instance must match the Group specified in this destination, or AMPS reports an error and will not replicate to that destination.

There is no built-in default for this value. AMPS requires that a destination have a Group defined. If a Name is specified, and no Group is specified, AMPS will use the value of the Name as the value for the Group. This behavior is for convenience to match the behavior of an AMPS instance when no Group is specified at the instance level configuration.

A Group is required. However, if a Name is specified for this Destination and no Group is specified, AMPS uses the value of the Name as the value of the Group. (Likewise, if Group is specified and no Name is specified, AMPS will use the Group value as the Name for this destination.)

Notice that the Name must be unique within an AMPS replication fabric. If your replication configuration requires more than one Destination that replicates to the same Group, and does not want AMPS replication to treat all of those servers as identical, use the Name element instead of the Group element.

Name

The name of the destination. This name appears in the AMPS logs when AMPS logs a message about this destination. The Name must be unique in the AMPS replication fabric. When not present, AMPS uses the Group provided as the destination Name. The Name should be either the Name or the Group of the remote instance.

60East recommends setting the Name only when your replication configuration replicates to more than one instance in a given group and the configuration does not need to treat the servers within the group as interchangeable. If it is important to replicate to a specific AMPS instance, rather than any server in the Group, set the Name rather than the Group, and use the Name of that instance.

For example, if you have three servers in the AMPS-LA group, the server AMPS-LA-1 would have separate Destination configurations for AMPS-LA-2 and AMPS-LA-3. Those Destination configurations would use the Name of the remote server (AMPS-LA-2 or AMPS-LA-3) rather than the Group that is common to all of the servers.

There is no default for this value. If a Group is specified and no Name is specified, AMPS uses the value of the Group as the Name of the destination.

Topic

Defines one or more topics to replicate to this destination.

A Destination may contain any number of Topic elements. All Topic elements will be used to determine the topics to be replicated to the destination. That is, a topic that matches any of the Topic elements will be replicated.

See the following section Topics in Destinations for details.

PassThrough

Specifies source groups to pass through to this destination.

The value of this element is a regular expression which is matched against the group name of the instance that sent the replication message to this instance. When the regular expression matches, the replication message is eligible for passthrough, and will be sent to the destination if the Topic specifications match the message.

For installations that involve more than two AMPS instances, or installations that use queues, a PassThrough specification may be necessary for replication to distribute the full set of messages in this instance. See the PassThrough Replication section for details.

Using a regular expression that matches all groups (such as .*) provides the highest level of reliability. In some topologies, it may be possible to further refine the groups specified in a PassThrough directive to reduce bandwidth by partially replicating the local transaction log.

Default: There is no default for this value. If no value is configured, then only messages published directly to this instance from an application will be replicated. If there are more than two instances in the set of instances that replicate to each other, it is strongly recommended to set PassThrough to cover all of the groups that should have the same messages.

Compression

Specifies whether to use compression for this destination.

When set to enabled, AMPS compresses traffic to this destination.

Default: disabled

CompressionType

Specifies the library to use for compression for this destination. This option has no effect unless the Compression option is set to enabled.

Supported values for this release are zstd and zlib.

Default: zlib

AckConflationInterval

Specifies the interval to use for conflating acknowledgment messages from this destination.

This value must be an interval of less than 1 second.

See the AMPS User Guide chapter on acknowledgment messages for details on this setting.

Default: 1s

ResyncPassThrough

Specifies source instances to pass through to this destination while replication is in the process of resynchronizing after a connection is made. The value of this element is a regular expression which is matched against the Group name of the instance that sent the replication message to this instance. When the regular expression matches, the replication message is eligible for passthrough, and will be sent to the destination if the Topic specifications match the message.

When present, this value is used during resynchronization instead of the PassThrough value specified. If configured, this value should match every Group that the PassThrough value matches as well as any Group that replicates messages to this instance that are intended to be present on the downstream instance, but which are not included in the PassThrough configuration of this instance.

This element is not required in most replication topologies. However, it can be useful to prevent gaps in replication during failover for topologies that intentionally rely on incomplete replication along certain paths. (Although a topology that does not fully replicate is not recommended, using this configuration item can help reduce the risk of missing messages in a topology that does not replicate messages along all paths that reach an instance that must receive the message).

Default: There is no default for this value. If no value is configured, the PassThrough value, if any, is used for all replication to this destination.

Transports in Destinations​

An outgoing Destination uses one or more Transport elements to specify how the instance will make an outgoing connection to the remote instance of AMPS.

Described below are the configuration items available for a Transport in a Replication/Destination. Expand each item for more details.

Type (required)

Specifies the type of connection to make to the destination.

The Type of a replication destination Transport must always be one of amps-replication or amps-replication-secure.

When the Type is set to amps-replication-secure, the outgoing connection will use TLS/SSL.

The Type of the outgoing connection must match the Type of the Transport that this instance is connecting to.

InetAddr

A Transport for a replication destination can contain one or more InetAddr elements.

An InetAddr element can be specified as an IPv4 address, an IPv6 address, or a resolvable hostname.

When a single InetAddr element is present, AMPS connects to that address for replication.

When more than one InetAddr element is present, AMPS uses the list of addresses as a prioritized list of failover servers to provide high availability. The list is in priority order, with the most preferred server at the beginning of the list. Each time AMPS needs to make a connection for this Destination, AMPS starts with the first address in the list and tries each address in order until a connection succeeds.

If no connection succeeds, AMPS waits for a timeout period and then either moves to the next Transport (if more than one Transport is present in the destination) or starts again with the first address in the list. Each time AMPS tries all of the addresses in the list without a successful connection, AMPS increases the timeout period between tries, up to a maximum timeout. The first time through the list, upon startup, AMPS gives addresses extra time, up to 60 seconds, to connect successfully.

If no InetAddr is specified, then this Destination does not make an outgoing connection. Instead, this instance will wait for the remote instance specified in the Destination to connect, and replicate to that instance once the connection is established. Use this configuration with caution, as this configuration requires another instance of AMPS to connect. This configuration is only recommended in cases where this instance must replicate messages to another instance, but is unable to make a connection to that instance (for example, firewall rules block outgoing connections from the system that hosts the instance).

ReconnectTimeout

A list of intervals that specifies how long AMPS will attempt to connect to a given InetAddr before attempting to connect to the next entry.

This configuration item can contain a single interval, which will be used for all InetAddr entries in the Transport, or a comma-delimited list of intervals.

When a comma-delimited list is provided, the number of intervals provided must match the number of InetAddr entries in the Transport. Each interval is used for the corresponding InetAddr. (In other words, the first entry in the list is used for the first InetAddr, the second entry in the list is used for the second InetAddr, and so on.)

IpProtocolPrefer

A Transport element within a Destination may contain an IpProtocolPrefer element, which specifies the IP protocol to prefer during DNS resolution of hostnames when establishing a bidirectional replication connection.

Currently allowed values for IpProtocolPrefer are:

  • v4 to prefer resolving hostnames to IPv4 addresses
  • v6 to prefer resolving hostnames to IPv6 addresses

If this element is not specified, AMPS will prefer IPv4 name resolution by default. All of the InetAddr elements specified within a Transport use the same IpProtocolPrefer preference.

If a valid DNS entry of the preferred IP protocol cannot be found, AMPS will fall back to the other non-preferred IP protocol type.

If an InetAddr is specified as an explicit IP address, the protocol is determined from the format of the IP address and this setting has no effect.

Authenticator

A Transport element within a Destination may contain an Authenticator element, which specifies a module that provides credentials to use when connecting to the destination.

All InetAddr elements specified within a Transport use the same Authenticator.

Authentication

A Transport element within a Destination may contain an Authentication element, which specifies the Authentication module to use when establishing a bidirectional replication connection. That is, if the other side of the connection will attempt to log in using an outgoing connection from this Destination, this sets the authentication to use for that connection.

All of the InetAddr elements specified within a Transport use the same Authentication module. If this element is not specified, AMPS will use the Authentication module specified for the incoming Transport with a Name matching the Type of this Transport, or the Authentication for the instance if no such Transport is present.

Entitlement

A Transport element within a Destination may contain an Entitlement element, which specifies the Entitlement module to use when establishing a bidirectional replication connection.

All of the InetAddr elements specified within a Transport use the same Entitlement module. If this element is not specified, AMPS will use the Entitlement module specified for the incoming Transport with a Name matching the Type of this Transport, or the Entitlement for the instance if no such Transport is present.

TLS/SSL Parameters

Described below are the configuration items needed to set up and enable TLS/SSL. Expand each item for more details.

Certificate (required if Type is amps-replication-secure)

A Transport element that specifies amps-replication-secure as the transport type must provide a certificate to use for the TLS/SSL connection.

There is no default for this option.

PrivateKey (required if Type is amps-replication-secure)

A Transport element that specifies amps-replication-secure as the transport type must provide a private key to use for the SSL connection.

There is no default for this option.

Ciphers (optional, only supported if Type is amps-replication-secure)

A Transport element that specifies amps-replication-secure as the transport type may provide a cipher list to use for the SSL connection. When provided, this connection is restricted to the specified ciphers.

Default: No restriction on the ciphers supported by the SSL implementation.

VerifyClient (optional, only supported if Type is amps-replication-secure)

When set to true, this destination will verify certificates provided for TLS using the CAFile or CAFileLocation specified.

Default: false

CAFile (one of CAFile or CAPath must be specified if VerifyClient is true)

When VerifyClient is set to true, specifies a .pem file containing trusted certificates used to verify certificates provided by the other side of the replication connection.

There is no default for this option.

CAPath (one of CAFile or CAPath must be specified if VerifyClient is true)

When VerifyClient is set to true, specifies a path to a directory containing .pem files that contain trusted certificates used to verify certificates provided by the other side of the replication connection. When this parameter is provided and VerifyClient is set to true, AMPS will use every .pem file in the directory for verification.

There is no default for this option.

Topics in Destinations​

A replication destination can contain any number of Topic definition elements. For simplicity in working with the configuration file, 60East recommends using a few Topic elements with regular expression patterns over large numbers of individual topic declarations.

When a Destination contains multiple Topic elements, messages that match any of the Topic elements will be replicated. When matching a Topic element, literal (non-regular expression) topic names take priority over regular expression topic names.

Described below are the configuration items available for a Topic in a Replication/Destination. Expand each item for more details.

Name (required)

The topic or topics to replicate. The Name can be either a literal topic name or a regular expression.

When Name is a literal topic, a topic with that name and the specified message type must be captured in a transaction log.

When Name is a regular expression, then topics that match the expression, match the message type, and are present in a transaction log are replicated.

Defaults to the regular expression .*, which matches any topic name, if no value is explicitly set.

MessageType (required)

The message type of the topic or topics to replicate.

Filter

A content filter to apply to the topic or topics.

When present, only messages that match the filter are replicated. This filter follows the standard AMPS filter syntax.

IncludeValidation

The set of configuration checks to validate for this topic.

See Replication Validation section for details.

Default: All validation options listed are included by default.

ExcludeValidation

The set of configuration checks to exclude for this topic.

If the same check appears in both IncludeValidation and ExcludeValidation, ExcludeValidation takes precedence and the check will not be run.

See Replication Validation section for details.

Default: None of the validation options are excluded by default.

Sample Replication Configuration​

This section shows a sample that configures an AMPS instance to provide messages to two downstream destinations.

Notice that this sample does not configure the AMPS instance to receive replication messages. Configuring an instance to receive replication is done in the Transports configuration for the instance. An example of this can be found here - Configuring Incoming Replication Transports.

<Replication>
    <Destination>
        <Group>Data-Center-NYC-1</Group>
        <Topic>
            <Name>ORDER_STATE-Replication</Name>
            <MessageType>xml</MessageType>
        </Topic>
        <Topic>
            <Name>REFERENCE_INFO-.*</Name>
            <MessageType>json</MessageType>
            <Filter>/state = 'published'</Filter>
        </Topic>
        <SyncType>sync</SyncType>
        <Compression>enabled</Compression>
        <Transport>
            <Type>amps-replication</Type>
            <InetAddr>interface1.example.com:19005</InetAddr>
            <InetAddr>interface2.example.com:19080</InetAddr>
            <Authenticator>
                <Module>my-credentials-store-module</Module>
            </Authenticator>
        </Transport>
        <PassThrough>.*</PassThrough>
    </Destination>

    <!-- View server will never receive publishes
         directly from a publisher. That means that it
         does not participate in considering a message
         persisted.

         The destination will therefore be marked async,
         and the validation rules for full replication,
         cascading validation, and enforcement of compatible
         SOW topic definitions will be relaxed. -->

    <Destination>
        <Name>NYC-View-Server-Group</Name>
        <Topic>
            <Name>ORDER_STATE</Name>
            <MessageType>xml</MessageType>
            <ExcludeValidation>replicate,cascade,sow</ExcludeValidation>
        </Topic>
        <SyncType>async</SyncType>
        <Compression>enabled</Compression>
        <Transport>
            <Type>amps-replication</Type>
            <InetAddr>view-server-a.example.com:19005</InetAddr>
            <InetAddr>view-server-b.example.com:19080</InetAddr>
        </Transport>
        <PassThrough>.*</PassThrough>
    </Destination>
</Replication>