Remote Site Definition

Each site involved in cross-site replication considers the other site to be the remote site. Before cross-site replication begins, each site must define the remote site from their own perspective.

Use the following as-admin command to define the remote site: 

create | define site <string> [router_discovery <string>] [suspend <boolean>]

Using the create site command, specify the name of the other site involved in cross-site replication from the perspective of the site you are actively configuring. To know more about using the create site command, see create site.

Using The router_discovery Setting

The cross-site replication feature is designed for active-passive replication where the primary site is considered the active site and the DR site is considered the passive site. The router_discovery setting must be used when you are defining the remote site on the primary site. The router_discovery setting specifies the listen URLs of each as-router running on the remote site. If a router_discovery setting is not provided while defining the remote site on the primary site, the messages do not get routed to the DR site.

Important: Since active-active replication is not supported, to prevent accidently trying to replicate data from the remote site to the primary site, do not specify the router_discovery setting while defining the remote site on the DR site itself. However, writes to the DR site should never be allowed unless the primary site has gone down and you have failed over to the DR site. Reads on the DR site are allowed.

Using the suspend Setting

The suspend setting is an optional setting that acts as a toggle. This setting indicates whether or not to suspend the messages being routed to the remote site being defined. By default, the routing of messages begins immediately. Depending on how your application initially loads its data, or whether you are running in a fail over state, you may want to consider defining your remote site with routing initially suspended. You can choose to suspend routing of messages to the remote site being defined and have the messages saved to the internal Pending Actions Space until the remote site is manually resumed.

Using the suspend setting can be especially useful to synchronize data from your DR site back to your primary site, if you need to temporarily take down your primary site and use your DR site as your main site until your primary site comes back online. To fail over to your DR site and retain any new data updates for later synchronizing back to your primary site, on your DR site update the remote site definition (for your primary site) as follows before switching your clients over to using the DR site:
  1. Set the router_discovery setting to contain the listen URLs of the as-routers running on the primary site.
  2. Set thesuspend setting to true.
When clients start using the DR site as the main site, any PUT or TAKE operations and transactions are stored internally on the DR site. When the primary site is brought back online:
  1. Prevent clients from making any changes to the DR site.
  2. On the primary site, suspend the DR site.
  3. On the DR site, resume the primary site.
Resuming the primary site from the DR site causes the DR site to synchronize the saved operations back to the primary site. Once the synchronization is complete do the following:
  1. On the DR site, suspend the primary site (or remove the 'router_discovery' setting of the primary site.
  2. On the primary site, resume the DR site.
  3. Switch clients back to using the primary site.
Note: Prior to using this procedure, you must ensure that you have adequate memory on your seeders to store the operations waiting to be synchronized back to the primary site. This procedure is intended for scenarios where the primary site is down for short periods only. You should always have a backup procedure in place for synchronizing data between sites using your persisted data stores or by some other means, if not using persistence.

Example of Suspended Routing

Consider the ActiveSpaces example, ASPersistence, which loads data into ActiveSpaces when it is first started. To initialize your primary site for cross-site replication with shared-all persistence, both the as-router executable and the ASPersistence example must be started on the primary site before you have initialized your remote site. Now, you have the following scenario:
  • the remote site is not yet running and waiting for connections from the local site
  • the ASPersistence example has started and initially loads data into the space on your primary site

In such a scenario, the cross-site messages to your remote site do not succeed and are lost as a connection has not yet been established to your remote site.

If you intended for the data that was initially loaded to be replicated to your remote site, you have two options:
  • Ensure the remote site is up and running before starting the primary site.
  • When creating a remote site definition on your primary site, specify suspend to be true. This causes the initially loaded data from the ASPersistence example to be stored until sending to the remote site has been resumed.
Using option 2 implies that on the primary site you have started the as-router executable and created your remote site definition in suspended mode prior to starting the ASPersistence example (or any other application which stores data that you expect to be replicated across sites). When a remote site definition is created in the suspended mode, the cross-site routing messages are queued up until the site is later resumed. When a site is resumed, any queued messages are then automatically sent to the site.

Remote Site Definition - Alternative

An alternative to starting as-admin and creating a remote site definition using the create site command is to use the -input command line option of the as-router executable. Using the -input option you can specify the path and file name of a file which contains as-admin commands. These commands are executed by as-router after it finishes its initialization. So, if DRSiteDefintion.txt contains the as-admin command to define your remote site, you can specify -input "DRSiteDefintion.txt" as an option when starting the as-router executable.

Note: If starting more than one as-router executable from a script which specifies the -input option, only the first router started creates the remote site definition. For subsequent executions/calls of as-router, an error is returned as the DR site is already defined by the first execution of as-router. The as-router executables ignore errors returned from running the as-admin commands and continues to run as usual.