RTR performs both client and user verification.

B.2.1 User Authentication

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

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

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/...

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.

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

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

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

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

The RTR log file usually contains more details.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

%RTR-F-CHANOTOPE, Channel not opened

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

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

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

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

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

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

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

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

%RTR-E-CMDTOOLON, Command too long

%RTR-E-CNTCRJOU, Cannot create journal directory

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

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

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

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

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

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

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

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

%RTR-E-CPNOTFOU, ConnectionPool [A], 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

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

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

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

%RTR-E-CTRHSTNOTSTART, Counter host not started

%RTR-S-CTRHSTSTART, Counter host started

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

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

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

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

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

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

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

%RTR-W-DISKMOUFOR, Disk is mounted foreign

%RTR-W-DISKNOTMOU, Disk is not mounted

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

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

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

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

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

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

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

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

%RTR-E-DSNOTFOU, DataSource [A] 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

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

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

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

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

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

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

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

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