create route

Designates the route to use for a connection from the current Replication Server to a remote Replication Server.

Syntax

create route to <dest_replication_server >{
 set next site [to] <thru_replication_server > |
 with primary at <dataserver.database> |
 [set username [to] <user>]
 [set password [to] <passwd>]
 [set <route_param> to '<value>' 
 [set <route_param> to '<value>']... ]
 [set <security_param> to '<value>' 
 [set <security_param> to '<value>']... ]}

Parameters

dest_replication_server

The destination Replication Server.

thru_replication_server

The intermediate Replication Server through which to pass messages for the destination Replication Server. Specify this when creating an indirect route.

with primary

Specifies the connection from the primary database that you want to create a dedicated route for.

Note You can only create a dedicated route between two Replication Servers if there is a direct route between the two Replication Servers. You cannot create a dedicated route if there is only an indirect route between the Replication Servers.

user

The Replication Server login name to use to log in to the destination Replication Server. This is the login name used by the RSI user thread. If no user name is entered, Replication Server uses the principal user name entered with the -S flag when Replication Server was started.

passwd

The password to use with the login name. If no password is entered, Replication Server uses a null value.

route_param

a parameter that affects routes. See “Configuration Parameters Affecting Routes” table for a list of parameters and values.

value

a character string containing a value for a parameter.

security_param

Specifies the name of a security parameter. Refer to Parameters affecting network-based security for a list and description of security parameters that can be set with create route.

Table 1: Parameters Affecting Network-Based Security
`<security_param>`	`<Value>`
msg_confidentiality	Indicates whether Replication Server sends and receives encrypted data. If set to “required,” outgoing data is encrypted. If set to “not required,” Replication Server accepts incoming data that is encrypted or not encrypted. Default: not_required
msg_integrity	Indicates whether data is checked for tampering. Default: not_required
msg_origin_check	Indicates whether the source of data should be verified. Default: not_required
msg_replay_detection	Indicates whether data should be checked to make sure it has not been read or intercepted. Default: not_required
msg_sequence_check	Indicates whether data should be checked for interception. Default: not_required
mutual_auth	Requires remote server to provide proof of identify before a connection is established. Default: not_required
security_mechanism	The name of the third-party security mechanism enabled for the pathway. Default: first mechanism listed in the SECURITY section of libtcl.cfg
unified_login	Indicates how Replication Server seeks to log in to remote data servers and accepts incoming logins. The values are: required – always seeks to log in to remote server with a credential. not_required – always seeks to log in to remote server with a password. Default: not_required
use_security_services	Tells Replication Server whether to use security services. If use_security_services is “off,” no security features take effect. Note This parameter can only be set by configure replication server.

Examples

Example 1

Entered at the TOKYO_RS Replication Server, this command creates a direct route from TOKYO_RS to the SYDNEY_RS Replication Server. TOKYO_RS can log in to SYDNEY_RS over this route, using the login name “sydney_rsi” with the password “sydney_rsi_ps:”

create route to SYDNEY_RS
 set username sydney_rsi
 set password sydney_rsi_ps

Example 2

Entered at TOKYO_RS, this command creates an indirect route from TOKYO_RS to SYDNEY_RS, through the intermediate Replication Server, MANILA_RS. Direct routes must already exist from TOKYO_RS to MANILA_RS and from MANILA_RS to SYDNEY_RS:

create route to SYDNEY_RS
 set next site MANILA_RS

Example 3

This command creates a direct route similar to that in the first example. However, if network-based security is enabled, TOKYO_RS must log in to SYDNEY_RS with a credential:

create route to SYDNEY_RS
 set unified_login 'required'

Example 4

To create a dedicated route between the RS_NY primary Replication Server and the RS_LON replicate Replication Server for the NY_DS.pdb1 primary connection, at RS_NY enter:

create route to RS_LON
 with primary at NY_DS.pdb1
 go

After you create a dedicated route for a specific connection, all transactions from the connection to the destination Replication Server follow the dedicated route.

Usage

Use create route to create a direct or indirect route from the current Replication Server to a remote Replication Server.
Before creating a route, you should have determined your overall routing scheme. See the Replication Server Administration Guide Volume 1 for information on creating and managing routes.
Replication Server does not support routing schemes where routes diverge from the same source Replication Server, then converge at the same intermediate or destination Replication Server.
Replication Server distributes information about the new route to qualifying sites through the replication system. The changes do not appear immediately at all such sites because of normal replication system lag time.
If Replication Server is configured with Embedded RSSD (ERSSD), you can create a route as long as both Replication Servers are 15.0 or higher. If the route being created is the first route originating from the current site, log transfer will be started and a Replication Agent will be started automatically:

To change the Replication Agent’s name, enter:
```
configure replication server 
set erssd_ra to '<value>'
```

Direct Routes

Specify an RSI user name and password and omit the next site clause from create route to set up a direct route from the current Replication Server to the destination Replication Server.
Before you create a direct route, create login names and passwords in the destination Replication Server. You can use rs_init to set these up; the default user name is “<RS_name>_rsi” and the default password is “<RS_name>_rsi_ps.”

If a route is created with a user and password that do not exist at the destination Replication Server, add or change the user and password at that destination.

Indirect Routes

Include the next site clause in create route to set up an indirect route for Replication Server messages. For example, messages originating in New York and destined for all European sites can be routed through a London site, along an indirect route. Using indirect routes decreases the volume of messages passed through a portion of the route.
Before you create an indirect route, you must first create a direct route from the source Replication Server to the intermediate Replication Server, and from the intermediate Replication Server to the destination Replication Server.
A route can have any number of intermediate Replication Servers. However, because each additional intermediate Replication Server increases the lag time between the primary and replicate sites, you should limit the number of intermediate sites.

Dedicated Routes

You can create a dedicated route only if:

A shared route exists from the primary Replication Server to the destination Replication Server, and the shared route is a direct route. You cannot create a dedicated route if there is only an indirect route between the Replication Servers.
The shared route is valid and not suspended.
The route version of the shared route is 1570 or later.

See Replication Server Administration Guide Volume 2 > Performance Tuning > Multi-Path Replication > Dedicated Routes.

Routes and RSSD Tables

The RSI user name and password you specify when you create a direct route is added to the <rs_users> system table in the RSSD of the destination Replication Server. The user name and password are also added to the <rs_maintusers> system table in the RSSD of the source Replication Server.
When you create a route, the source Replication Server sends the destination Replication Server the login name and password of the source RSSD’s primary user. The destination Replication Server uses this login to create subscriptions to some of the RSSD system tables at the source Replication Server. This primary user login name is usually named “<source_RSSD_name>_prim,” and is stored in the <rs_users> system table at the destination Replication Server.

Network-Based Security Parameters

Both ends of a route must use compatible Security Control Layer (SCL) drivers with the same security mechanisms and security features. It is the replication system administrator’s responsibility to choose and set security features for each server. The Replication Server does not query the security features of remote servers before it attempts to establish a connection.
create route specifies network-based security settings that affect how the current Replication Server logs in to the target Replication Server and how secure message transmission is accomplished.
If unified_login is set to “required,” only the “sa” user can log in to the Replication Server without a credential. If the security mechanism should fail, the “sa” user can then log in to Replication Server with a password and disable unified_login.
A Replication Server can have more than one security mechanism; each supported mechanism is listed in the libtcl.cfg file under SECURITY.
Message encryption is a costly process with severe performance penalties. In most instances, it may be wise to set msg_confidentiality “on” only for certain routes. Alternatively, choose a less costly security feature, such as msg_integrity.

Permissions

create route requires “sa” permission.