Changes the attributes of a route from the current Replication Server to a remote Replication Server.
Syntax
alter route to dest_replication_server {
set next site [to] thru_replication_server |
set username [to] 'user' set password [to] 'passwd' |
set password [to] 'passwd' |
set route_param [to] 'value' |
set security_param [to] 'value' |
set security_services [to] 'default'}
Parameters
- dest_replication_server – The name of the destination Replication Server whose route you are altering.
- thru_replication_server – The name of an intermediate Replication Server through which messages for the destination Replication Server will be passed.
- user – The login name to use for the route.
- passwd – The password to use with the login name.
- route_param – A parameter that affects routes. Refer to Configuration parameters affecting routes for a list of parameters and values.
- value – A setting for route_param.
It is a character string.
Configuration Parameters Affecting Routes route_param
Value
disk_affinity
Specifies an allocation hint for assigning the next partition. Enter the logical name of the partition to which the next segment should be allocated when the current partition is full.
Default: off
rsi_batch_size
The number of bytes sent to another Replication Server before a truncation point is requested.
Default: 256KB
Minimum: 1KB
Maximum: 128MB
rsi_fadeout_time
The number of seconds of idle time before Replication Server closes a connection with a destination Replication Server.
Default: -1 (specifies that Replication Server will not close the connection)
rsi_packet_size
Packet size, in bytes, for communications with other Replication Servers. The range is 1024 to 16384 bytes.
Default: 4096 bytes
rsi_sync_interval
The number of seconds between RSI synchronization inquiry messages. The Replication Server uses these messages to synchronize the RSI outbound queue with destination Replication Servers. Values must be greater than 0.
Default: 60 seconds
rsi_xact_with_large_msg
Specifies route behavior if a large message is encountered. This parameter is applicable only to direct routes where the site version at the replicate site is 12.1 or earlier. Values are “skip” and “shutdown.”
Default: shutdown
save_interval
The number of minutes that the Replication Server saves messages after they have been successfully passed to the destination Replication Server. See the Replication Server Administration Guide Volume 2 for details.
Default: 0 minutes
- security_param – specifies the name of a security parameter. For a list and description of security parameters that can be set with alter route, refer to Configuration parameters affecting routes.
- set security_services [to] 'default' – resets all network-based security features for the connection to match the global settings of your Replication Server.
Examples
- Example 1 – In examples 1 and 2, direct routes exist from the
Tokyo Replication Server (TOKYO_RS) to the San Francisco
Replication Server (SF_RS) and to the Sydney Replication
Server (SYDNEY_RS). The following commands change one direct
route into an indirect route, so that TOKYO_RS passes messages
destined for SYDNEY_RS through SF_RS.
Entered at SF_RS, this command creates a direct route to SYDNEY_RS that will be used by the new indirect route:
create route to SYDNEY_RS set username SYDNEY_rsi_user set password SYDNEY_rsi_passwd
- Example 2 – Entered at TOKYO_RS, this command changes
the direct route from TOKYO_RS to SYDNEY_RS to
an indirect route, specifying SF_RS as an intermediate
Replication Server:
alter route to SYDNEY_RS set next site SF_RS
This figure shows the routes before and after changing the routing scheme.
Examples 3 and 4 change the routing so that TOKYO_RS sends messages directly to SYDNEY_RS again, instead of passing them through SF_RS.
- Example 3 – Entered at TOKYO_RS, this command changes
the route from TOKYO_RS to SYDNEY_RS from an indirect
route to a direct route:
alter route to SYDNEY_RS set username SYDNEY_rsi set password SYDNEY_rsi_passwd
- Example 4 – Entered at SF_RS, this command removes the
direct route from SF_RS to SYDNEY_RS:
drop route to SYDNEY_RS
Together, the commands in examples 3 and 4 cancel the effects of examples 1 and 2. This figure shows the routes after the second set of commands is entered.
In example 5, direct routes exist from TOKYO_RS to SYDNEY_RS and from SYDNEY_RS to SF_RS, and an indirect route exists from TOKYO_RS to SF_RS, through SYDNEY_RS. This example changes this routing scheme so that TOKYO_RS passes messages destined for SF_RS through a different Replication Server, LA_RS in Los Angeles.
- Example 5 – Entered at TOKYO_RS, this command changes
the intermediate Replication Server for the indirect route to LA_RS
instead of SYDNEY_RS.
alter route to SF_RS set next site LA_RS
Before the route can be altered, direct routes must have been created from TOKYO_RS to LA_RS and from LA_RS to SF_RS.
This fugure shows the routes before and after the necessary commands have been entered. (Direct routes to and from SYDNEY_DS are not shown because you may have dropped them.)
- Example 6 – Entered at TOKYO_RS, this command changes
the password for the direct route from TOKYO_RS to LA_RS.
The new password is “LApass.”
alter route to LA_RS set password LApass
Before you change the password for the direct route, you must suspend the route using suspend route.
- Example 7 – Sets the security service to DCE for the route to
LA_RS:
suspend route to LA_RS alter route to LA_RS set security_mechanism to 'dce' resume route to LA_RS
Usage
- Use alter route to change:
A direct route to an indirect route.
An indirect route to a direct route.
The next intermediate site in an existing route.
The password for the RSI user for an existing direct route.
A route configuration parameter.
A network-based security parameter.
For an overview of routes, see the Replication Server Administration Guide Volume 1.
Execute alter route at the Replication Server that is the source for a direct route.
Use set next site thru_replication_server when you are changing a direct route into an indirect route, or when you are changing the intermediate site in an indirect route.
If you are changing a direct route to an indirect route, you must first create direct routes from the source site to the intermediate site, and from the intermediate site to the destination site. Do this with create route.
If you are changing the intermediate site in an indirect route, you must first create direct routes from the new intermediate site to the destination site, and from the new intermediate site to the destination site. Do this with create route.
An indirect route may have one or more intermediate Replication Servers. For example, an indirect route from A_RS to D_RS may pass through intermediate sites B_RS and C_RS.
To change an indirect route to a direct route, use alter route without the set next site clause, specifying the login name and password to use at the destination Replication Server. For example, an indirect route from A_RS->B_RS->C_RS changes to a direct route A_RS->C_RS.
To exchange one intermediate site for the next intermediate site, execute alter route with the set next site clause. For example, an indirect route A_RS->B_RS->C_RS->D_RS changes to A_RS->C_RS->D_RS.
You can set route parameters using the configure route or alter route parameter.
Use suspend route to suspend activity on the route before altering it.
Set Password and Username
Use set username user and set password passwd only when you are changing an indirect route to a direct route. You cannot change the user name or password for indirect routes; attempting to do so changes the indirect route to a direct route.
Use set password passwd only when you are changing the password for a direct route. Before you change the password for a direct route, use suspend route.
Route Parameters
Setting a save interval allows the system to tolerate partition or stable queue failures at the destination Replication Server. Backlogged messages are sent to the destination Replication Server during recovery with the rebuild queues command.
See the Replication Server Administration Guide Volume 2 for detailed information about the save interval and stable queue recovery.
Sybase recommends that you leave the rsi_batch_size, rsi_fadeout_time, rsi_packet_size, and rsi_sync_interval parameters at their default values to optimize performance.
You must suspend the connection before altering a route parameter with alter route. After executing the alter route command, you must resume the route for the change to take effect.
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 attempting to establish a connection. Connections will fail if security features at both ends of the route are not compatible.
alter route alters network-based security settings for an outgoing connection from Replication Server to a target Replication Server. Security parameters set by alter route override default values set by configure replication server.
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 is wise to set msg_confidentiality “on” only for certain connections. Alternatively, choose a less costly security feature, such as msg_integrity.
You must suspend the connection before altering a security parameter with alter route. After you execute alter route, resume the route for the change to take effect.
Quiesce the replication system. For more detailed information, refer to the Replication Server Troubleshooting Guide.
Suspend log transfer with suspend log transfer at each Replication Server that manages a database with a RepAgent.
Execute the alter route command at the source Replication Server. You may alter as many routes as necessary.
Resume RepAgent connections to each RSSD and user database using resume log transfer.
See the Replication Server Administration Guide Volume 1 for complete procedures for altering routes.