# hp Reliable Transaction Router
System Manager's Manual

Previous | Contents | Index

## 2.13.1 Tuning for Journal Access in a Cluster

RTR can exhibit several different behaviors for journal locking in a cluster depending on the setting of certain environmental variables. These include RTR_JNL_RETAIN_SECS to prevent premature journal release, RTR_JNL_RELEASE_SECS to release a journal after a given period of time, RTR_JNL_RETAIN_MODE to define the level of support for journal host resignation, and RTR_JNL_PARTITION_FAILBACK to reset partition priorities from standby to a prior mode.

- RTR_JNL_RETAIN_SECS: To prevent premature journal release in an unstable network, a system requires that conditions enabling a node to resign hosting its journal persist for the length of time (in seconds) specified by this environment variable. If this variable is not specified, RTR assumes the default of 30 seconds. The effective value used by RTR is the greater of the value specified (or the default) and the greatest link-inactivity timeout for all RTR links that communicate with routers.
  To display the value of this parameter, use the
  `SHOW RTR/COUNTER=jam_jnl_retain_secs` command.
- RTR_JNL_RELEASE_SECS: Systems requesting that a cluster colleague node give up its journal persist with the request for this number of seconds. After this time period, the request will be dropped and the journal access attempt is allowed to fail. The default value assumes by RTR is three times that in use for the journal retention timer RTR_JNL_RETAIN_SECS.
- RTR_JNL_RETAIN_MODE: Defines the level of support for the journal host resignation feature. This parameter can be used to resolve a journal access conflict when an RTR backend becomes isolated from the network and blocks access to its journal by other cluster members, defeating RTR standby takeover. Valid values are:
  - 0: feature disabled
  - 1: RTR resigns journal if appropriate, then stops.
  - 2: (default) RTR does not stop after resigning the journal and can recover if the network isolation condition ends.
    To display the value of this parameter, use the
    `SHOW RTR/counter=jam_jnl_retain_mode` command, which displays one of the following values: `retain_jnl, resign_jnl_and_stop,` or `resign_jnl_and_wait.`
- RTR_JNL_PARTITION_FAILBACK: Define this to defeat the default behavior so that when an isolated node regains its connection to the network, partition instances resume in their prior mode, not in standby mode.

For more details on these environment variables, see Table 2-2.

## 2.13.2 Compression of Event and Reply Data

Transaction data can be transmitted in a compressed format, to address the needs of users who wish to reduce their network bandwidth requirements for the transfer of such data. User data passed to RTR using the `rtr_reply_to_client(), rtr_broadcast_event()` and `rtr_ext_broadcast_event()` calls may optionally be compressed before being passed to the RTRACP process for transmission to the RTR router. The event or reply data are decompressed to their original state before being presented to the receiving applications.

Compression and decompression occur in the address space of client and server applications, so these processes will consume additional CPU resources when compression is in use. Compression is done using the open source zlib library. For further information, consult http://www.gzip.org/zlib/.

Both compression and decompression are controlled by environment variables with no method for automatic decompression of compressed data.

To ensure interoperability, all participating systems must be running a version of RTR that supports compression, and compression must be either disabled or enabled on all participating systems. Failure to observe these restrictions may cause compressed data to be incorrectly delivered to applications expecting uncompressed data.

You cannot use compression and the `msgfmt` argument of `rtr_reply_to_client(), rtr_broadcast_event()` , or `rtr_ext_broadcast_event()` simultaneously.

Compression and decompression are controlled with the following environment variables defined on participating frontends and backends as follows:

On participating frontends to control compression of client broadcasts:

> RTR_EVENT_COMPRESS_LEVEL
> RTR_EVENT_COMPRESS_THRESHOLD

On participating backends:

> RTR_EVENT_COMPRESS_LEVEL
> RTR_EVENT_COMPRESS_THRESHOLD
> RTR_REPLY_COMPRESS_LEVEL
> RTR_REPLY_COMPRESS_THRESHOLD

No setup is required on router nodes, or if no compression is wanted.

The EVENT_COMPRESS variables control event-data compression. They are deployed on a frontend to control compression of client broadcasts, and on a backend to control compression of server broadcasts. The LEVEL variable controls compression amount or level; valid values are integers in the range 1-9. Higher levels cause better compression, at the cost of increased CPU usage. If unspecified, the zlib default compression level is used.

The THRESHOLD variable defines the size of the largest data packet not subject to compression; anything larger is compressed. A threshold value of 0, the default, disables compression.

## 2.13.3 Flow Control Environment Variables

If an application is sending many large messages, flow control may not close the application channel soon enough which may cause the RTRACP to run out of memory.

For applications using large messages containing tens of thousands of bytes, the following environment variables are provided to adjust the flow control algorithm parameters: RTR_MAX_CHANNEL_WAITQ_LIMIT, RTR_MAX_CHANNEL_WAITQ_BYTES, and RTR_MAX_CHANNEL_FULL_COUNT. These variables are described in Table 2-2.

When the WAITQ memory quota is exceeded, the RTRACP deletes all messages in the queue and returns a status of RTR_STS_CACHEXHAU, along with a "channel has been closed" message `(rtr_mt_closed)` which indicates that all messages were discarded in the application channel's queue.

Sizing for Channels and Sockets

Facilities do not require channels but networks links do. On OpenVMS, the number of channels is defined by the parameter CHANNELCNT that can be updated by changing MODPARAMS.DAT and running AUTOGEN. UNIX uses sockets, not channels.

To compute the number of channels and the maximum process count, use the rules in Table 2-1.

Table 2-1 Rules for CHANNELCNT and MAXPROCCNT
To compute: | For Parameter: | Parameter value must be greater than:
--- | --- | ---
Channel count | CHANNELCNT | (30 + (number-of-processes * 2) + (number-of-links))
Maximum process count | MAXPROCCNT | (number-of-processes + 50)

Table 2-2 summarizes environment variables used by RTR.

Table 2-2 RTR Environment Variables
Environment Variable | Description
--- | ---
System Logicals and Directories: |
SYS$NODE | Set by DECnet if configured; used to detect presence of DECnet.
RTR_DIRECTORY | Define to run RTR as a Service on Windows NT.
RTR$DUMP_DIRECTORY | Directory for `rtr_error.log` and `rtr.dmp`
RTR_DUMP_DIRECTORY | Synonym for RTR$DUMP_DIRECTORY.
RTRHELP | Specifies an alternate location for the RTR online help file ( `rtr.hlb` ).
Notification Variables: |
FE_NOTIFICATION_MSG_COUNT | Defines how many times a frontend will disconnect the current router and attempt to reconnect with the preferred routers. The default is 3; that is, after three attempts the frontend remains connected to the current router and no longer bounces between routers. Minimum: 3, maximum: 100.
FE_NOTIFICATION_MSG_SECS | Defines the interval within which a frontend can change routers three times, in seconds. The default is 600 seconds, or 10 minutes (10*60). With the default, if a frontend fails three times in 10 minutes, it will stop changing routers. The minimum is 60 seconds, and the maximum, 12*60*60.
FE_NOTIFICATION_RESUME_SECS | Defines the interval for a frontend to remain connected to the current router, after three failed attempts to use the preferred routers list. Once the interval is over, the frontend will again try to connect to the preferred routers in the list. The default is 4*60*60 (4 hours); the minimum is 2 hours, and the maximum, 12 hours.
Best Response Time Variable: |
RTR_GOAL_RESPONSE | To ensure best throughput, RTR queues data that is to be sent from an application to the RTRACP and sends it in one operation. The send is initiated when RTR is about to wait for something to occur. In a threaded application that has made an RTR API call and is waiting for something outside RTR to occur, this could lengthen response time. To change RTR's performance goal from best throughput to best response time, define the application process environment variable RTR_GOAL_RESPONSE. Defining this variable can impact both throughput and application CPU usage.
Journaling Variables: |
RTR_JNL_PARTITION_FAILBACK | Resets partition priorities from standby to a prior mode.
RTR_JNL_RELEASE_SECS | Releases the journal after a given period of time.
RTR_JNL_RETAIN_MODE | Defines the level of support for journal host resignation.
RTR_JNL_RETAIN_SECS | Prevents premature journal release.
Flow Control Variables: |
RTR_MAX_CHANNEL_FULL_COUNT | Defines for each channel the maximum number of attempts the RTRACP allows for a message to be placed in a full queue. The default value is 2000. This number may be set to a maximum of RTR_MAX_CHANNEL_WAITQ_LIMIT/64000, where 64000 is the maximum number of bytes allowed in an application message.
RTR_MAX_CHANNEL_WAITQ_BYTES | Defines for each application channel the maximum queue size in bytes for a pending transaction or set of broadcasts. The default value is 100,000 bytes. You can set the RTR_MAX_CHANNEL_WAITQ_BYTES variable somewhat larger than the total amount of data that can possibly occur in one transaction or one set of broadcasts. This value might be a few million bytes for a typical large message application. This variable must be set to a value less then RTR_MAX_CHANNEL_WAITQ_LIMIT when RTR_MAX_CHANNEL_WAITQ_LIMIT is enabled (set greater than -1).
RTR_MAX_CHANNEL_WAITQ_LIMIT | Defines for each channel the maximum amount of RTRACP WAITQ memory (in bytes) allowed. The default value is -1, which means there is no limit. This value may set to several million bytes. Set the RTR_MAX_CHANNEL_WAITQ_LIMIT value to an amount of RTRACP WAITQ memory that you can afford for one channel, considerably less than your virtual memory and heap quotas. If the value is -1, both RTR_MAX_CHANNEL_WAITQ_BYTES and RTR_MAX_CHANNEL_FULL_COUNT apply. If the value is greater than -1, only RTR_MAX_CHANNEL_FULL_COUNT applies.
Compression variables: |
RTR_EVENT_COMPRESS_LEVEL | Enables unconditional compression and decompression of event data.
RTR_EVENT_COMPRESS_THRESHOLD | Enables unconditional compression and decompression of reply data.
RTR_REPLY_COMPRESS_LEVEL | Enables unconditional compression and decompression of reply data in levels from 1 to 9 (9=highest level of compression).
RTR_REPLY_COMPRESS_THRESHOLD | Defines the size of the largest data packet not subject to compression; anything larger is compressed. A threshold of 0, the default, disables compression.
Networking Variables: |
RTR_PREF_PROT | Default is RTR_DNA_FIRST for OpenVMS nodes with DECnet; RTR_TCP_FIRST for other platforms. Other possible values are RTR_DNA_ONLY and RTR_TCP_ONLY.
RTR_DNA_PREFIX RTR_TCP_PREFIX RTR_TUNNEL_PREFIX | These command interfaces allow link names to be prefixed to indicate special treatment, e.g. `tcp` . If a prefixed name conflicts with a real node in the target environment, the value of the prefix string can be changed using these environment variables.

## 2.13.4 Network Transports

RTR supports multiple network transports with a default behavior.

If an attempt to create a network connection to a remote node fails, RTR retries the connection attempt using an alternate transport protocol if one is available. The order in which the supported transport protocols are used depends on the host operating system.

- OpenVMS - first DECnet then TCP/IP
- All other platforms - first TCP/IP, then DECnet if available

If a connection attempt fails on all available protocols, it is retried at a later time starting again with the first transport protocol.

If an established link fails, RTR automatically initiates a reconnection of the link, starting with the first transport protocol for the platform, regardless of the transport employed when the link failed.

For information on dual-rail and multihome environments, see Section 2.13.4.4.

### 2.13.4.1 Specifying the Link Transport Protocol

It is possible to override the protocol failover mechanism by specifying the transport protocol to be employed for a link by naming links to include a transport selecting prefix. Prefixing names of nodes with `tcp.` and `dna.` specifies TCP/IP or DECnet as the required transports respectively. These prefixes cause the local node to employ only the specified transport protocol when attempting a connection on the link to which the prefix has been applied. Using a protocol prefix on one node does not prevent a remote node from connecting using some other transport.

For example, to specify the facility FAX1 which uses only the DECnet transport, two routers (DNET1 and DNET2), two backends (SRV1 and SRV2) and many frontends, use the following command:

    RTR> create facility FAX1 /frontend=(dna.FE1,dna.FE2,dna.FE3 ....)
        /router=(dna.DNET1,dna.DNET2)
        /backend=(dna.SRV1,dna.SRV2)

Creating a facility that uses only TCP/IP would use a command like this:

    RTR> create facility FINANCE
        /frontend=(tcp.client1,tcp.client2,tcp.client7 ....)
        /router=(tcp.routr1,tcp.routr2)
        /backend=(tcp.srv1,tcp.srv2)

### 2.13.4.2 Using RTR with DHCP and Internet Tunnels

When using RTR with Dynamic Host Configuration Protocol (DHCP) or an internet tunnel, a node name may not be fully known; special naming techniques are provided for these conditions.

Anonymous Clients

RTR allows the use of wildcards when specifying the frontends from which a router is permitted to accept connections (that is, in the facility definition on the router). Valid wildcard characters are asterisk (*), percent sign (%), and question mark (?). Using a wildcard character at facility configuration time will result in the creation of a template link.

When operating RTR in conjunction with internet tunnels, a client system outside of the corporate firewall uses tunnel software to obtain a secure channel from the Internet to inside the corporate domain. The tunnel client is assigned an address by the tunnel server from a pool when the tunnel software starts up.

When an RTR router receives a connection request from RTR running on this client, the source address of the connection is the address assigned by the tunnel server. There is no longer a fixed relationship between the client and its address. You can configure the router to accept such a connection. Use wildcards to define the frontend nodes with all the possible addresses that the tunnel server can assign to tunnel clients, for example:

           RTR> create facility . . ./frontend=*.pool.places.dec.com

This command enables all nodes connecting through the tunnel to connect as frontends. The anonymous client feature may also be used with frontends that are using DHCP for TCP/IP address assignment.

Using the Tunnel Prefix

By using the node name prefix "tunnel.", it is possible to configure RTR to accept a network connection from a particular remote node even if it is connecting through an internet tunnel using an unknown pseudoadapter address. This method allows stricter access control than the anonymous client feature where wildcards may be used when specifying a remote node name. For example, on the router node behind a firewall, the facility definition could include:

    RTR> create facility . . ./router=router.rtr.dec.com -
        /frontend=tunnel.client.rtr.dec.com

The definition on the frontend could be:

    RTR> create facility /router=router.rtr.dec.com -
        /frontend=client.rtr.dec.com

Troubleshooting Tunnel and Wildcard Connections

To assist in diagnosing connect-acceptance problems, use the monitor picture ACCFAIL. This picture displays the recent history of those links from which the local node has refused to accept connections. It also displays the failed link name as provided by the network transport, and can assist in rapidly identifying any problems.

TCP Services File

RTR uses the TCP/IP port number 46000 for the network communication daemon `rtr rtrd` . Refer to the Reliable Transaction Router Installation Guide for how to reserve this port for UNIX systems.

### 2.13.4.3 Network Protocol Selection

To specify the network protocol, you can prefix a node name with a .dna (DECnet) or .tcp (TCP/IP) string. Using the .dna prefix assumes that the default network transport is TCP/IP. The default network transport can be changed to DECnet with the environment variable RTR_PREF_PROT. The applicable environment variables are:

    set RTR_PREF_PROT=RTR_TCP_FIRST
    set RTR_PREF_PROT=RTR_TCP_ONLY
    set RTR_PREF_PROT=RTR_DNA_FIRST
    set RTR_PREF_PROT=RTR_DNA_ONLY

These statements set the choice of network transport to TCP/IP with fallback to DECnet, TCP/IP only, DECnet with fallback to TCP/IP or DECnet only.

Network Protocol Selection on OpenVMS

The default network transport protocol for RTR on OpenVMS is DECnet. You may change the default to TCP/IP by removing this line from `RTR$STARTUP.COM` :

    $ DEFINE/SYSTEM RTR_PREF_PROT RTR_DNA_FIRST

If you are using TCP/IP, you must use the node name prefix `dna.` if you want DECnet transport to be used.

If you are using DECnet as the default, you must use the node name prefix `tcp.` to connect to other nodes using TCP/IP transport.

If the value of the logical RTR_PREF_PROT is changed, the new value takes effect only after RTR has been restarted.

Reliable Transaction Router Version 4.2 for OpenVMS can use either TCP/IP Services for OpenVMS or TCPware Version 5.1 as the TCP/IP transport layer. For more details on modifying RTR$STARTUP.COM on OpenVMS, see the full OpenVMS installation instructions in the Reliable Transaction Router Installation Guide.

Previous | Next | Contents | Index