Replication
Last updated
Last updated
An AMPS replication target is defined within the Replication section of an AMPS configuration file. Within the Replication section, there are one or more Destination sections, each specifying a unique replication target.
Replication is used to distribute data, including for failover and high availability purposes. For a discussion of replication in general, see the section of the AMPS User Guide. The section describes how to use the features of AMPS, including replication, to create highly-available AMPS installations.
The following table contains a listing of the parameters for the Destination section in the Replication section of an AMPS configuration file.
Each individual Destination configures an outgoing replication connection and message flow from this instance of AMPS.
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 involves creating a Transport that accepts replication connections, in the same way that configuring an instance to receive application connections involves creating one or more Transport elements to receive incoming data from applications. See the section of the AMPS User Guide and the section of this guide for details.
Element
Description
Destination
(required)
Required parent tag, which defines a unique replication target.
SyncType
(required)
Defines whether the destination is considered when determining if a message is safely replicated and fully persisted.
sync acknowledgment means that this Destination must acknowledge a message as persisted for this instance to consider the message to acknowledged as safely persisted.
async acknowledgment means that this Destination does not need to acknowledge a message as persisted for this instance to consider the message to be acknowledged 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, at any given point in time, a sync destination should 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.
See the AMPS User Guide 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.
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.
If a Group is specified and no Name is specified, AMPS uses the value of the Group as the Name. 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 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
PassThrough
Specifies source instances 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 AMPS User Guide 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.
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.
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.
The following table describes the configuration available for a Transport in a Replication/Destination.
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, and 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 InetAddress 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 of the 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.
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.
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 SSL connection.
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.
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.
VerifyClient
(optional, only supported if Type is amps-replication-secure)
A Transport element that specifies whether this destination will verify certificates provided for TLS using the CAFile or CAFileLocation specified. When set to true, verification will be performed. Default: false
CAFile
(optional, 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 parameter.
CAPath
(optional, 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 containing 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 parameter.
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.
Element
Description
MessageType
(required)
The message type of the topic or topics to replicate.
Name
(required)
The name of the topic 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.
Filter
A content filter to apply to the topics.
When present, only messages that match the filter are replicated. This filter follows the standard AMPS filter syntax.
IncludeValidation
Default: All validation options listed below are included by default.
ExcludeValidation
The set of configuration checks to exclude for this topic.
Default: None of the validation options listed below are excluded by default.
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.
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 below.
Defines a topic.
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 for details.
The set of configuration checks to validate for this topic. See and the discussion in the AMPS User Guide for details.
If the same check appears in both IncludeValidation and ExcludeValidation, ExcludeValidation takes precedence and the check will not be run.
See and the discussion in the AMPS User Guide for details.