# hp Reliable Transaction Router
System Manager's Manual

Previous | Contents | Index

# B.2 Server Security

RTR performs both client and user verification.

## B.2.1 User Authentication

Note In order to perform user authentication on Windows 98 systems, you must first enable User-level access control; follow the path `Control Panel/Network/Access Control` and select `User-level access control` .

The HTTP server client will request user credentials, as shown in Figure 1-2.

Enter a username and password for an account for which the RTR HTTP has been enabled. Windows users may enter the username in the format `domain-name\user-name` .

To reduce the overhead of accessing the host system user authorization facilities, the server caches user credentials for a period of 90 seconds. During this time it will not revalidate user credentials against the operating system. If you change your password, wait 90 seconds before submitting it to the RTR server.

In addition to validating the supplied credentials, the server ensures that all HTTP requests are received by a command server running under the validated username. Username/password validation errors are logged to the RTR log file.

## B.2.2 User Credentials Caching

The RTR web server usually caches valid client credentials to avoid the overhead of validating each access with the operating system. Since only one set of credentials is cached, users who present different sets of credentials (for example, from different browser sessions using different Windows NT domains) will experience unexpected authorization failures. To turn off client credential caching, set the following environment variable: RTR_PASSWORD_CACHE_DISABLE. After a username/password combination has been entered, it is cached until you close your browser. To log in as a different user, close your browser and then reopen it.

## B.2.3 Break-in Detection and Evasion

The server attempts to detect a password probing attempt by monitoring the rate of user authentication errors. This is achieved by counting the errors that occur in a time window. This count is maintained for each connecting client node. If the count exceeds a threshold, the server refuses to accept subsequent connections from the client node concerned for a certain time interval. Errors that remain at the end of the counting window are forgiven, and a new window and count are started. The following table shows the default times and counts and the names of environment variables that may be used to specify customized values.

Description | Environment Variable | Default Value
--- | --- | ---
Counting window period | RTR_LGI_WINDOW | 300 seconds
Max. number of user authentications errors tolerated in window | RTR_LGI_BRK_LIM | 5
Time during which server refuses connections from evaded client | RTR_LGI_HID_TIM | 300 seconds

# Appendix C
RTR XA Support

This appendix explains how RTR can be used with an X/OPEN Distributed Transaction Processing (DTP) conformant Resource Manager.

# C.1 Introduction

The X/OPEN Distributed Transaction Processing (DTP) architecture defines a standard interface that lets application programs share resources provided by resource managers. The XA interface uses the two-phase commit protocol to commit transactions, and is a system-level, bidirectional interface between the transaction manager (TM) and the resource manager (RM). In the RTR environment, RTR is the transaction manager and database software such as ORACLE8 is the resource manager.

Without XA, an RTR application must deal with replayed transactions after server recovery delivered with `rtr_mt_msg1_uncertain` ; the application has to check if the transaction has been committed to the database. With XA, the application does not need to be concerned with this problem.

The XA library is an external interface that enables a transaction manager to coordinate global transactions. These can include:

- Opening a resource manager
- Starting a transaction
- Rolling back a transaction
- Preparing and committing a transaction
- Closing a resource manager

With XA, RTR can connect directly to a resource manager such as ORACLE8.

# C.2 Invoking RTR XA Support

Starting with RTR Version 4.0, you can invoke RTR XA support in an application without modifying the RTR API. This section shows how to use and invoke RTR XA support within an ORACLE environment.

## C.2.1 Registering a Resource Manager

You must register an instance of an RM with RTR. The RM instance name will be used by RTR to identify the specific database. Refer to the ORACLE administrator's reference manual for the appropriate `open_string` and `xaswitch` name.

    RTR>  REGISTER RM db_name1_rm
        /library_path="/opt/oracle8/lib/libclntsh.so"
        /open_string="Oracle_XA+Acc=P/Scott/Tiger+db=db_name1"
        /xaswitch=xaosw

    RTR>  REGISTER RM db_name2_rm
        /library_path="/opt/oracle8/lib/libclntsh.so"
        /open_string="Oracle_XA+Acc=P/Scott/Tiger+db=db_name2"
        /xaswitch=xaosw

Note You can only register an RM on an RTR backend.

Threaded RTR When using the threaded version of RTR with Oracle, Oracle 8.1.5 is required.

## C.2.2 Associating a Resource Manager with a Facility

All resource managers that will be accessed by a facility must be specified when the facility is created. During a crash, all doubtful transactions associated with these resource managers will be processed and recovered. Once an RM is associated with a given facility, the same RM cannot be associated with another facility.

    RTR>  CREATE FACILITY facility_name/router=.../backend=...
       /resource_manager=(db_name1_rm,db_name2_rm)

## C.2.3 Binding a Resource Manager with a Partition

You must bind the specific resource manager with an RTR partition when the partition is created. This allows RTR to manage transactions accessing this partition down to the underlying RM via the XA protocol. The XA-managed attribute for the partition remains until the partition goes away.

An RM can be bound with only one partition. Once an RM is associated with a partition, the RM cannot be associated with another partition.

    <RTR > CREATE PARTITION db_name1_part/resource_manager=db_name1_rm/...
    <RTR > CREATE PARTITION db_name2_part/resource_manager=db_name2_rm/...

Note This feature is supported only in RTR Version 4.0 and later.

## C.2.4 Opening an RTR Channel

Starting with RTR Version 4.0, when a server application opens a new channel it does not have to specify the RTR_F_OPE_XA_MANAGED flag and RM name along with the RM's attributes such as `open_string` in order to invoke RTR XA service. The server application just has to specify the name of a partition that is associated with a specific RM, provided that the user specifies an RM name when creating the partition. All transactions processed through this channel will be managed by the RTR XA service. For an example of opening an RTR channel with XA, see the Reliable Transaction Router C Application Programmer's Reference Manual `rtr_open_channel` call.

# C.3 MONITOR XA

This command monitors the internal status of XA interface activities. It displays counters containing information such as the number of XA calls, call status (success or failure), and the number of read-only transactions. It provides counts for the open, close, start, end, prepare, commit, rollback, and recovery commands.

Command Syntax: MONITOR XA

# C.4 Microsoft DTC Support

RTR for Windows NT is interoperable with the Microsoft Distributed Transaction Controller (DTC). DTC is supported via the RTR XA software architecture. That is, with the XA protocol, RTR users can develop application programs to update MS SQL Server databases, MSMQ, or other Microsoft resource managers under the control of a true distributed transaction.

This is possible because RTR (as a distributed transaction manager) is able to directly communicate with MS DTC to manage a transaction or perform a recovery via the XA protocol. For each standard XA call received from RTR, MS DTC will translate it into a corresponding OLE transaction call that SQL Server or MSMQ can use to update databases.

# Appendix D
RTR Utility Messages

This appendix describes the messages that can be returned by the RTR utility.

The following table gives the meaning of the various error codes.

Code | Meaning | Description
--- | --- | ---
S | Success | The system has successfully performed your request. In some cases, the command processing continues after the message is issued.
I | Information | The system has performed your request. The message provides information about the process.
W | Warning | The command may have performed some, but not all, of your request. The message may suggest that you verify the command or the program output.
E | Error | The output or program result is incorrect, but the system may attempt to continue execution.
F | Fatal (Severe) | The system cannot continue to execute the request.

# D.1 Utility Error Messages

> %RTR-F-ABKEYW, Ambiguous qualifier or keyword - supply more characters

Explanation: Too few characters were used to truncate a keyword or qualifier name to make the keyword or qualifier name unique.

> %RTR-F-ABVERB, Ambiguous command verb - supply more characters

Explanation: Too few characters were used to truncate a command name to make the command name unique.

> %RTR-E-ACCTOOBIG, ACCESS string is too long

Explanation: The string supplied with the /ACCESS qualifier on the OPEN CHANNEL command was too long.

> %RTR-F-ACPINSRES, The RTRACP has insufficient resources

Explanation: The RTRACP was unable to perform an operation due to an unusual condition. This is most probably a resource issue, for example when the ACP cannot create an additional shared memory segment due to quota or system configuration limits. This may also occur on some platforms when an application connects to a newly restarted ACP before all applications have finished using the process counter shared memory segments belonging to a previous ACP.

The RTR log file usually contains more details.

> %RTR-E-ACPNOTVIA, RTRACP is no longer a viable entity, restart RTR

Explanation: The RTRACP process has terminated unexpectedly.

> %RTR-I-ALRDYINSTATE, Partition is already in the desired state

Explanation: Returned following an attempt to change the state of shadowing for a partition when the partition was already in the desired state.

> %RTR-E-AMBIGDISP, Ambiguous monitor file name, [A]

Explanation: The filename [A] could refer to more than one monitor file. Please supply more characters.

> %RTR-F-AMBROUNAM, Ambiguous API routine name for CALL - supply more characters

Explanation: The parameter for the CALL command is the name (or part of a name) of an RTR API routine. This allows the user to type, for example, "rtr call accept" instead of "rtr call rtr_accept_tx". This message is issued if the user has specified part of an API routine name that matches more than one routine.

> %RTR-F-BADDSKWRI, Unable to create/extend a journal file - disk write failed

Explanation: An attempt to create or extend a journal file on disk failed. Check that the disk(s) you are using for journals have sufficient free space and that you have not exceeded your quota.

> %RTR-E-BADINTLEN, Integer keys of length [A] are not supported - use 1, 2, 4 or 8

Explanation: Keys of type integer are constrained in length to one of 1, 2, 4, 8.

> %RTR-E-BADKEYLEN, Key-type string [A] of [A] ambiguous - use string, signed or unsigned

Explanation: The input string is too short to identify the required type unambiguously. Input more characters. Try string, signed, or unsigned.

> %RTR-E-BADKEYTYPE, Key-type string [A] of [A] invalid - try string, signed or unsigned

Explanation: The input key type is unrecognised. Try one of string, signed, unsigned.

> %RTR-E-BADKEYWORD, Segment [A] keyword [A] unrecognised - use type, length, offset, low_ or high_bound

Explanation: The indicated text is not a recognised keyword of the key segment syntax. Use type, length, offset, low_bound or high_bound.

> %RTR-E-BADKEYWORDL, Segment [A] keyword string [A] ambiguous - use type, length, offset, low_ or high_bound

Explanation: Insufficient characters have been entered to allow unambiguous resolution of the keyword. Enter more text. Use type, length, offset, low_bound or high_bound.

> %RTR-E-BADOP, Unable to complete operation @[A] line [A]

Explanation: Processing definition incomplete or undefined - report occurrence with supporting information on current command to RTR Engineering.

> %RTR-F-BADOUTFIL, Cannot open file specified with /OUTPUT

Explanation: The file specified with the /OUTPUT qualifier cannot be opened.

> %RTR-E-BADPRTSTATE, Disallowed attempt to make an illegal or undefined partition state transition

Explanation: Returned following an attempt to make an illegal or undefined partition state transition. The specified state transition is invalid.

> %RTR-E-BADRTRINS, RTR is not correctly installed

Explanation: RTR is not correctly installed. Refer to the RTR Installation Guide for details of how to install RTR.

> %RTR-W-BADTRVERSION, Function not supported in version of RTR on router node

Explanation: RTR is running in a mixed-version environment. A router running an older version of RTR does not recognize the operation requested of it by a newer version of RTR running on another node. Usually this indicates some inconsistency in the rolling upgrade procedure. Consult the Release Notes and RTR Installation Guide for instructions on rolling upgrades.

> %RTR-E-BENOTALL032, Not all backends are at the minimum required version of V3.2

Explanation: Cannot perform the requested action because not all routers are at a minimum version of V3.2.

> %RTR-E-CANTSTOP, RTR could not be stopped

Explanation: RTR cannot be stopped under the present circumstances.

> %RTR-E-CHAALROPE, Channel [A] is already open in this window

Explanation: An RTR channel of this name is already open in this window.

> %RTR-F-CHANOTOPE, Channel not opened

Explanation: Channel was not opened. Check channels using the SHOW CHANNEL command.

> %RTR-F-CHKDSKSP, Check for device full or inadequate disk quota

Explanation: Journal creation fails because there is not enough device space/disk quota. Increase device space/disk quota and create the journal.

> %RTR-E-CHNALRDEC, Channel [A] is already declared

Explanation: The channel specified with the /CHANNEL qualifier on a CALL RTR_OPEN_CHANNEL command has already been declared.

> %RTR-E-CHNOTACTIVE, Channel does not have active transaction running

Explanation: No transaction is currently active on this channel. This can occur only in the V2 command environment, and is retained for compatibility with previous versions of RTR.

> %RTR-E-CLASSREQ, At least one data-class definition required

Explanation: At least one data-class definition is required in a call to rtr_request_info.

> %RTR-E-CLOSEPEND, Send failed due to close pending on channel - call rtr_receive_message

Explanation: Sending of data to the RTRACP has been aborted due to the presence of an undelivered mt_closed message on the channel. The application may retrieve the reason for the channel closure by calling rtr_receive_message to receive the mt_closed message.

> %RTR-I-CMDIGNORE, Command ignored for defined facility role

Explanation: Indicates that the command was ignored on the executing node since it has no significance for the role defined.

> %RTR-I-CMDNOTWRK, [A]-command not implemented

Explanation: This command is not currently implemented.

> %RTR-E-CMDRESDEV, Command reserved to RTR development

Explanation: An unsupported command was issued.

> %RTR-E-CMDTOOLON, Command too long

Explanation: Command was longer than 256 characters.

> %RTR-E-CNTCRJOU, Cannot create journal directory

Explanation: Cannot create journal directory. Check that RTR has sufficient permission, disk space and disk quota, and that the parent directory exists and is writable. There may be more details in the log.

> %RTR-S-COMARESEN, Commands sent by default to node [A]

Explanation: Displays the default nodes for command execution after issuing a SET ENVIRONMENT or SHOW ENVIRONMENT command.

> %RTR-E-COMNOTFOU, Command not found [A], use RECALL/ALL

Explanation: The command [A] requested with RECALL did not match any command in the recall buffer.

> %RTR-E-COMNUMMUS, Command number must be between 1 and [A]

Explanation: The command number requested with RECALL was not in the allowed range (1 to [A]).

> %RTR-F-CONFLICT, Illegal combination of command elements - check documentation n [A]

Explanation: Two or more keywords, qualifiers or parameters that cannot be used in in combination were used in the same command line.

> %RTR-S-CPCREATED, ConnectionPool [A] created

Explanation: Displays the name [A] of the ConnectionPool that was successfully created after issuing a CREATE CONNECTIONPOOL command.

> %RTR-S-CPDELETED, ConnectionPool [A] deleted

Explanation: ConnectionPool has been successfully deleted after issuing a DELETE CONNECTIONPOOL command.

> %RTR-E-CPINUSE, ConnectionPool [A], is currently in use

Explanation: The ConnectionPool name specified in a CREATE DATASOURCE or MODIFY DATASOURCE command is already associated with another DataSource.

> %RTR-S-CPMODIFIED, ConnectionPool [A], has been modified

Explanation: Confirms that the MODIFY CONNECTIONPOOL command has successfully modified the required parameter of the RTR Connection Pool.

> %RTR-E-CPNOTFOU, ConnectionPool [A], not found

Explanation: RTR ConnectionPool not found.

This status may be returned by the MODIFY CONNECTIONPOOL, DELETE CONNECTIONPOOL and SHOW CONNECTIONPOOL commands.

The can be caused by one of the following:

a) You have not issued an RTR CREATE CONNECTIONPOOL command.

b) The ConnectionPool has been deleted.

> %RTR-E-CPPROPFMAT, The format of ConnectionPool [A]'s property is wrong - use key:val format

Explanation: The format of a ConnectionPool property is not proper. The defined format is "/property=(key1:val1, key2:val2,...)".

This status may be returned by the MODIFY CONNECTIONPOOL and CREATE CONNECTIONPOOL commands.

> %RTR-S-CPTESTED, ConnectionPool [A] tested successfully

Explanation: The ConnectionPool has been successfully tested after issuing a CREATE CONNECTIONPOOL/TEST command.

> %RTR-I-CPTESTFAIL, ConnectionPool [A] test failed

Explanation: The testing of ConnectionPool failed after issuing a CREATE CONNECTIONPOOL/TEST command.

> %RTR-E-CTRHSTNOTSTART, Counter host not started

Explanation: The performance counter host could not be started. Check the RTR log file for additional information.

> %RTR-S-CTRHSTSTART, Counter host started

Explanation: The performance counter host was successfully started.

> %RTR-I-DEQDATA, Received data ([A] bytes) [B]

Explanation: Displays the dequeued data [B] and its length in bytes [A].

> %RTR-F-DFSDISK, Disk is served by DFS

Explanation: An attempt was made to create a journal on a disk served by DFS. RTR does not support journals on DFS-supported disks.

> %RTR-I-DISABMOD, [A] mode disabled

Explanation: Displays the name [A] of the mode that was disabled after issuing a SET MODE command.

> %RTR-S-DISITMCLR, [A] monitor item(s) cleared

Explanation: Indicates how many monitor items [A] were successfully cleared after issuing a CLEAR command.

> %RTR-E-DISKACCDEN, Disk access denied - privileges required to create a journal in the directory

Explanation: The journal directory exists, but the RTR process does not have sufficient access permission to create journal files in it.

> %RTR-W-DISKALL, Disk is not available to RTR

Explanation: An attempt was made to create a journal on a disk which is allocated to a different process.

> %RTR-W-DISKMNTVER, Disk is currently under mount verification

Explanation: An attempt was made to create a journal on a disk which is in mount verification. Try later.

> %RTR-W-DISKMOUFOR, Disk is mounted foreign

Explanation: An attempt was made to create a journal on a disk which is mounted foreign. Please check disk for proper mount status.

> %RTR-W-DISKNOTMOU, Disk is not mounted

Explanation: An attempt was made to create a journal on a disk which is not mounted. Please check disk for proper mount status.

> %RTR-W-DISKSSM, Disk is a member of a shadow set

Explanation: An attempt was made to create a journal on a disk which is a member of a shadow set. RTR cannot locate journals on individual shadow set members.

> %RTR-W-DISKSWL, Disk is software write locked

Explanation: An attempt was made to create a journal on a disk which is software write locked.

> %RTR-I-DROPPEDBE, Dropped backend [A] from facility [A]

Explanation: A role was trimmed from the facility causing a role/node combination to be dropped. When a router is trimmed and later restored, all other roles in the facility are not automatically restored. A lost role on a specific node can be restored using an EXTEND FACILITY/ROUTER=thisnode/BACKEND=lostnode command.

> %RTR-I-DROPPEDFE, Dropped frontend [A] from facility [A]

Explanation: A role was trimmed from the facility causing a role/node combination to be dropped. When a router is trimmed and later restored, all other roles in the facility are not automatically restored. A lost role on a specific node can be restored using an EXTEND FACILITY/ROUTER=thisnode/FRONTEND=lostnode command.

> %RTR-S-DSCREATED, Datasource [A] created

Explanation: Displays the name [A] of the DataSource that was successfully created after issuing a CREATE DATASOURCE command.

> %RTR-S-DSDELETED, Datasource [A] deleted

Explanation: DataSource has been successfully deleted after issuing a DELETE DATASOURCE command.

> %RTR-E-DSKNOTSET, Specified disk not part of the journal disk set

Explanation: A disk specified as part of a MODIFY JOURNAL command was not part of the original disk set specified in the CREATE JOURNAL command.

> %RTR-S-DSMODIFIED, Datasource [A] has been modified

Explanation: Confirms that the RTR DataSource has successfully modified the required parameter after issuing a MODIFY DATASOURCE command.

> %RTR-E-DSNOTFOU, DataSource [A] not found

Explanation: RTR DataSource not found.

This status may be returned by the MODIFY DATASOURCE, DELETE DATASOURCE and SHOW DATASOURCE commands.

This can be because:

a) You have not issued an RTR CREATE DATASOURCE command.

b) The DataSource has been deleted.

> %RTR-E-DTXNOSUCHRM, There is no such RM registered

Explanation: There is no such Resource Manager (RM) registered.

> %RTR-W-DTXREADONLY, The transaction branch was read-only and has been committed

Explanation: The Resource Manager (RM) will simply return a warning indicating the transaction branch was read-only and has been committed already.

> %RTR-E-DTXRMBUSY, DTX RM is still in use by RTR

Explanation: The DTX Resource Manager (RM) is still referenced by at least one RTR facility or open channel.

> %RTR-E-DTXRMEXISTS, The DTX RM has already been registered

Explanation: The Resource Manager (RM) has already been registered.

> %RTR-E-DTXTOOMANYRMS, Too many RMs or instances of an RM have been registered

Explanation: The RTRACP has registered too many (> 16) Resource Manager (RM) instances.

> %RTR-E-DTXXAERPROTO, RTR invoked an xa call in an improper context

Explanation: RTR called the XA routine in an improper context, for example, calling xa_commit call without calling xa_prepare.

> %RTR-E-DUPCPNAME, Duplicate ConnectionPool name, [A]

Explanation: The ConnectionPool name specified in a CREATE CONNECTIONPOOL command already exists in the system.

> %RTR-E-DUPDSNAME, Duplicate DataSource name, [A]

Explanation: The DataSource name specified in a CREATE DATASOURCE command already exists in the system.

> %RTR-F-DUPJOUFIL, Duplicate RTR journal file found - remove duplicate or use CREATE JOURNAL /SUPERSEDE

Explanation: A duplicate RTR journal file has been found. This status may be returned by the CREATE FACILITY and SHOW JOURNAL commands.

Previous | Next | Contents | Index