PyPI - amps-python-client - Versions diffs - 5.3.4.1__zip → 5.3.4.3__zip - Mend

amps-python-client 5.3.4.1zip → 5.3.4.3zip

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (918) hide show

amps-python-client-5.3.4.1/docs/user-guide/html/chapters/replication.html DELETED Viewed

@@ -1,1777 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-    <title>25. Replicating Messages Between Instances &#8212; AMPS User Guide develop documentation</title>
-    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
-    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
-    <script type="text/javascript">
-      var DOCUMENTATION_OPTIONS = {
-        URL_ROOT:    '../',
-        VERSION:     'develop',
-        COLLAPSE_INDEX: false,
-        FILE_SUFFIX: '.html',
-        HAS_SOURCE:  true,
-        SOURCELINK_SUFFIX: '.txt'
-      };
-    </script>
-    <script type="text/javascript" src="../_static/jquery.js"></script>
-    <script type="text/javascript" src="../_static/underscore.js"></script>
-    <script type="text/javascript" src="../_static/doctools.js"></script>
-    <link rel="index" title="Index" href="../genindex.html" />
-    <link rel="search" title="Search" href="../search.html" />
-    <link rel="next" title="26. Highly Available AMPS Installations" href="ha.html" />
-    <link rel="prev" title="24. Automating AMPS With Actions" href="actions.html" />
-  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
-  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
-  </head>
-  <body role="document">
-  <div class="document">
-      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
-        <div class="sphinxsidebarwrapper">
-            <p class="logo"><a href="../index.html">
-              <img class="logo" src="../_static/flag_logo.png" alt="Logo"/>
-            </a></p>
-  <h3><a href="../index.html">Table Of Contents</a></h3>
-  <ul>
-<li><a class="reference internal" href="#">25. Replicating Messages Between Instances</a><ul>
-<li><a class="reference internal" href="#replication-basics">Replication Basics</a><ul>
-<li><a class="reference internal" href="#benefits-of-replication">Benefits of Replication</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#configuring-replication">Configuring Replication</a><ul>
-<li><a class="reference internal" href="#sync-vs-async-acknowledgment">Sync vs Async Acknowledgment</a></li>
-<li><a class="reference internal" href="#downgrading-acknowledgments-for-a-destination">Downgrading Acknowledgments for a Destination</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#replication-configuration-validation">Replication Configuration Validation</a></li>
-<li><a class="reference internal" href="#replication-resynchronization">Replication Resynchronization</a></li>
-<li><a class="reference internal" href="#replication-compression">Replication Compression</a></li>
-<li><a class="reference internal" href="#destination-server-failover">Destination Server Failover</a></li>
-<li><a class="reference internal" href="#two-way-replication">Two-Way Replication</a></li>
-<li><a class="reference internal" href="#passthrough-replication">PassThrough Replication</a></li>
-<li><a class="reference internal" href="#guarantees-on-ordering">Guarantees on Ordering</a></li>
-<li><a class="reference internal" href="#replication-security">Replication Security</a></li>
-<li><a class="reference internal" href="#understanding-replication-message-routing">Understanding Replication Message Routing</a></li>
-<li><a class="reference internal" href="#maximum-downstream-destinations">Maximum Downstream Destinations</a></li>
-<li><a class="reference internal" href="#replicated-queues">Replicated Queues</a><ul>
-<li><a class="reference internal" href="#queue-message-ownership">Queue Message Ownership</a><ul>
-<li><a class="reference internal" href="#failover-and-queue-message-ownership">Failover and Queue Message Ownership</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#configuration-for-queue-replication">Configuration for Queue Replication</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#bootstrap-initialization-of-amps-replication">Bootstrap Initialization of AMPS Replication</a><ul>
-<li><a class="reference internal" href="#when-to-use-bootstrap-initialization">When to Use Bootstrap Initialization</a></li>
-<li><a class="reference internal" href="#starting-bootstrap-initialization">Starting Bootstrap Initialization</a></li>
-<li><a class="reference internal" href="#configuring-bootstrap-initialization">Configuring Bootstrap Initialization</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#replication-best-practices">Replication Best Practices</a></li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
-<ul>
-  <li><a href="../index.html">Documentation overview</a><ul>
-      <li>Previous: <a href="actions.html" title="previous chapter">24. Automating AMPS With Actions</a></li>
-      <li>Next: <a href="ha.html" title="next chapter">26. Highly Available AMPS Installations</a></li>
-  </ul></li>
-</ul>
-</div>
-<div id="searchbox" style="display: none" role="search">
-  <h3>Quick search</h3>
-    <form class="search" action="../search.html" method="get">
-      <div><input type="text" name="q" /></div>
-      <div><input type="submit" value="Go" /></div>
-      <input type="hidden" name="check_keywords" value="yes" />
-      <input type="hidden" name="area" value="default" />
-    </form>
-</div>
-<script type="text/javascript">$('#searchbox').show(0);</script>
-        </div>
-      </div>
-      <div class="documentwrapper">
-        <div class="bodywrapper">
-          <div class="body" role="main">
-  <div class="section" id="replicating-messages-between-instances">
-<span id="replication"></span><span id="ha-replication"></span><span id="index-0"></span><h1>25. Replicating Messages Between Instances<a class="headerlink" href="#replicating-messages-between-instances" title="Permalink to this headline">¶</a></h1>
-<p>AMPS has the ability to replicate messages to downstream AMPS instances
-once those messages are stored to a transaction log. Replication in AMPS
-involves the configuration of two or more instances designed to share
-some or all of the published messages. With AMPS replication, an
-upstream (or source) instance delivers messages to
-a downstream instance.</p>
-<p>Replication is typically used to improve the availability of a
-set of AMPS instances by creating a set of servers that hold
-the same messages, where each server can take over for the
-others in the event of a network or server failure.</p>
-<p>Since AMPS replication operates on individual messages,
-replication is also an efficient way to split and share message
-streams between multiple sites where each downstream site
-may only want a subset of the messages from the upstream
-instances.</p>
-<p>AMPS replication uses a leaderless, &#8220;all nodes hot&#8221; model. Any instance
-in a replication fabric can accept publishes and updates at any time,
-and there is no need for a message to be replicated downstream before
-it is delivered to subscribers (unless a subscriber explicitly
-requests otherwise using the <code class="docutils literal"><span class="pre">fully_durable</span></code> option on a
-bookmark replay).</p>
-<div class="admonition tip">
-<p class="first admonition-title">Tip</p>
-<p>The only communication between instances of AMPS is
-through replication. AMPS instances do not share
-state through the filesystem or any out-of-band
-communication.</p>
-<p class="last">AMPS high availability and replication do not rely
-on a quorum or a controller instance. Each instance
-of AMPS processes messages independently. Each
-instance of AMPS manages connections and subscriptions
-locally.</p>
-</div>
-<p>AMPS supports two forms of message acknowledgment for replication links:
-<em>synchronous</em> and <em>asynchronous</em>; these settings control when AMPS considers
-a message persisted. This controls when AMPS sends publishers
-<code class="docutils literal"><span class="pre">persisted</span></code> acknowledgments and the point at which AMPS considers
-a message to be fully persisted for bookmark subscribers. These settings do not
-affect when or how messages are replicated, or when or how messages are
-delivered to subscribers unless a subscriber explicitly requests this
-behavior. These settings only affect when AMPS acknowledges to the publisher
-that the message has been persisted. They do not affect the speed of
-replication, the priority of replication, or the guarantees that AMPS
-makes for ensuring that all replicated messages are acknowledged by
-the downstream instance before they can be removed from the transaction
-log.</p>
-<p>AMPS replication consists of a message stream (or, more precisely, a
-command stream) provided to downstream instances. AMPS replicates
-the messages produced as a result of <code class="docutils literal"><span class="pre">publish</span></code> and <code class="docutils literal"><span class="pre">delta_publish</span></code>
-and replicates <code class="docutils literal"><span class="pre">sow_delete</span></code> commands. AMPS does not
-replicate messages produced internally by AMPS, such as the results of
-<code class="docutils literal"><span class="pre">Views</span></code> or updates sent to a <code class="docutils literal"><span class="pre">ConflatedTopic</span></code>. When replicating
-queues, AMPS also uses the replication connection to send and receive
-administrative commands related to queues, as described in the section
-on <a class="reference internal" href="#ug-replicated-queues"><span class="std std-ref">Replicated Queues</span></a>.</p>
-<div class="admonition important">
-<p class="first admonition-title">Important</p>
-<p>60East recommends that any server that participates in replication
-<em>and</em> that accepts publishes, SOW deletes, or queue acknowledgments
-directly from applications is configured with at least
-one <code class="docutils literal"><span class="pre">sync</span></code> replication destination.</p>
-<p class="last">Without at least one destination that uses <code class="docutils literal"><span class="pre">sync</span></code> acknowledgment,
-an AMPS instance could be a single point of failure, resulting in
-possible message loss if the instance has an unrecoverable failure
-(such as a hardware failure)  between the time that
-the server acknowledges a command to a client, and the time that
-a replication destination receives and persists the command.</p>
-</div>
-<p>Notice that when replicating the results of a <code class="docutils literal"><span class="pre">delta_publish</span></code> command, and
-publishes to a topic that provides preprocessing and enrichment, AMPS
-replicates the fully processed and merged message &#8211; exactly the information
-that is written to the local transaction log and sent to subscribers. AMPS does
-<em>not</em> save the original command to the transaction log or replicate the original
-command. Instead, AMPS stores the message produced by the command and replicates that
-message.</p>
-<div class="section" id="replication-basics">
-<h2>Replication Basics<a class="headerlink" href="#replication-basics" title="Permalink to this headline">¶</a></h2>
-<p>Before planning an AMPS replication topology, it can be helpful to understand
-the basics of how AMPS replication works. This section presents a general
-overview of the concepts that are discussed in more detail in the following
-sections.</p>
-<ul>
-<li><p class="first"><strong>Replication is point-to-point</strong>. Each replication connection involves exactly two
-AMPS instances: a source (that provides messages) and a destination that receives
-messages.</p>
-</li>
-<li><p class="first"><strong>Replication is always &#8220;push&#8221; replication</strong>. In AMPS, the source configures a
-destination, and pushes messages to that destination. (Notice that it is possible
-to configure the source to wait for the destination to connect rather than
-actively making an outgoing connection, but replication is still a &#8220;push&#8221; from
-the source to the destination once that connection is made). The source must be
-configured to push messages to the destination, and
-the source guarantees that all messages to be replicated must be acknowledged
-by the destination before they can be removed from the transaction log.</p>
-</li>
-<li><p class="first"><strong>Replication is one-link by default</strong>. By default, an instance of AMPS
-<em>only</em> replicates messages that are published to that instance by a client.
-Optionally, an instance of AMPS can be configured to replicate messages
-that arrive over replication. Adding this configuration is typically
-required if there are more than two instances in a replicated set
-of AMPS instances. See <a class="reference internal" href="#ug-ha-passthrough"><span class="std std-ref">PassThrough Replication</span></a>
-for details.</p>
-</li>
-<li><p class="first"><strong>Replication relies on the transaction log</strong>. AMPS replicates the commands
-as preserved in the transaction log. This means, for example, that the
-results of delta publishes are replicated as fully-merged messages,
-since fully-merged messages are stored in the transaction log. Likewise,
-if duplicate messages arrive over different paths, only the first message
-to arrive will be stored in the transaction log, and that message is
-the one that will be replicated.</p>
-</li>
-<li><p class="first"><strong>Replication provides a command stream</strong>. In AMPS replication, the server
-replicates the results of <code class="docutils literal"><span class="pre">publish</span></code>, <code class="docutils literal"><span class="pre">delta_publish</span></code> and <code class="docutils literal"><span class="pre">sow_delete</span></code> commands
-once those results are written to the transaction log. Each individual command is
-replicated, for low latency and fine-grained control of what is replicated. If a
-command is not in the transaction log (for example, a maintenance action has
-removed the journal that contains that command, or the command is for a topic
-that is not recorded in the transaction log), that command will not be replicated.</p>
-<p>Replication is intended to guarantee that the command stream for a set of topics
-on one instance is present on the other instance, with the ordering of each
-message source preserved. This means that there can be only <em>one</em> connection
-from a given upstream instance to a given downstream instance.</p>
-</li>
-<li><p class="first"><strong>Replication is customizable by topic, message type, and content</strong>. AMPS can be configured to
-replicate the entire transaction log, or any subset of the transaction log. This makes it
-easy to use replication to populate view servers, test environments, or similar instances
-that require only partial views of the source data.</p>
-</li>
-<li><p class="first"><strong>Replication guarantees delivery</strong>. AMPS will not remove a journal file until
-<em>all</em> messages in that journal file have been replicated to, and acknowledged by,
-the destination.</p>
-</li>
-<li><p class="first"><strong>Replication is composable</strong>. AMPS is capable of building a sophisticated replication
-topology by composing connections. For example, full replication between two servers
-is two point-to-point connections, one in each direction. The basic point-to-point
-nature of connections makes it easy to reason about a single connection, and the
-composable nature of AMPS replication allows you to build replication networks
-that provide data distribution and high availability for applications across
-data centers and around the globe.</p>
-</li>
-<li><p class="first"><strong>Replication acknowledgment is configurable</strong>. The acknowledgment mode
-provides different guarantees: <em>async</em> acknowledgment provides durability
-guarantees for the local instance, whereas <em>sync</em> acknowledgment provides
-durability guarantees for the local instance and the downstream instance.</p>
-</li>
-<li><p class="first"><strong>Group</strong> identifies a set of instances that are intended to be fully
-equivalent for the purposes of message contents, application failover,
-and AMPS replication failover. Instances that are not intended to be
-fully equivalent for all of these purposes should be given a different
-<code class="docutils literal"><span class="pre">Group</span></code> name, even if they are in the same data center or geographic location,
-or if they would be treated as equivalent for some, but not all, purposes.</p>
-</li>
-</ul>
-<p>More details on each of these points is provided in this section.</p>
-<div class="section" id="benefits-of-replication">
-<h3>Benefits of Replication<a class="headerlink" href="#benefits-of-replication" title="Permalink to this headline">¶</a></h3>
-<p id="index-1">Replication can serve two purposes in AMPS:</p>
-<ol class="arabic simple">
-<li>It can increase the fault-tolerance of AMPS by creating a spare
-instance to cut over to when the primary instance fails.</li>
-<li>Replication can be used in message delivery to a remote site.</li>
-</ol>
-<p>In order to provide fault tolerance and reliable remote site message
-delivery, for the best possible messaging experience, there are some
-guarantees and features that AMPS has implemented. Those features are
-discussed below.</p>
-<p>Replication in AMPS supports filtering by both topic and by message
-content. This granularity in filtering allows replication sources to
-have complete control over what messages are sent to their downstream
-replication instances.</p>
-<p>Additionally, replication can improve availability of AMPS by creating a
-redundant instance of an AMPS server. Using replication, all of the
-messages which flow into a primary instance of AMPS can be replicated to
-a secondary spare instance. This way, if the primary instance should
-become unresponsive for any reason, then the secondary AMPS instance can
-be swapped in to begin processing message streams and requests.</p>
-<div class="admonition tip">
-<p class="first admonition-title">Tip</p>
-<p class="last">When an AMPS instance is a replication source, that instance
-<em>guarantees</em> that messages will not be removed from the
-transaction log until all destinations have acknowledged
-the message.</p>
-</div>
-</div>
-</div>
-<div class="section" id="configuring-replication">
-<h2>Configuring Replication<a class="headerlink" href="#configuring-replication" title="Permalink to this headline">¶</a></h2>
-<p id="index-2">Replication configuration involves the configuration of two or more
-instances of AMPS. For testing purposes both instances of AMPS can
-reside on the same physical host before deployment into a production
-environment. When running both instances on one machine, the performance
-characteristics will differ from production, so running both instances
-on one machine is more useful for testing configuration correctness than
-testing overall performance.</p>
-<p>Any instance that is intended to receive messages via replication
-must define an incoming replication transport as one of the
-<code class="docutils literal"><span class="pre">Transports</span></code> for the instance. An instance may have only one
-incoming replication transport.</p>
-<p>Any instance that is intended to replicate messages to another
-instance must specify a <code class="docutils literal"><span class="pre">Replication</span></code> stanza in the
-configuration file with at least one <code class="docutils literal"><span class="pre">Destination</span></code>. An
-instance can have multiple <code class="docutils literal"><span class="pre">Destination</span></code> declarations: each
-one defines a single outgoing replication connection.</p>
-<p>In AMPS replication, instances should only be configured as part
-of the same <code class="docutils literal"><span class="pre">Group</span></code> if they are fully equivalent. That is, not
-only should they contain the same messages, but they should be
-considered failover alternatives for applications and other
-AMPS servers. If two servers are not intended to be fully replicated
-(for example, if there is one-way replication between a production
-server and a test server), they should have different <code class="docutils literal"><span class="pre">Group</span></code>
-values.</p>
-<div class="admonition caution">
-<p class="first admonition-title">Caution</p>
-<p class="last">It&#8217;s important to make sure that when running multiple AMPS
-instances on the same host there are no conflicting ports.
-AMPS will emit an error message and will not start properly if
-it detects that a port specified in the configuration file is
-already in use.</p>
-</div>
-<p>For the purposes of explaining this example, we&#8217;re going to assume a
-simple hot-hot replication case where we have two instances of
-AMPS - the first host is named <code class="docutils literal"><span class="pre">amps-1</span></code> and the second host is named
-<code class="docutils literal"><span class="pre">amps-2</span></code>. Each of the instances are configured to replicate data to
-the other. That is, all messages published to <code class="docutils literal"><span class="pre">amps-1</span></code> are
-replicated to <code class="docutils literal"><span class="pre">amps-2</span></code> and vice versa. This configuration ensures that
-a message published to one instance is available on the other instance in
-the case of a failover (although, of course, the publishers and subscribers
-should also be configured for failover).</p>
-<div class="admonition caution">
-<p class="first admonition-title">Caution</p>
-<p>Every instance of AMPS that will participate in replication
-must have a unique <code class="docutils literal"><span class="pre">Name</span></code> among <em>all</em> of the instances that
-are part of replication.</p>
-<p>All instances that have the same <code class="docutils literal"><span class="pre">Group</span></code> must be able to
-be treated as equivalent by AMPS replication and AMPS
-clients.</p>
-<p class="last">If two instances of AMPS should be treated differently
-(for example, one instance receives publishes while the other
-is a read-only instance that receives one-way replication),
-those instances should be in different groups.</p>
-</div>
-<p>We will first show the relevant portion of the configuration used in
-<code class="docutils literal"><span class="pre">amps-1</span></code>, and then we will show the relevant configuration for
-<code class="docutils literal"><span class="pre">amps-2</span></code>.</p>
-<div class="admonition tip">
-<p class="first admonition-title">Tip</p>
-<p class="last">All topics to be replicated must be recorded in the transaction
-log. The examples below omit the transaction log configuration
-for brevity. Please reference the Transaction Log chapter for
-information on how to configure a transaction log for a topic.</p>
-</div>
-<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
-    <span class="nt">&lt;Name&gt;</span>amps-1<span class="nt">&lt;/Name&gt;</span>
-    <span class="nt">&lt;Group&gt;</span>DataCenter-NYC-1<span class="nt">&lt;/Group&gt;</span>
-    ...
-    <span class="nt">&lt;Transports&gt;</span>
-        <span class="nt">&lt;Transport&gt;</span>
-            <span class="c">&lt;!-- The amps-replication transport is required.</span>
-<span class="c">                 This is a proprietary message format used by</span>
-<span class="c">                 AMPS to replicate messages between instances.</span>
-<span class="c">                 This AMPS instance will receive replication messages</span>
-<span class="c">                 on this transport. The instance can receive</span>
-<span class="c">                 messages from any number of upstream instances</span>
-<span class="c">                 on this transport.</span>
-<span class="c">                 An instance of AMPS may only define one incoming replication</span>
-<span class="c">                 transport.  --&gt;</span>
-            <span class="nt">&lt;Name&gt;</span>amps-replication<span class="nt">&lt;/Name&gt;</span>
-            <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
-            <span class="nt">&lt;InetAddr&gt;</span>10004<span class="nt">&lt;/InetAddr&gt;</span>
-        <span class="nt">&lt;/Transport&gt;</span>
-  <span class="c">&lt;!--</span>
-<span class="c">        Transports for application use also need to</span>
-<span class="c">        be defined. An amps-replication transport can</span>
-<span class="c">        only be used for replication --&gt;</span>
-   ... transports for client use here ...
-    <span class="nt">&lt;/Transports&gt;</span>
-    ...
-    <span class="c">&lt;!-- All replication destinations are defined inside the Replication block. --&gt;</span>
-    <span class="nt">&lt;Replication&gt;</span>
-        <span class="c">&lt;!--</span>
-<span class="c">             Each individual replication destination defines outgoing</span>
-<span class="c">             replication, that is, messages being replicated from</span>
-<span class="c">             this instance of AMPS to another instance of AMPS.</span>
-<span class="c">          --&gt;</span>
-        <span class="nt">&lt;Destination&gt;</span>
-            <span class="c">&lt;!-- The replicated topics and their respective message types are defined here. AMPS</span>
-<span class="c">                allows any number of Topic definitions in a Destination. --&gt;</span>
-            <span class="nt">&lt;Topic&gt;</span>
-                <span class="nt">&lt;MessageType&gt;</span>fix<span class="nt">&lt;/MessageType&gt;</span>
-                <span class="c">&lt;!-- The Name definition specifies the name of the topic or topics to be replicated.</span>
-<span class="c">                    The Name option can be either a specific topic name or a regular expression that</span>
-<span class="c">                    matches a set of topic names. --&gt;</span>
-                <span class="nt">&lt;Name&gt;</span>topic<span class="nt">&lt;/Name&gt;</span>
-            <span class="nt">&lt;/Topic&gt;</span>
-            <span class="nt">&lt;Topic&gt;</span>
-              <span class="c">&lt;!-- Replicate any topic that uses the JSON message type</span>
-<span class="c">                   and that starts with /orders --&gt;</span>
-              <span class="nt">&lt;MessageType&gt;</span>json<span class="nt">&lt;/MessageType&gt;</span>
-              <span class="nt">&lt;Name&gt;</span>^/orders/<span class="nt">&lt;/Name&gt;</span>
-            <span class="nt">&lt;/Topic&gt;</span>
-            <span class="nt">&lt;Name&gt;</span>amps-2<span class="nt">&lt;/Name&gt;</span>
-            <span class="c">&lt;!-- Fully synchronize messages, including messages that</span>
-<span class="c">                 were not originally published to this instance. --&gt;</span>
-            <span class="nt">&lt;PassThrough&gt;</span>.*<span class="nt">&lt;/PassThrough&gt;</span>
-            <span class="c">&lt;!-- The group name of the destination instance (or instances). The name specified</span>
-<span class="c">                here must match the Group defined for the remote AMPS instance, or AMPS reports</span>
-<span class="c">                an error and refuses to connect to the remote instance. --&gt;</span>
-            <span class="nt">&lt;Group&gt;</span>DataCenter-NYC-1<span class="nt">&lt;/Group&gt;</span>
-            <span class="c">&lt;!-- Replication acknowledgment can be either synchronous or</span>
-<span class="c">                 asynchronous. This does not affect the speed or priority of</span>
-<span class="c">                 the connection, but does control when this instance will</span>
-<span class="c">                 acknowledge the message as safely persisted. --&gt;</span>
-            <span class="nt">&lt;SyncType&gt;</span>sync<span class="nt">&lt;/SyncType&gt;</span>
-            <span class="c">&lt;!-- The Transport definition defines the location to which this AMPS instance will</span>
-<span class="c">                replicate messages. The InetAddr points to the hostname and port of the</span>
-<span class="c">                downstream replication instance. The Type for a replication instance should</span>
-<span class="c">                always be amps-replication. --&gt;</span>
-            <span class="nt">&lt;Transport&gt;</span>
-                <span class="c">&lt;!-- The address, or list of addresses, for the replication destination. --&gt;</span>
-                <span class="nt">&lt;InetAddr&gt;</span>amps-2-server.example.com:10005<span class="nt">&lt;/InetAddr&gt;</span>
-                <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
-            <span class="nt">&lt;/Transport&gt;</span>
-        <span class="nt">&lt;/Destination&gt;</span>
-    <span class="nt">&lt;/Replication&gt;</span>
-    ...
-<span class="nt">&lt;/AMPSConfig&gt;</span>
-</pre></div>
-</div>
-<p><em>Configuration used for amps-1</em></p>
-<p>For the configuration of <code class="docutils literal"><span class="pre">amps-2</span></code>, we will use the following example.
-While this example is similar, only the differences between the
-<code class="docutils literal"><span class="pre">amps-1</span></code> configuration will be called out.</p>
-<div class="highlight-xml" id="repl-amps2-config"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
-    <span class="nt">&lt;Name&gt;</span>amps-2<span class="nt">&lt;/Name&gt;</span>
-    <span class="nt">&lt;Group&gt;</span>DataCenter-NYC-1<span class="nt">&lt;/Group&gt;</span>
-    ...
-    <span class="nt">&lt;Transports&gt;</span>
-            <span class="c">&lt;!-- The amps-replication transport is required</span>
-<span class="c">                 This is a proprietary message format used by</span>
-<span class="c">                 AMPS to replicate messages between instances.</span>
-<span class="c">                 This AMPS instance will receive replication messages</span>
-<span class="c">                 on this transport. The instance can receive</span>
-<span class="c">                 messages from any number of upstream instances</span>
-<span class="c">                 on this transport.</span>
-<span class="c">                 An instance of AMPS may only define one incoming replication</span>
-<span class="c">                 transport.  --&gt;</span>
-        <span class="nt">&lt;Transport&gt;</span>
-            <span class="nt">&lt;Name&gt;</span>amps-replication<span class="nt">&lt;/Name&gt;</span>
-            <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
-            <span class="c">&lt;!-- The port where amps-2 listens for replication messages matches the port where</span>
-<span class="c">                amps-1 is configured to send its replication messages. This AMPS instance will</span>
-<span class="c">                receive replication messages on this transport. The instance can receive</span>
-<span class="c">                messages from any number of upstream instances on this transport. --&gt;</span>
-            <span class="nt">&lt;InetAddr&gt;</span>10005<span class="nt">&lt;/InetAddr&gt;</span>
-        <span class="nt">&lt;/Transport&gt;</span>
-    <span class="nt">&lt;/Transports&gt;</span>
-    ...
-    <span class="nt">&lt;Replication&gt;</span>
-        <span class="nt">&lt;Destination&gt;</span>
-            <span class="c">&lt;!-- The Topic definitions for amps-2 match</span>
-<span class="c">                 the definitions for amps-1 so that these</span>
-<span class="c">                 topics contain the same messages in the</span>
-<span class="c">                 transaction log on both instances. --&gt;</span>
-            <span class="nt">&lt;Topic&gt;</span>
-                <span class="nt">&lt;MessageType&gt;</span>fix<span class="nt">&lt;/MessageType&gt;</span>
-                <span class="nt">&lt;Name&gt;</span>topic<span class="nt">&lt;/Name&gt;</span>
-            <span class="nt">&lt;/Topic&gt;</span>
-            <span class="nt">&lt;Topic&gt;</span>
-              <span class="nt">&lt;MessageType&gt;</span>json<span class="nt">&lt;/MessageType&gt;</span>
-              <span class="nt">&lt;Name&gt;</span>^/orders/<span class="nt">&lt;/Name&gt;</span>
-            <span class="nt">&lt;/Topic&gt;</span>
-            <span class="nt">&lt;Name&gt;</span>amps-1<span class="nt">&lt;/Name&gt;</span>
-            <span class="c">&lt;!-- Fully synchronize messages, including messages that</span>
-<span class="c">                 were not originally published to this instance. --&gt;</span>
-            <span class="nt">&lt;PassThrough&gt;</span>.*<span class="nt">&lt;/PassThrough&gt;</span>
-            <span class="nt">&lt;Group&gt;</span>DataCenter-NYC-1<span class="nt">&lt;/Group&gt;</span>
-            <span class="nt">&lt;SyncType&gt;</span>sync<span class="nt">&lt;/SyncType&gt;</span>
-            <span class="nt">&lt;Transport&gt;</span>
-                <span class="c">&lt;!-- The replication destination port for amps-2 is configured to send replication</span>
-<span class="c">                    messages to the same port on which amps-1 is configured to listen for them. --&gt;</span>
-                <span class="nt">&lt;InetAddr&gt;</span>amps-1-server.example.com:10004<span class="nt">&lt;/InetAddr&gt;</span>
-                <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
-            <span class="nt">&lt;/Transport&gt;</span>
-        <span class="nt">&lt;/Destination&gt;</span>
-    <span class="nt">&lt;/Replication&gt;</span>
-    ...
-<span class="nt">&lt;/AMPSConfig&gt;</span>
-</pre></div>
-</div>
-<p><em>Configuration for amps-2</em></p>
-<p>These example configurations replicate the topic named <code class="docutils literal"><span class="pre">topic</span></code> of the message type <code class="docutils literal"><span class="pre">nvfix</span></code>
-and any topic of the message type <code class="docutils literal"><span class="pre">json</span></code> that begins with <code class="docutils literal"><span class="pre">/orders/</span></code> between the
-two instances of AMPS. To replicate more topics, these instances could add
-additional <code class="docutils literal"><span class="pre">Topic</span></code> blocks.</p>
-<div class="section" id="sync-vs-async-acknowledgment">
-<h3>Sync vs Async Acknowledgment<a class="headerlink" href="#sync-vs-async-acknowledgment" title="Permalink to this headline">¶</a></h3>
-<p id="replication-sync-vs-async">When publishing to a topic that is recorded in the transaction log, it
-is recommended that publishers request a <code class="docutils literal"><span class="pre">persisted</span></code> acknowledgment.
-The <code class="docutils literal"><span class="pre">persisted</span></code> acknowledgment message is how AMPS notifies the
-publisher that a message received by AMPS is considered to be safely
-persisted, as specified in the configuration. (The AMPS client
-libraries automatically request this acknowledgment on each <code class="docutils literal"><span class="pre">publish</span></code>
-command when a publish store is present for the client &#8211; that is, any
-time that the client is configured to ensure that the publish is received
-by the AMPS server.)</p>
-<p>Depending on the replication destination configuration for the AMPS
-instance that receives the message, that <code class="docutils literal"><span class="pre">persisted</span></code> acknowledgment
-message will be delivered to the publisher at different times in the
-replication process.</p>
-<p>There are two options: <em>synchronous</em> or <em>asynchronous</em> acknowledgment.
-These two acknowledgment <code class="docutils literal"><span class="pre">SyncType</span></code> options control when
-publishers of messages are sent <code class="docutils literal"><span class="pre">persisted</span></code> acknowledgments.</p>
-<p>For <em>synchronous</em> replication acknowledgments, AMPS will not return a
-<code class="docutils literal"><span class="pre">persisted</span></code> acknowledgment to the publisher for a message until the
-message has been stored to the local transaction log, to the SOW, and
-all downstream synchronous replication destinations have acknowledged
-the message. The figure below shows the cycle of a message being
-published in a replicated instance, and the persisted acknowledgment
-message being returned back to the publisher. Notice that, with this
-configuration, the publisher will not receive an acknowledgment if the
-remote destination is unavailable. 60East recommends that when you use
-<code class="docutils literal"><span class="pre">sync</span></code> replication, you consider setting a policy for downgrading the
-link when a destination is offline, as described in
-<a class="reference internal" href="#ug-replication-downgrade"><span class="std std-ref">Downgrading Acknowledgments for a Destination</span></a>.</p>
-<div class="figure" id="ha-figure-sync-ack">
-<img alt="Synchronous acknowledgment -- no acknowledgment to publisher until the downstream instance acknowledges" src="../_images/HA_sync_ack.png" />
-</div>
-<p><em>Sequence for a Connection Using Sync Acknowledgment</em></p>
-<p>For destinations configured with <em>async</em> replication acknowledgment,
-an AMPS instance does not require that the destination acknowledge that the
-message is persisted before acknowledging the message to the publisher.
-That is, for <em>async</em> acknowledgment, the AMPS instance replicating
-the message sends the <code class="docutils literal"><span class="pre">persisted</span></code> acknowledgment message back
-to the publisher as soon as the message is stored in the local transaction
-log and SOW stores.</p>
-<p>The acknowledgment type (<code class="docutils literal"><span class="pre">SyncType</span></code>) has no effect on how an instance of
-AMPS replicates the message to other instances of AMPS. The acknowledgment
-type <em>only</em> affects whether an instance of AMPS must receive an acknowledgment
-from that <code class="docutils literal"><span class="pre">Destination</span></code> before it will acknowledge a message as having
-been persisted.</p>
-<p>The figure below shows the cycle of a message being published with a
-<code class="docutils literal"><span class="pre">SyncType</span></code> configuration set to <em>async</em> acknowledgment.</p>
-<div class="figure" id="ha-figure-async-ack">
-<img alt="Aynchronous acknowledgment -- acknowledgment to publisher immediately, independent of downstream replication" src="../_images/HA_async_ack.png" />
-</div>
-<p><em>Sequence for a Connection Using Async Acknowledgment</em></p>
-<p>By default, replication destinations do not affect when a message is delivered
-to a subscription. Optionally, a subscriber can request the <code class="docutils literal"><span class="pre">fully_durable</span></code>
-option on a bookmark subscription (that is, a replay from the transaction log).
-When the <code class="docutils literal"><span class="pre">fully_durable</span></code> option is specified, AMPS does not deliver a message
-to that subscriber until all replication destinations configured for <code class="docutils literal"><span class="pre">sync</span></code>
-acknowledgment have acknowledged the message.</p>
-<div class="admonition caution">
-<p class="first admonition-title">Caution</p>
-<p class="last">Every instance of AMPS that accepts publish commands, SOW delete commands
-or allows consumption of messages from queues, should specify at least
-one destination that uses <code class="docutils literal"><span class="pre">sync</span></code> acknowledgment.  If a publish or
-queue consumer may fail over between two (or more) instances of AMPS, those
-instances should specify <code class="docutils literal"><span class="pre">sync</span></code> acknowledgment between them to
-prevent a situation where a message could be lost if an instance fails
-immediately after acknowledging a message to a publisher.</p>
-</div>
-<p>A destination configured for <code class="docutils literal"><span class="pre">sync</span></code> acknowledgment can be
-downgraded to <code class="docutils literal"><span class="pre">async</span></code> acknowledgment while AMPS is running.
-This can be useful in cases where a server is offline for an
-extended period of time due to hardware failure or persistent
-network issues.</p>
-</div>
-<div class="section" id="downgrading-acknowledgments-for-a-destination">
-<span id="ug-replication-downgrade"></span><h3>Downgrading Acknowledgments for a Destination<a class="headerlink" href="#downgrading-acknowledgments-for-a-destination" title="Permalink to this headline">¶</a></h3>
-<p>The AMPS administrative console provides the ability to downgrade a
-replication link from <em>synchronous</em> to <em>asynchronous</em> acknowledgment.
-This feature is useful to relieve memory or storage pressure on publishers
-should a downstream AMPS instance prove unstable, unresponsive, or be
-experiencing excessive latency to the point that it should be
-considered to be offline.</p>
-<p>Downgrading a replication link to <em>asynchronous</em> means that any
-<code class="docutils literal"><span class="pre">persisted</span></code> acknowledgment message that a publisher may be waiting on
-will no longer wait for the downstream instance to confirm that it has
-committed the message to its downstream Transaction Log or SOW store.
-AMPS immediately considers the downstream instance to have acknowledged
-the message for existing messages, which means that if AMPS was waiting
-for acknowledgment from that instance to deliver a <code class="docutils literal"><span class="pre">persisted</span></code>
-acknowledgment, AMPS immediately sends the <code class="docutils literal"><span class="pre">persisted</span></code>
-acknowledgment when the instance is downgraded.</p>
-<p>The result of a link being downgraded is:</p>
-<ul class="simple">
-<li>The number of messages that the publisher must retain is reduced, <em>but</em></li>
-<li>The downgraded link is unsafe for the publisher to fail over to</li>
-<li>The downgraded link is unsafe for a bookmark subscriber to fail over to</li>
-</ul>
-<p>Automatic downgrade is most suitable for a situation where an instance
-should be considered offline or unavailable.</p>
-<div class="admonition caution">
-<p class="first admonition-title">Caution</p>
-<p>Downgrading a destination means that this instance will not
-wait for that destination to acknowledge a message
-before acknowledging that message to publishers or
-upstream instances. It does not affect any other
-behavior of the instance.</p>
-<p>A publisher or queue consumer must not fail over
-from this instance to a destination that has been
-downgraded to <code class="docutils literal"><span class="pre">async</span></code> acknowledgment. This can
-cause message loss, since the upstream instance may
-have acknowledged a message that the downstream
-instance has not yet processed.</p>
-<p class="last">A bookmark subscriber must not fail over from
-this instance to a destination that has been
-downgraded to <code class="docutils literal"><span class="pre">async</span></code> acknowledgment. This can
-cause replay gaps, since that destination is
-no longer considered when determining whether
-a message is persisted.</p>
-</div>
-<p>AMPS can be configured to automatically downgrade a replication link to
-<code class="docutils literal"><span class="pre">asynchronous</span></code> if the remote side of the link cannot keep up with
-persisting messages or becomes unresponsive. This option prevents
-unreliable links from holding up publishers, but increases the chances
-of a single instance failure resulting in message loss, as described
-above. AMPS can also be configured to automatically upgrade a
-replication link that has previously been downgraded. If an instance
-is configured to downgrade acknowledgment, it should also
-be configured to upgrade acknowledgment.</p>
-<p>Automatic downgrade is implemented as an AMPS action. To configure
-automatic downgrade, add the appropriate action to the configuration
-file as shown below:</p>
-<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
-    ...
-    <span class="nt">&lt;Actions&gt;</span>
-        <span class="nt">&lt;Action&gt;</span>
-            <span class="nt">&lt;On&gt;</span>
-                <span class="nt">&lt;Module&gt;</span>amps-action-on-schedule<span class="nt">&lt;/Module&gt;</span>
-                <span class="nt">&lt;Options&gt;</span>
-                    <span class="c">&lt;!--This option determines how often AMPS checks whether destinations have fallen</span>
-<span class="c">                    behind. In this example, AMPS checks destinations every 15 seconds. In most</span>
-<span class="c">                    cases, 60East recommends setting this to half of the Interval setting. --&gt;</span>
-                    <span class="nt">&lt;Every&gt;</span>15s<span class="nt">&lt;/Every&gt;</span>
-                <span class="nt">&lt;/Options&gt;</span>
-            <span class="nt">&lt;/On&gt;</span>
-            <span class="nt">&lt;Do&gt;</span>
-                <span class="nt">&lt;Module&gt;</span>amps-action-do-downgrade-replication<span class="nt">&lt;/Module&gt;</span>
-                <span class="nt">&lt;Options&gt;</span>
-                    <span class="c">&lt;!--The maximum amount of time for a destination to fall behind. If AMPS has been</span>
-<span class="c">                     waiting for an acknowledgment from the destination for longer than the</span>
-<span class="c">                     Interval, AMPS downgrades the destination. In this example, AMPS downgrades any</span>
-<span class="c">                     destination for which an acknowledgment has taken longer than 300 seconds. --&gt;</span>
-                    <span class="nt">&lt;Age&gt;</span>300s<span class="nt">&lt;/Age&gt;</span>
-                <span class="nt">&lt;/Options&gt;</span>
-            <span class="nt">&lt;/Do&gt;</span>
-            <span class="nt">&lt;Do&gt;</span>
-                <span class="nt">&lt;Module&gt;</span>amps-action-do-upgrade-replication<span class="nt">&lt;/Module&gt;</span>
-                <span class="nt">&lt;Options&gt;</span>
-                   <span class="c">&lt;!-- The threshold for upgrading the replication link back to sync</span>
-<span class="c">                        acknowledgment. If the destination is behind by less than this</span>
-<span class="c">                        amount, and was previously downgraded to async acknowledgment,</span>
-<span class="c">                        AMPS will upgrade to sync acknowledgment.</span>
-<span class="c">                        --&gt;</span>
-                    <span class="nt">&lt;Age&gt;</span>10s<span class="nt">&lt;/Age&gt;</span>
-                <span class="nt">&lt;/Options&gt;</span>
-            <span class="nt">&lt;/Do&gt;</span>
-        <span class="nt">&lt;/Action&gt;</span>
-    <span class="nt">&lt;/Actions&gt;</span>
-   ...
-<span class="nt">&lt;/AMPSConfig&gt;</span>
-</pre></div>
-</div>
-<p>In this configuration file, AMPS checks every 15 seconds to see if a
-destination has fallen behind by 300 seconds.  If a destination has
-fallen behind by more than 300 seconds, that destination should
-no longer be considered reliable. AMPS downgrades the destination
-to <code class="docutils literal"><span class="pre">async</span></code> acknowledgment. That destination will no longer
-be considered when acknowledging messages to publishers,
-and publishers should not consider that destination to be
-an option for failover until the destination catches up.</p>
-<div class="admonition tip">
-<p class="first admonition-title">Tip</p>
-<p class="last">All publishers using a publish store should be able to hold
-a number of messages equal to the number of messages published,
-at peak message volume, for a time period equal to the
-periodicity of the downgrade check plus the threshold for downgrade.
-With the configuration above, a publisher that publishes at a peak
-rate of 10,000 messages per second should, at a minimum, be able
-to allocate a publish store that holds 750,000 messages.</p>
-</div>
-<p>In some cases, it is important that a destination maintain a minimum
-number of destinations that use <code class="docutils literal"><span class="pre">sync</span></code> acknowledgment. For those
-cases, an instance-level <code class="docutils literal"><span class="pre">Tuning</span></code> parameter is available that
-will prevent the action from downgrading a connection if doing so
-would reduce the number of destinations that use <code class="docutils literal"><span class="pre">sync</span></code> acknowledgment
-below the configured limit. This parameter does not guarantee whether
-a specific destination will continue using <code class="docutils literal"><span class="pre">sync</span></code> acknowledgment. This
-parameter only limits whether AMPS will downgrade a destination that
-meets downgrade criteria. AMPS will not upgrade a destination that
-has previously been downgraded if a connection is lost, even if
-this means that the number of currently connected destinations that
-use <code class="docutils literal"><span class="pre">sync</span></code> acknowledgment is less than the configured minimum.
-See the <em>AMPS Configuration Guide</em> section on instance-level
-parameters for details.</p>
-</div>
-</div>
-<div class="section" id="replication-configuration-validation">
-<h2>Replication Configuration Validation<a class="headerlink" href="#replication-configuration-validation" title="Permalink to this headline">¶</a></h2>
-<p>Replication configuration validation helps to ensure that
-any configuration that could result in message loss or inconsistent
-message contents between two instances of AMPS is explicitly
-designed into the replication topology and not the result
-of accidental misconfiguration.</p>
-<p>Replication can involve coordinating configuration among a large number
-of AMPS instances. It can sometimes be difficult to ensure that all
-of the instances are configured correctly, and to ensure that a
-configuration change for one instance is also made at the replication
-destinations. For example, if a high-availability pair replicates the
-topics ORDERS, INVENTORY, and CUSTOMERS to a remote disaster recovery
-site, but the disaster recovery site only replicates ORDERS and
-INVENTORY back to the high-availability pair, disaster recovery may not
-occur as planned. Likewise, if only one member of the HA pair replicates
-ORDERS to the other member of the pair, the two instances will contain
-different messages, which could cause problems for the system.</p>
-<p>Starting in the 5.0 release, AMPS automatic replication configuration
-validation makes it easier to keep configuration items consistent across
-a replication fabric.</p>
-<p>Replication configuration validation happens when a replication
-connection is made between two instances. The validation compares
-the configuration of those two instances. By default, any difference
-in configuration that could result in message loss, different
-behavior between the source instance and the destination instance,
-or different replication guarantees between the source instance
-and the destination instance is reported as an error.</p>
-<div class="admonition important">
-<p class="first admonition-title">Important</p>
-<p class="last">When replication validation reports an error, the reason for the
-error is logged to the event log on the instance that detects
-the problem, and the connection is closed.</p>
-</div>
-<p>Automatic configuration validation is enabled for all elements of the
-replication configuration by default. You can turn off validation for
-specific elements of the configuration, as described below.</p>
-<p>AMPS replication uses a leaderless, &#8220;all nodes hot&#8221; model. This means
-that no single AMPS instance has a view of the entire replication
-fabric, and a single AMPS instance will always assume that there are
-instances in the replication fabric that it is not aware of. The
-replication validation rules are designed with this assumption. The
-advantage of this assumption is that if instances are added to the
-replication fabric, it is typically only necessary to change
-configuration on the instances that they directly communicate with
-for replication to function as expected. The tradeoff, however, is
-that it is sometimes necessary to configure an instance as though
-it were part of a larger fabric (or exclude a validation rule)
-even in a case where the instance is part of a much simpler
-replication design.</p>
-<p>Each <code class="docutils literal"><span class="pre">Topic</span></code> in a replication <code class="docutils literal"><span class="pre">Destination</span></code> can configure a unique
-set of validation checks. By default, all of the checks apply to all
-topics in the <code class="docutils literal"><span class="pre">Destination</span></code>.</p>
-<p>When troubleshooting a configuration validation error, it is important
-to look at the AMPS logs on <em>both</em> sides of the connection. Typically, the
-AMPS instance that detects the error will log complete information on the
-part of validation that failed and the changes required for the connection
-to succeed, while the other side of the connection will simply note that the
-connection failed validation. This means that if a validation error is reported
-on one instance, but details are not present, the other side of the connection
-detected the error and will have logged relevant details.</p>
-<div class="admonition warning">
-<p class="first admonition-title">Warning</p>
-<p class="last">Excluding a validation check directs AMPS to make a
-replication connection that could result in inconsistent
-state or data loss. Use caution when excluding
-validation checks. See the table below for
-details on each validation check.</p>
-</div>
-<p>The table below lists aspects of replication that AMPS validates. By default, replication
-validation treats the downstream instance as though it is intended to be a full
-highly-available failover partner for any topic that is replicated. For situations
-where that is not the case, many validation rules can be excluded. For example, if
-the downstream instance is a view server that does not accept publishes and,
-therefore, is not configured to replicate a particular topic back to this instance,
-the <code class="docutils literal"><span class="pre">replicate</span></code> validation check might need to be excluded.</p>
-<p>AMPS performs the following validation checks:</p>
-<table border="1" class="docutils" id="id1">
-<caption><span class="caption-text"><em>Replication validation checks</em></span><a class="headerlink" href="#id1" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Check</th>
-<th class="head">Validates</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">txlog</span></code></td>
-<td><p class="first">The topic is contained in the
-transaction log of the remote
-instance.</p>
-<p class="last">An error on this validation check
-indicates that this instance is
-replicating a topic that is not in
-the transaction log on the
-downstream instance. This means
-that the downstream instance is not
-persisting the messages in a way
-that can be used for replication,
-replay, or used as the basis
-for a queue.</p>
-</td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">replicate</span></code></td>
-<td><p class="first">The topic is replicated from the
-remote instance back to this
-instance.</p>
-<p class="last">An error on this validation check
-indicates that this instance is
-replicating a topic to the
-downstream instance that is not
-being replicated back to this
-instance. This means that any
-publishes or updates to the topic
-on the downstream instance are not
-replicated back to this instance.</p>
-</td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">sow</span></code></td>
-<td><p class="first">If the topic is a SOW topic in this
-instance, it must also be a SOW
-topic in the remote instance.</p>
-<p class="last">An error on this validation check
-indicates that this instance is
-replicating a topic to the
-downstream instance that is a
-<code class="docutils literal"><span class="pre">SOW/Topic</span></code> on this instance, but
-is not a <code class="docutils literal"><span class="pre">SOW/Topic</span></code> on the
-downstream instance. This means that
-the topic has different behavior
-on the downstream instance, and
-does not maintain the current value
-of records in the topic in the
-SOW.</p>
-</td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">cascade</span></code></td>
-<td><p class="first">The remote instance must enforce the
-same set of validation checks for
-this topic as this instance does.</p>
-<p>When relaxing validation rules for
-a topic that the downstream instance
-itself replicates, adding an
-exclusion for <code class="docutils literal"><span class="pre">cascade</span></code> is often
-necessary as well.</p>
-<p>An error on this validation check
-indicates that this instance
-enforces a validation check for a
-topic that the downstream instance
-does not enforce when that instance
-replicates the topic.</p>
-<p>To understand the impact of this
-validation check, consider the
-validation checks that the
-downstream instance enforces. If
-the downstream instance enforces
-the appropriate validation checks,
-this instance can exclude
-the <code class="docutils literal"><span class="pre">cascade</span></code> check.</p>
-<div class="last admonition tip">
-<p class="first admonition-title">Tip</p>
-<p class="last">It is sometimes necessary to
-exclude this check as part of a
-rolling upgrade, and then to leave
-this exclusion in place until all
-instances can be taken offline at
-the same time. If the <code class="docutils literal"><span class="pre">cascade</span></code>
-check is the only check being
-excluded on any instance, the
-topology can be considered to meet
-validation rules (and the
-<code class="docutils literal"><span class="pre">cascade</span></code> exclusion can be safely
-removed during a maintenance window
-when all of the instances can be
-updated simultaneously).</p>
-</div>
-</td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">queue</span></code></td>
-<td><p class="first">If the topic is a queue in this
-instance, it must also be a queue in
-the remote instance.</p>
-<p>A distributed queue will not
-function correctly if one of the
-instances it is replicated to
-does not define the topic as a
-queue.</p>
-<p class="last">This option cannot be excluded.</p>
-</td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">keys</span></code></td>
-<td><p class="first">If the topic is a SOW topic in this
-instance, it must also be a SOW
-topic in the remote instance and the
-SOW in the remote instance must use
-the same <code class="docutils literal"><span class="pre">Key</span></code> definitions.</p>
-<p class="last">An error on this validation check
-indicates that this instance is
-replicating a topic to the
-downstream instance that is a
-<code class="docutils literal"><span class="pre">SOW/Topic</span></code> on both instances, but
-that the definition of message
-identity (the <code class="docutils literal"><span class="pre">Key</span></code> configuration
-for the topic) does not match on
-the two instances. This means
-that the contents of this topic
-may be different on these two
-instances for the same set
-of messages published.</p>
-</td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">replicate_filter</span></code></td>
-<td><p class="first">If this topic uses a replication
-filter, the remote instance must use
-the same replication filter for
-replication back to this instance.</p>
-<p class="last">An error on this validation check
-indicates that this instance uses a
-replication filter for a topic that
-the downstream instance does not
-use when it replicates the topic.
-This means that, given the same
-set of publishes, the downstream
-instance may replicate a different
-set of messages than are replicated
-to that instance. This would
-produce inconsistent data across
-the set of replicated instances.</p>
-</td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">queue_passthrough</span></code></td>
-<td><p class="first">If the topic is a queue in this
-instance, the remote instance must
-support passthrough from this group.</p>
-<p class="last">An error on this validation check
-indicates that this instance does
-not pass through messages for one
-or more groups that the queue is
-replicated from. This could lead to
-a situation where a queue message
-is undeliverable if a network
-connection is unavailable or if
-additional instances are added to
-the set of instances that contain
-the queue.</p>
-</td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">queue_underlying</span></code></td>
-<td><p class="first">If the topic is a queue in this
-instance, it must use the same
-underlying topic definition and
-filters in the remote instance.</p>
-<p class="last">This option cannot be excluded.</p>
-</td>
-</tr>
-</tbody>
-</table>
-<p><em>Replication Configuration Validation</em></p>
-<p>Notice that, by default, <em>all</em> of these checks are applied.</p>
-<p>The sample below shows how to exclude validation checks for a replication
-destination. In this sample, the <code class="docutils literal"><span class="pre">Topic</span></code> does not require the remote destination
-to replicate back to this instance, and does not require that the remote
-destination enforce the same configuration checks for any downstream
-replication of this topic.</p>
-<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Destination&gt;</span>
-    ...
-    <span class="nt">&lt;Topic&gt;</span>
-        <span class="nt">&lt;MessageType&gt;</span>json<span class="nt">&lt;/MessageType&gt;</span>
-        <span class="nt">&lt;Name&gt;</span>MyStuff-VIEW<span class="nt">&lt;/Name&gt;</span>
-        <span class="nt">&lt;ExcludeValidation&gt;</span>replicate,cascade<span class="nt">&lt;/ExcludeValidation&gt;</span>
-    <span class="nt">&lt;/Topic&gt;</span>
-    ...
-<span class="nt">&lt;/Destination&gt;</span>
-</pre></div>
-</div>
-</div>
-<div class="section" id="replication-resynchronization">
-<h2>Replication Resynchronization<a class="headerlink" href="#replication-resynchronization" title="Permalink to this headline">¶</a></h2>
-<p>When a replication connection is established between AMPS
-instances, the upstream instance publishes any messages that it
-contains in its transaction log that the downstream instance
-may not have previously received. This process is called
-&#8220;replication resync&#8221;. During resync, the upstream instance
-replays from the transaction log, replicating messages that
-match the <code class="docutils literal"><span class="pre">Topic</span></code> (and, optionally, <code class="docutils literal"><span class="pre">Filter</span></code>) specification(s)
-for the downstream <code class="docutils literal"><span class="pre">Destination</span></code>.</p>
-<p>When a replication connection is established between AMPS servers
-that are both version 5.3.3.0 or higher, the servers exchange
-information about the messages present in the transaction log to
-determine the earliest message in the transaction log on the
-upstream instance that is not present on the downstream instance.
-Replication resynchronization will begin at that point. This
-approach to finding the resynchronization point applies
-whether or not these two instances have had a replication
-connection before.</p>
-<p>For replication between older versions of AMPS, replication
-resynchronization begins at the last point in the upstream
-instance&#8217;s transaction log that the downstream instance has
-received. For those versions of AMPS, messages from other
-instances are not considered when determining the
-resynchronization point.</p>
-</div>
-<div class="section" id="replication-compression">
-<span id="index-3"></span><h2>Replication Compression<a class="headerlink" href="#replication-compression" title="Permalink to this headline">¶</a></h2>
-<p>AMPS provides the ability to compress the replication connection. In
-typical use, using replication compression can greatly reduce the
-bandwidth required between AMPS instances.</p>
-<p>The precise amount of compression that AMPS can achieve depends on the
-content of the replicated messages. Compression is configured at the
-replication source, and does not need to be enabled in the transport
-configuration at the instance receiving the replicated messages.</p>
-<p>For AMPS instances that are receiving replicated messages, no additional
-configuration is necessary. AMPS automatically recognizes when an
-incoming replication connection uses compression.</p>
-<p>See the <em>AMPS Configuration Guide</em> for enabling compression and choosing
-a compression algorithm.</p>
-</div>
-<div class="section" id="destination-server-failover">
-<h2>Destination Server Failover<a class="headerlink" href="#destination-server-failover" title="Permalink to this headline">¶</a></h2>
-<p>Your replication plan may include replication to a server that is part
-of a highly-available group.</p>
-<p>There are two common approaches to destination server failover:</p>
-<ol class="arabic simple">
-<li><strong>Wide IP</strong> - AMPS replication works transparently with wide IP and
-many installations use wide IP for destination server failover. The
-advantage of this approach is that it requires no additional
-configuration in AMPS and redundant servers can be added or removed
-from the wide IP group without reconfiguring the instances that
-replicate to the group. A disadvantage to this approach is that failover
-can require several seconds and messages are not replicated during the
-time that it takes for failover to occur.</li>
-<li><strong>AMPS Failover</strong> - AMPS allows you to specify multiple downstream
-servers in the <code class="docutils literal"><span class="pre">InetAddr</span></code> element of a destination. In this case, AMPS
-treats the defined list of servers as a list of equivalent servers, listed
-in order of priority.</li>
-</ol>
-<p>When multiple addresses are specified for a destination, each time AMPS
-needs to make a connection to a destination and there is no incoming
-connection from a server in that destination, AMPS starts at the
-beginning of the list and attempts to connect to each address in the
-list. If AMPS is unable to connect to any address in the list, AMPS
-waits for a timeout period, then begins again with the first server on
-the list. Each time AMPS reaches the end of the list without
-establishing a connection, AMPS increases the timeout period. If an incoming
-connection from one of the servers on the list exists, AMPS will use that
-connection for outgoing replication. If multiple incoming connections
-from servers in the list exist, AMPS will choose one of the incoming
-connections to use for outgoing traffic.</p>
-<p>This capability allows you to easily set up replication to a
-highly-available group. If the server you are replicating to fails over,
-AMPS uses the prioritized list of servers to re-establish a connection.</p>
-</div>
-<div class="section" id="two-way-replication">
-<h2>Two-Way Replication<a class="headerlink" href="#two-way-replication" title="Permalink to this headline">¶</a></h2>
-<p>Two-way replication, sometimes called <em>Back Replication</em>, is a term used
-to describe a replication scenario where there are two instances of AMPS
-&#8211; termed <code class="docutils literal"><span class="pre">AMPS-A</span></code> and <code class="docutils literal"><span class="pre">AMPS-B</span></code> for this example.</p>
-<p>In a two-way replication configuration, messages that are published to <code class="docutils literal"><span class="pre">AMPS-A</span></code>
-are replicated to <code class="docutils literal"><span class="pre">AMPS-B</span></code>. Likewise, messages which are published to
-<code class="docutils literal"><span class="pre">AMPS-B</span></code> are replicated to <code class="docutils literal"><span class="pre">AMPS-A</span></code>. This replication scheme is used
-when both instances of AMPS need to be in sync with each other to handle
-a failover scenario with no loss of messages between them. This way, if
-<code class="docutils literal"><span class="pre">AMPS-A</span></code> should fail at any point, applications can immediately fail over
-to the <code class="docutils literal"><span class="pre">AMPS-B</span></code> instance, allowing message flow to resume with as little
-downtime as possible.</p>
-<p>To enable two-way replication, each instance of AMPS defines
-a replication <code class="docutils literal"><span class="pre">Transport</span></code> to receive incoming replication
-messages. Each instance also defines a replication <code class="docutils literal"><span class="pre">Destination</span></code>
-to deliver messages to the other instance.</p>
-<p>Notice that servers are intended to function as failover partners.
-Since a publisher may fail over between these two instances, the
-<code class="docutils literal"><span class="pre">Destination</span></code> on each instance that replicates to the other instance
-is configured to use <code class="docutils literal"><span class="pre">sync</span></code> message acknowledgment. This
-ensures that a publisher does not consider a message to be persisted
-until all of the failover partners have received and persisted the
-message.</p>
-<div class="admonition warning">
-<p class="first admonition-title">Warning</p>
-<p class="last">When configuring a set of instances for failover, it is important that
-the instances use <code class="docutils literal"><span class="pre">sync</span></code> message acknowledgment among the set of
-instances that a given client will consider for failover. It should never be
-possible for a publisher to fail over from one instance to another instance
-if the replication link between those instances is configured for <code class="docutils literal"><span class="pre">async</span></code>
-acknowledgments.</p>
-</div>
-<p id="index-4">Starting with the 5.0 release, when AMPS detects back replication
-between a pair of instances, AMPS will prefer using a single network
-connection between the servers, replicating messages in both directions
-(that is, to both destinations) over a single connection.  This can
-be particularly useful for situations where you need to have messages
-replicated, but only one server can initiate a connection. For example,
-when one of the servers is in a DMZ, and cannot make a connection to a
-server within the company. AMPS also allows you to specify a replication
-destination with no InetAddr provided. In this case, the instance will
-replicate once the destination establishes a connection, but will not initiate
-a connection. When both instances specify an InetAddr, AMPS may temporarily
-create two connections between the instances while replication is being established.
-In this case, after detecting that there are two connections active, AMPS will
-close one of the network connections and allow both AMPS instances to use
-the remaining network connection to publish messages to the other instance.
-Notice that using a single network connection is simply an optimization to
-more efficiently use the available sockets. This does not change the way
-messages are replicated or the replication protocol, nor does it change the
-requirement that all messages in a journal are replicated to all destinations
-before a journal can be removed.</p>
-</div>
-<div class="section" id="passthrough-replication">
-<span id="ug-ha-passthrough"></span><h2>PassThrough Replication<a class="headerlink" href="#passthrough-replication" title="Permalink to this headline">¶</a></h2>
-<p>PassThrough Replication is a term used to describe the ability of an
-AMPS instance to pass along replicated messages to another AMPS
-instance. This allows you to easily keep multiple failover or DR
-destinations in sync from a single AMPS instance. Unless passthrough
-replication is configured, an AMPS instance only replicates messages
-directly published to that instance from an application. By default,
-an instance <em>does not</em> re-replicate messages received over replication.</p>
-<p>PassThrough replication uses the name of the originating AMPS group to
-indicate that messages that arrive at this instance of AMPS directly
-from that group are to be replicated to the specified destination.
-PassThrough replication supports regular expressions to specify groups,
-and allows multiple server groups per destination. Notice that if the
-destination instance does not specify a <code class="docutils literal"><span class="pre">Group</span></code> in its instance config,
-the group name is the <code class="docutils literal"><span class="pre">Name</span></code> of the instance.</p>
-<p>To ensure that an instance replicates a full copy of its transaction
-log downstream (which is typically the intended result), include
-a <code class="docutils literal"><span class="pre">PassThrough</span></code> configuration item that matches any group name.</p>
-<p>With care, some topologies can use a <code class="docutils literal"><span class="pre">PassThrough</span></code> configuration
-that only replicates messages directly published to the instance
-and a subset of messages received over replication.
-This can result in significant bandwidth reduction in some
-topologies, but must be configured with care to ensure that
-messages do not fail to reach all of the instances, since
-in this case AMPS is configured to replicate only a <em>part</em> of
-the transaction log of the local instance.</p>
-<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Replication&gt;</span>
-    <span class="nt">&lt;Destination&gt;</span>
-        <span class="nt">&lt;Name&gt;</span>AMPS2-HKG<span class="nt">&lt;/Name&gt;</span>
-        <span class="c">&lt;!-- No group specified: this destination is for</span>
-<span class="c">             a server at the same site, and is responsible for</span>
-<span class="c">             populating the specific replication partner. --&gt;</span>
-        <span class="nt">&lt;Transport&gt;</span>
-            <span class="nt">&lt;Name&gt;</span>amps-replication<span class="nt">&lt;/Name&gt;</span>
-            <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
-            <span class="nt">&lt;InetAddr&gt;</span>secondaryhost:10010<span class="nt">&lt;/InetAddr&gt;</span>
-        <span class="nt">&lt;/Transport&gt;</span>
-        <span class="nt">&lt;Topic&gt;</span>
-            <span class="nt">&lt;Name&gt;</span>/rep_topic<span class="nt">&lt;/Name&gt;</span>
-            <span class="nt">&lt;MessageType&gt;</span>fix<span class="nt">&lt;/MessageType&gt;</span>
-        <span class="nt">&lt;/Topic&gt;</span>
-        <span class="nt">&lt;Topic&gt;</span>
-            <span class="nt">&lt;Name&gt;</span>/rep_topic2<span class="nt">&lt;/Name&gt;</span>
-            <span class="nt">&lt;MessageType&gt;</span>fix<span class="nt">&lt;/MessageType&gt;</span>
-        <span class="nt">&lt;/Topic&gt;</span>
-        <span class="nt">&lt;SyncType&gt;</span>sync<span class="nt">&lt;/SyncType&gt;</span>
-        <span class="c">&lt;!-- Specify which messages received via replication will be replicated</span>
-<span class="c">             to this destination (provided that the Topic and MessageType also match).</span>
-<span class="c">             This destination will receive messages that arrive via replication from</span>
-<span class="c">             AMPS instances with a group name that does not contain HKG. Replicated</span>
-<span class="c">             messages from an instance that has a group name that matches HKG will not be</span>
-<span class="c">             sent to this destination.</span>
-<span class="c">             Regardless of the PassThrough configuration, all messages published directly</span>
-<span class="c">             to this instance by an AMPS client will be replicated to this destination</span>
-<span class="c">             if the Topic and MessageType match.</span>
-<span class="c">        --&gt;</span>
-        <span class="nt">&lt;PassThrough&gt;</span>^((?!HKG).)*$<span class="nt">&lt;/PassThrough&gt;</span>
-     <span class="nt">&lt;/Destination&gt;</span>
-<span class="nt">&lt;/Replication&gt;</span>
-</pre></div>
-</div>
-<p>When a message is eligible for passthrough replication, topic and
-content filters in the replication destination still apply. The
-passthrough directive simply means that the message is eligible for
-replication from this instance if it comes from an instance in the
-specified group.</p>
-<p>AMPS protects against loops in passthrough replication by tracking the
-instance names or group names that a message has passed through. AMPS
-does not allow a message to travel through the same instance and group name
-more than once.</p>
-<div class="admonition caution">
-<p class="first admonition-title">Caution</p>
-<p class="last">When using passthrough, AMPS will not send a message to an
-instance that the message has already traveled through
-to protect against replication loops.</p>
-</div>
-<p>If an instance replicates a queue (distributed queue) or a group local queue, it
-<em>must also</em> provide passthrough for any incoming replication group that replicates that
-topic (even if the incoming replication connection is from the same group that this
-instance belongs to). The reason for this is simple: AMPS must ensure that messages
-for a replicated queue, including acknowledgments and transfer messages, are able
-to reach every instance that hosts the queue if possible, even if a network connection
-fails or an instance goes offline. Therefore, this instance must pass through messages
-received from other instances that affect the queue.</p>
-</div>
-<div class="section" id="guarantees-on-ordering">
-<h2>Guarantees on Ordering<a class="headerlink" href="#guarantees-on-ordering" title="Permalink to this headline">¶</a></h2>
-<p>For each publisher, on a single topic, AMPS is guaranteed to deliver
-messages to subscribers in the same order that the messages were
-published by the original publisher. This guarantee holds true
-regardless of how many publishers or how many subscribers are connected
-to AMPS at any one time.</p>
-<p>For each instance, AMPS is guaranteed to deliver messages in the order
-in which the messages were received by the instance, regardless of
-whether a message is received directly from a publisher or indirectly
-via replication. The message order for the instance is recorded in the
-transaction log, and is guaranteed to remain consistent across server
-restarts.</p>
-<p>These guarantees mean that subscribers will not spend unnecessary CPU
-cycles checking timestamps or other message content to verify which
-message is the most recent, or reordering messages during playback. This
-frees up subscriber resources to do more important work.</p>
-<p>AMPS preserves an absolute order across topics for a single subscription
-for all topics <em>except</em> views, queues, and conflated topics.
-Applications often rely on this behavior to correlate the times at which
-messages to different topics were processed by AMPS. See
-<a class="reference internal" href="pub_sub.html#pub-sub-ordering"><span class="std std-ref">Message Ordering</span></a> for more information.</p>
-</div>
-<div class="section" id="replication-security">
-<h2>Replication Security<a class="headerlink" href="#replication-security" title="Permalink to this headline">¶</a></h2>
-<p>AMPS allows authorization and entitlement to be configured on
-replication destinations. For the instance that receives connections,
-you simply configure <code class="docutils literal"><span class="pre">Authentication</span></code> and <code class="docutils literal"><span class="pre">Entitlement</span></code> for the transport
-definition for the destination, as shown below:</p>
-<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Transports&gt;</span>
-    <span class="nt">&lt;Transport&gt;</span>
-        <span class="nt">&lt;Name&gt;</span>amps-replication<span class="nt">&lt;/Name&gt;</span>
-        <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
-        <span class="nt">&lt;InetAddr&gt;</span>10005<span class="nt">&lt;/InetAddr&gt;</span>
-        <span class="c">&lt;!-- Specifies the entitlement module to use to check permissions for incoming</span>
-<span class="c">            connections. The module specified must be defined in the Modules section of the</span>
-<span class="c">            config file, or be one of the default modules provided by AMPS. This snippet</span>
-<span class="c">            uses the default module provided by AMPS for example purposes. --&gt;</span>
-        <span class="nt">&lt;Entitlement&gt;</span>
-            <span class="nt">&lt;Module&gt;</span>amps-default-entitlement-module<span class="nt">&lt;/Module&gt;</span>
-        <span class="nt">&lt;/Entitlement&gt;</span>
-        <span class="c">&lt;!-- Specifies the authentication module to use to verify identity for incoming</span>
-<span class="c">            connections. The module specified must be defined in the Modules section of the</span>
-<span class="c">            config file, or be one of the default modules provided by AMPS. This snippet</span>
-<span class="c">            uses the default module provided by AMPS for example purposes. --&gt;</span>
-        <span class="nt">&lt;Authentication&gt;</span>
-            <span class="nt">&lt;Module&gt;</span>amps-default-authentication-module<span class="nt">&lt;/Module&gt;</span>
-       <span class="nt">&lt;/Authentication&gt;</span>
-    <span class="nt">&lt;/Transport&gt;</span>
- ...
-<span class="nt">&lt;/Transports&gt;</span>
-</pre></div>
-</div>
-<p>For incoming connections, configuration is the same as for other types
-of transports.</p>
-<p>For connections from AMPS to replication destinations, you can configure
-an <code class="docutils literal"><span class="pre">Authenticator</span></code> module for the destination transport. <code class="docutils literal"><span class="pre">Authenticator</span></code>
-modules provide credentials for outgoing connections from AMPS. For
-authentication protocols that require a challenge and response, the
-<code class="docutils literal"><span class="pre">Authenticator</span></code> module handles the responses for the instance requesting
-access.</p>
-<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Replication&gt;</span>
-    <span class="nt">&lt;Destination&gt;</span>
-        <span class="nt">&lt;Topic&gt;</span>
-            <span class="nt">&lt;MessageType&gt;</span>fix<span class="nt">&lt;/MessageType&gt;</span>
-            <span class="nt">&lt;Name&gt;</span>topic<span class="nt">&lt;/Name&gt;</span>
-        <span class="nt">&lt;/Topic&gt;</span>
-        <span class="nt">&lt;Name&gt;</span>amps-1<span class="nt">&lt;/Name&gt;</span>
-        <span class="nt">&lt;SyncType&gt;</span>async<span class="nt">&lt;/SyncType&gt;</span>
-        <span class="nt">&lt;Transport&gt;</span>
-            <span class="nt">&lt;InetAddr&gt;</span>amps-1-server.example.com:10004<span class="nt">&lt;/InetAddr&gt;</span>
-            <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
-            <span class="c">&lt;!-- Specifies the authenticator module to use to provide credentials for the</span>
-<span class="c">                outgoing connection. The module specified must be defined in the Modules section</span>
-<span class="c">                of the config file, or be one of the default modules provided by AMPS. This</span>
-<span class="c">                snippet uses the default module provided by AMPS for example purposes. --&gt;</span>
-            <span class="nt">&lt;Authenticator&gt;</span>
-                <span class="nt">&lt;Module&gt;</span>amps-default-authenticator-module<span class="nt">&lt;/Module&gt;</span>
-            <span class="nt">&lt;/Authenticator&gt;</span>
-        <span class="nt">&lt;/Transport&gt;</span>
-    <span class="nt">&lt;/Destination&gt;</span>
-<span class="nt">&lt;/Replication&gt;</span>
-</pre></div>
-</div>
-</div>
-<div class="section" id="understanding-replication-message-routing">
-<h2>Understanding Replication Message Routing<a class="headerlink" href="#understanding-replication-message-routing" title="Permalink to this headline">¶</a></h2>
-<p>An instance of AMPS will replicate a message to a given <code class="docutils literal"><span class="pre">Destination</span></code> when
-all of the following conditions are met (and there is an active replication
-connection to the <code class="docutils literal"><span class="pre">Destination</span></code>):</p>
-<ol class="arabic simple">
-<li>The message must be recorded in the transaction log for this instance (that is,
-the topic that the message is published to must be recorded in the transaction
-log with the appropriate message type).</li>
-<li>The AMPS instance must be configured to replicate messages with that
-topic and message type to the <code class="docutils literal"><span class="pre">Destination</span></code>. (If a content filter
-is included in the replication configuration, the message must
-also match the content filter.)</li>
-<li>The message must <em>either</em> have been directly published to this instance, or
-if the message was received via replication, the <code class="docutils literal"><span class="pre">Destination</span></code> must specify
-a <code class="docutils literal"><span class="pre">PassThrough</span></code> rule that matches the AMPS instance that this instance
-received the message from.</li>
-<li>The message must not have previously passed through the <code class="docutils literal"><span class="pre">Destination</span></code>
-being replicated to; replication loops are not permitted.</li>
-</ol>
-<p>Each instance that receives a message evaluates the conditions above for each
-<code class="docutils literal"><span class="pre">Destination</span></code>. The same process is followed when replaying messages from
-the transaction log while resynchronizing the downstream replication
-destination.</p>
-<p>To verify that a given set of configurations replicates the appropriate
-messages, start at each instance that will receive publishes and trace the
-possible replication paths, applying these rules. If, at any time, applying
-these rules creates a situation where a message does not reach an instance
-of AMPS that is intended to receive the message, revise the rules (typically,
-by adjusting the topics replicated to a <code class="docutils literal"><span class="pre">Destination</span></code> or the
-<code class="docutils literal"><span class="pre">PassThrough</span></code> configuration for a <code class="docutils literal"><span class="pre">Destination</span></code>) until
-messages reach the intended instances regardless of route.</p>
-</div>
-<div class="section" id="maximum-downstream-destinations">
-<h2>Maximum Downstream Destinations<a class="headerlink" href="#maximum-downstream-destinations" title="Permalink to this headline">¶</a></h2>
-<p>AMPS has support for up to 64 downstream destinations
-that use synchronous acknowledgment. There is no
-explicit limit on the number of downstream
-destinations that use asynchronous (immediate)
-acknowledgment.</p>
-</div>
-<div class="section" id="replicated-queues">
-<span id="ug-replicated-queues"></span><span id="index-5"></span><h2>Replicated Queues<a class="headerlink" href="#replicated-queues" title="Permalink to this headline">¶</a></h2>
-<p>AMPS provides a unique approach to replicating queues. This approach is
-designed to offer high performance in the most common cases, while
-continuing to provide delivery model guarantees, resilience and failover
-in the event that one of the replicated instances goes offline.</p>
-<p>When a queue is replicated, AMPS replicates the <code class="docutils literal"><span class="pre">publish</span></code> commands to
-the underlying topic, the <code class="docutils literal"><span class="pre">sow_delete</span></code> commands that contain the
-acknowledgment messages, and special queue management commands that are
-internal to AMPS.</p>
-<div class="section" id="queue-message-ownership">
-<span id="ug-queue-message-ownership"></span><h3>Queue Message Ownership<a class="headerlink" href="#queue-message-ownership" title="Permalink to this headline">¶</a></h3>
-<p>To guarantee that no message is processed more than once, AMPS tracks
-ownership of the message within the network of replicated instances.</p>
-<p>For a distributed queue (that is, a queue defined with the <code class="docutils literal"><span class="pre">Queue</span></code>
-configuration element), the instance that first receives the publish
-command from a client owns the message. Although all replicated instances
-downstream record the publish command in their transaction
-logs, they do not provide the message to queue subscribers unless that
-instance owns the message.</p>
-<p>For a group local queue (that is, a queue defined with the <code class="docutils literal"><span class="pre">GroupLocalQueue</span></code>
-tag), the instance specified in the <code class="docutils literal"><span class="pre">InitialOwner</span></code> element for the queue
-owns a message when the message first enters the queue, regardless of where
-the message was originally published.</p>
-<p>Only one instance can own a message at any given time. Other instances
-can request that the current owner transfer ownership of a message.</p>
-<p>To transfer ownership, an instance that does not currently own the message
-makes a request to the current message owner. The owning instance makes an
-explicit decision to transfer ownership, and replicates the transfer
-notification to all instances to which the queue topic is replicated.</p>
-<p>The instance that owns a message will always deliver the message to a
-local subscriber if possible. This means that performance for local
-subscribers is unaffected by the number of downstream instances.
-However, this also means that if the local subscribers are keeping up
-with the message volume being published to the queue, the owning
-instance will never need to grant a transfer of ownership.</p>
-<p>A downstream instance will request ownership transfer if:</p>
-<ol class="arabic simple">
-<li>The downstream instance has subscriptions for that topic with
-available backlog, <em>and</em></li>
-<li>The amount of time since the message arrived at the instance is
-greater than the typical time between the replicated message arriving
-and the replicated acknowledgment arriving.</li>
-</ol>
-<p>Notice that this approach is intended to minimize ungranted transfer
-requests. In normal circumstances, the typical processing time reflects
-the speed at which the local processors are consuming messages at a
-steady state. Downstream instances will only request messages that have
-been seen to exceed that time, indicating that the processors are not
-keeping up with the incoming message rate.</p>
-<p>The instance that owns the message will grant ownership to a requesting
-instance if:</p>
-<ol class="arabic simple">
-<li>The request is the first request received for this message, <em>and</em></li>
-<li>There are no subscribers on the owning instance that can accept the
-message</li>
-</ol>
-<p>When the owning instance grants the request, it logs the transfer in its
-transaction log and sends the transfer of ownership to all instances
-that are receiving replicated messages for the queue. When the owning
-instance does not grant the transfer of ownership, it takes no action.</p>
-<p>Notice that your replication topology must be able to replicate
-acknowledgments to all instances that receive messages for the queue.
-Otherwise, an instance that does not receive the acknowledgments will
-not consider the messages to be processed. Replication validation can
-help to identify topologies that do not meet this requirement.</p>
-<div class="admonition tip">
-<p class="first admonition-title">Tip</p>
-<p class="last">A <em>barrier message</em> is delivered immediately when
-there are no unacknowledged messages ahead of the
-barrier message in the queue on this instance,
-<em>regardless of which instance owns the message</em>. This
-means that for a distributed queue or group local queue,
-every queue that contains the barrier message will deliver
-the barrier message when all previous messages on that
-instance have been acknowledged.</p>
-</div>
-<div class="section" id="failover-and-queue-message-ownership">
-<h4>Failover and Queue Message Ownership<a class="headerlink" href="#failover-and-queue-message-ownership" title="Permalink to this headline">¶</a></h4>
-<p>When an instance that contains a queue fails or is shut down, that
-instance is no longer able to grant ownership requests for the messages
-that it owns. By default, those messages become unavailable for
-delivery, since there is no longer a central coordination point at which
-to ensure that the messages are only delivered once.</p>
-<p>AMPS provides a way to make those messages available. Through the admin
-console, you can choose to <code class="docutils literal"><span class="pre">enable_proxied_transfer</span></code>, which allows an
-instance to act as an ownership proxy for an instance that has gone
-offline. In this mode, the local instance can assume ownership of
-messages that are owned by an offline instance.</p>
-<p><em>Use this setting with care</em>: when active, it is possible for messages to
-be delivered twice if the instance that had previously owned the message
-comes back online, or if multiple instances have proxied transfer
-enabled for the same queue.</p>
-<p>In general, you <code class="docutils literal"><span class="pre">enable_proxied_transfer</span></code> as a temporary recovery step
-while one of the instances is offline, and then disable proxied transfer
-when the instance comes back online, or when all of the messages owned
-by that instance have been processed.</p>
-</div>
-</div>
-<div class="section" id="configuration-for-queue-replication">
-<h3>Configuration for Queue Replication<a class="headerlink" href="#configuration-for-queue-replication" title="Permalink to this headline">¶</a></h3>
-<p>To provide replication for a distributed queue, AMPS requires that the
-replication configuration meet the following requirements:</p>
-<ol class="arabic">
-<li><p class="first">Provide bidirectional replication between the instances. In other
-words, if instance A replicates a queue to instance B, instance B
-must also replicate that queue to instance A.</p>
-</li>
-<li><p class="first">If the topic is a queue on one instance, it must be a queue on all
-replicated instances.</p>
-</li>
-<li><p class="first">On all replicated instances, the queue must use the same underlying
-topic definition and filters. For queues that use a regular
-expression as the topic definition, this means that the regular
-expression must be the same. For a <code class="docutils literal"><span class="pre">GroupLocalQueue</span></code>, the
-<code class="docutils literal"><span class="pre">InitialOwner</span></code> must be the same on all instances that contain
-the queue.</p>
-</li>
-<li><p class="first">The underlying topics must be replicated to all replicated instances
-(since this is where the messages for the queue are stored).</p>
-</li>
-<li><p class="first">Replicated instances must provide passthrough for instances that
-replicate queues. For example, consider the following replication
-topology: Instance A in group One replicates a queue to instance B in
-group Two. Instance B in group Two replicates the queue to instance C
-in group Three.</p>
-<p>For this configuration, instance B must provide passthrough for group
-Three to instance A, and must also provide passthrough for group One
-to instance C. The reason for this is to ensure that ownership
-transfer and acknowledgment messages can reach all instances that
-maintain a copy of the queue.</p>
-<p>Likewise, consider a topology where Instance X in GroupOne replicates
-a queue to Instance Y in GroupOne. Instance X must provide passthrough
-for GroupOne, since any incoming replication messages for the queue
-(for example, from Instance Z) that arrive at Instance X must be
-<em>guaranteed</em> to reach Instance Y. Otherwise, it would be possible for the
-queue on Instance Y to have different messages than Instance X and Instance
-Z if Instance Z does not replicate to Instance Y (or if the network
-connection between Instance Z and Instance Y fails).</p>
-</li>
-</ol>
-<p>Notice that <em>the requirements above apply only to queue topics</em>. If the
-underlying topic uses a different name than the queue topic, it is
-possible to replicate the messages from the underlying topic <em>without</em>
-replicating the queue itself. This approach can be convenient for simply
-recording and storing the messages provided to the queue on an archival
-or auditing instance. When only the underlying topic (or topics) are
-replicated, the requirements above do not apply, since AMPS does not
-provide queuing behavior for the underlying topics.</p>
-<p>A queue defined with <code class="docutils literal"><span class="pre">LocalQueue</span></code> cannot be replicated. The data from
-the underlying topics for the queue can be replicated without special
-restrictions. The queue topic itself, however, cannot be replicated.
-AMPS reports an error if any <code class="docutils literal"><span class="pre">LocalQueue</span></code> topic is replicated.</p>
-</div>
-</div>
-<div class="section" id="bootstrap-initialization-of-amps-replication">
-<span id="bootstrap-initialization"></span><h2>Bootstrap Initialization of AMPS Replication<a class="headerlink" href="#bootstrap-initialization-of-amps-replication" title="Permalink to this headline">¶</a></h2>
-<p id="index-6">AMPS offers the ability to initialize replication by recovering
-the full current set of messages in an AMPS instance from another
-instance.</p>
-<p>Bootstrap initialization can restore the messages in the
-transaction log of the source instance. Unlike replication,
-bootstrap initialization will restore messages that
-would not normally be replicated, including:</p>
-<ul>
-<li><p class="first">The full current contents of SOW topics (including messages that
-are present in the SOW, but are no longer in the transaction log).</p>
-</li>
-<li><p class="first">Messages that would not be replicated to the
-instance being bootstrapped due to protection against
-replication loops.</p>
-<p>That is, if the <code class="docutils literal"><span class="pre">AMPS-Instance-A</span></code> instance is being
-recovered, bootstrap recovery will copy messages
-that were originally published to <code class="docutils literal"><span class="pre">AMPS-Instance-A</span></code>.</p>
-<p>Replication does not return messages to the instance
-that the message was originally received from (to
-prevent loops, and because that instance is already
-known to have the message).</p>
-</li>
-</ul>
-<p>Bootstrap replication initialization uses the
-AMPS replication transport to retrieve messages from
-the source. However, the bootstrap initialization
-process itself is distinct from replication and
-happens as a part of AMPS recovery, <em>before</em> replication
-begins.</p>
-<div class="admonition caution">
-<p class="first admonition-title">Caution</p>
-<p>Since an instance must finish bootstrap
-initialization before providing any other
-service, two instances of AMPS should not
-try to bootstrap from each other in a
-situation where both transaction logs
-are empty. In this case, both instances
-will wait for the other instance, and neither
-instance will recover.</p>
-<p class="last">If two instances of AMPS will be recovery
-partners with each other, start one instance
-without a bootstrap configuration the first
-time, then add the bootstrap configuration
-on a later restart.</p>
-</div>
-<p>Bootstrap initialization only takes place when
-the AMPS instance is starting, and the
-<em>only</em> function of bootstrap initialization
-is to restore the initial state of AMPS from
-another instance. To keep the current state
-of messages synchronized between instances,
-use AMPS replication.</p>
-<div class="section" id="when-to-use-bootstrap-initialization">
-<h3>When to Use Bootstrap Initialization<a class="headerlink" href="#when-to-use-bootstrap-initialization" title="Permalink to this headline">¶</a></h3>
-<p>Bootstrap initialization is most commonly used
-for:</p>
-<ul>
-<li><p class="first"><strong>Disaster Recovery</strong> - In a situation where the
-entire state of the instance has been lost,
-bootstrap replication initialization can effectively
-recover the state of the instance, including the
-SOW topics and messages originally published to
-the instance.</p>
-</li>
-<li><p class="first"><strong>Scale-out Scenarios</strong> - When an instance of AMPS
-joins an existing set of instances that maintain
-data in SOW topics for longer than the instances
-maintain the transaction log.</p>
-</li>
-<li><p class="first"><strong>Offline Replica Scenarios</strong> - For example, bootstrap
-initialization might be a good option for periodically
-repopulating a development or reporting environment
-that periodically needs a full copy of the data in
-an instance, but does not require active message flow.</p>
-<p>In this case, the state for the instance is typically
-removed on a regular basis. The message contents
-are recovered using bootstrap initialization, but the
-upstream instance may not continue to replicate messages
-while the instance is running, since active message flow
-is not necessary.</p>
-</li>
-</ul>
-</div>
-<div class="section" id="starting-bootstrap-initialization">
-<h3>Starting Bootstrap Initialization<a class="headerlink" href="#starting-bootstrap-initialization" title="Permalink to this headline">¶</a></h3>
-<p>An instance of AMPS will begin bootstrap initialization
-when:</p>
-<ul class="simple">
-<li>The instance is configured to bootstrap the initial state.</li>
-<li>The AMPS instance does not detect persistent state
-when it starts (or AMPS detects that it was
-shut down while bootstrap was underway).</li>
-</ul>
-<p>An AMPS instance will <strong>only</strong> use bootstrap initialization when
-that instance starts with no messages in the transaction log.
-Bootstrap initialization will not overwrite or modify existing
-messages on an instance. If there are messages in the transaction
-log for the AMPS instance, the instance will not perform
-bootstrap initialization.</p>
-<p>An AMPS instance does not
-use bootstrap initialization once the instance starts. To keep
-message state consistent between two instances of AMPS while
-AMPS is running, use AMPS replication.</p>
-</div>
-<div class="section" id="configuring-bootstrap-initialization">
-<h3>Configuring Bootstrap Initialization<a class="headerlink" href="#configuring-bootstrap-initialization" title="Permalink to this headline">¶</a></h3>
-<p>To configure bootstrap initialization, the configuration on the
-instance being initialized must include:</p>
-<ul class="simple">
-<li>A replication transport (that is, a <code class="docutils literal"><span class="pre">Transport</span></code> of type <code class="docutils literal"><span class="pre">amps-replication</span></code> or <code class="docutils literal"><span class="pre">amps-replication-secure</span></code></li>
-<li>A transaction log, <em>and</em></li>
-<li>A bootstrap directive</li>
-</ul>
-<p>Most often, the instance that is the source of bootstrap
-messages will also replicate to the instance that is being
-initialized. However, this is not required: the instance being
-bootstrapped can receive replication publishes from a
-completely different instance or set of instances.</p>
-<p>The instance that will serve as the source of bootstrap
-initialization must define a replication transport, and
-must also have recorded the information that will be
-used for initialization (that is, the topics that will
-be initialized must be in the transaction log and/or
-SOW).</p>
-<p>For example, the following configuration will initialize
-the message state of the instance from the source AMPS
-instance located at <code class="docutils literal"><span class="pre">source.example.com</span></code> or, if that
-server is unavailable, at the AMPS instance located at
-<code class="docutils literal"><span class="pre">backup.example.com</span></code>. In both cases, those instances
-must have configured a replication transport listening
-on port <code class="docutils literal"><span class="pre">4100</span></code>.</p>
-<p>This instance will initialize the topics <code class="docutils literal"><span class="pre">important-topic</span></code>
-and any topic that begins with the string <code class="docutils literal"><span class="pre">audit-topic</span></code>
-of message type <code class="docutils literal"><span class="pre">json</span></code> from the source server. If either
-of these topics is recorded in the <code class="docutils literal"><span class="pre">SOW</span></code>, the current
-messages from the source instance will be copied to this
-instance of AMPS.</p>
-<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Bootstrap&gt;</span>
-  <span class="nt">&lt;Topic&gt;</span>
-    <span class="nt">&lt;Name&gt;</span>important-topic<span class="nt">&lt;/Name&gt;</span>
-    <span class="nt">&lt;MessageType&gt;</span>json<span class="nt">&lt;/MessageType&gt;</span>
-  <span class="nt">&lt;/Topic&gt;</span>
-  <span class="nt">&lt;Topic&gt;</span>
-    <span class="nt">&lt;Name&gt;</span>^audit-topic<span class="nt">&lt;/Name&gt;</span>
-    <span class="nt">&lt;MessageType&gt;</span>json<span class="nt">&lt;/MessageType&gt;</span>
-  <span class="nt">&lt;/Topic&gt;</span>
-  <span class="nt">&lt;DataType&gt;</span>sow,txlog<span class="nt">&lt;/DataType&gt;</span>
-  <span class="nt">&lt;Transport&gt;</span>
-    <span class="nt">&lt;InetAddr&gt;</span>source.example.com:4100<span class="nt">&lt;/InetAddr&gt;</span>
-    <span class="nt">&lt;InetAddr&gt;</span>backup.example.com:4100<span class="nt">&lt;/InetAddr&gt;</span>
-    <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
-  <span class="nt">&lt;/Transport&gt;</span>
-<span class="nt">&lt;/Bootstrap&gt;</span>
-</pre></div>
-</div>
-<p>This instance must also define a replication transport
-and a transaction log. If the topics specified are
-to be stored in the SOW, the instance must also
-include definitions for those topics in the
-configuration.</p>
-<p>If an instance with this configuration starts, and
-there is no message data in the transaction log,
-the instance will bootstrap initialize message
-contents as configured above.</p>
-</div>
-</div>
-<div class="section" id="replication-best-practices">
-<span id="common-replication-best-practices"></span><span id="index-7"></span><h2>Replication Best Practices<a class="headerlink" href="#replication-best-practices" title="Permalink to this headline">¶</a></h2>
-<p>For your application to work properly in an environment that uses
-AMPS replication, it is important to follow these best practices:</p>
-<ul class="simple">
-<li><em>Every client that changes the state of AMPS must have a distinct client
-name</em> - Although AMPS only enforces this requirement for an individual
-instance, if two clients with the same name are connected to two
-different instances, and both clients publish messages, delete messages,
-or acknowledge messages from a queue, the messages present on each
-instance of AMPS can become inconsistent.</li>
-<li><em>Use replication filters with caution, especially for queue topics</em> - Using
-a replication filter will create different topic contents on each instance.
-In addition, using a replication filter for a message queue topic (or the
-underlying topic for a message queue) can create different queue contents
-on different instances, and messages that are not replicated must be
-consumed from the instance where they were originally published.</li>
-<li><em>Do not manually set client sequence numbers on published messages</em> -
-The publish store classes in the AMPS client libraries manage sequence
-numbers for published messages to ensure that there is no message
-loss or duplication in a high availability environment. 60East
-recommends using those publish stores to manage sequence numbers
-rather than setting them manually. Since AMPS uses the sequence
-number to identify duplicate messages, setting sequence numbers
-manually can cause AMPS to discard messages or lead to inconsistent
-state across instances.</li>
-<li><em>Default to PassThrough for every group</em> - PassThrough for every
-group guarantees that each upstream instance will provide the
-full set of messages that it has to downstream groups. For some
-topologies, it is possible to reduce traffic to downstream
-instances by using the PassThrough configuration to avoid replicating
-messages that are guaranteed to arrive via another route (even in
-cases of network or server failure), but this should be done
-with caution.</li>
-<li><em>Do not allow a publisher or queue consumer to fail over between
-two instances that are replicating using async acknowledgment</em> - The
-<code class="docutils literal"><span class="pre">async</span></code> acknowledgment mode means that messages are acknowledged
-to a publisher before the downstream replication instance has
-acknowledged that it has received the message. Allowing a publisher
-to fail over between two instances that are using <code class="docutils literal"><span class="pre">async</span></code> acknowledgment
-runs the risk of creating inconsistent state or message loss.</li>
-</ul>
-</div>
-</div>
-          </div>
-        </div>
-      </div>
-    <div class="clearer"></div>
-  </div>
-    <div class="footer">
-      &copy;2023 60East Technologies, Inc. (version develop).
-      |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.5.3</a>
-      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
-    </div>
-  </body>
-</html>

amps-python-client 5.3.4.1__zip → 5.3.4.3__zip

amps-python-client 5.3.4.1zip → 5.3.4.3zip