Teradata Query Director. User Guide

Transcription

1 Teradata Query Director User Guide Release B A August 2007

2 The product or products described in this book are licensed products of Teradata Corporation or its affiliates. Teradata, BYNET, DBC/1012, DecisionCast, DecisionFlow, DecisionPoint, Eye logo design, InfoWise, Meta Warehouse, MyCommerce, SeeChain, SeeCommerce, SeeRisk, Teradata Decision Experts, Teradata Source Experts, WebAnalyst, and You ve Never Seen Your Business Like This Before are trademarks or registered trademarks of Teradata Corporation or its affiliates. Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc. AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc. BakBone and NetVault are trademarks or registered trademarks of BakBone Software, Inc. EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation. GoldenGate is a trademark of GoldenGate Software, Inc. Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company. Intel, Pentium, and XEON are registered trademarks of Intel Corporation. IBM, CICS, DB2, MVS, RACF, Tivoli, and VM are registered trademarks of International Business Machines Corporation. Linux is a registered trademark of Linus Torvalds. LSI and Engenio are registered trademarks of LSI Corporation. Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States and other countries. Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries. QLogic and SANbox trademarks or registered trademarks of QLogic Corporation. SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc. SPARC is a registered trademarks of SPARC International, Inc. Sun Microsystems, Solaris, Sun, and Sun Java are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries. Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and other countries. Unicode is a collective membership mark and a service mark of Unicode, Inc. UNIX is a registered trademark of The Open Group in the United States and other countries. Other product and company names mentioned herein may be the trademarks of their respective owners. THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN AS-IS BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country. Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice. To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please teradata-books@lists.teradata.com Any comments or materials (collectively referred to as Feedback ) sent to Teradata Corporation will be deemed non-confidential. Teradata Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback. Copyright by Teradata Corporation. All Rights Reserved.

3 Preface Purpose This book provides information about Teradata Query Director (Teradata QD), which is a Teradata Tools and Utilities product. This book also provides information about installing Teradata QD. Teradata Tools and Utilities are a group of products designed to work with Teradata Database. This book explains how to use Teradata QD to increase database availability and efficiency by routing sessions between two or more Teradata Databases. Audience This book is intended for use by: System and application programmers System administrators Database administrators and relational database developers System operators and other database specialists Supported Releases This book supports the following releases: Teradata Database Teradata Tools and Utilities Teradata Query Director Note: See Teradata QD Version Number on page 28 to verify the Teradata QD version number. To locate detailed supported release information: 1 Go to 2 Navigate to General Search> Publication Product ID. 3 Enter Open the version of the Teradata Tools and Utilities ##.##.## Supported Versions spreadsheet associated with this release. Teradata Query Director User Guide 3

4 Preface Prerequisites The spreadsheet includes supported Teradata Database versions, platforms, and product release numbers. Prerequisites The following prerequisite knowledge is required for this product: Computer technology and terminology System console environment NCR system hardware Relational database management systems Basic concepts and facilities of the Teradata Database and the NCR server Connectivity software, such as ODBC or CLI Changes to This Book The following changes were made to this book in support of the current release. Changes are marked with change bars. For a complete list of changes to the product, see the Teradata Tools and Utilities Release Definition associated with this release. Date and Release Aug July Description Updated routing configuration file format in chapter 4. See Creating a Routing Configuration File on page 38 Supported platform update. See Supported Platforms on page 27 Updated security version settings. See Security Mechanisms on page 23 Added note that QD does not currently support multi-byte logon names or account strings. See What is Teradata Query Director on page 17 Additional Information Additional information that supports this product and Teradata Tools and Utilities is available at the web sites listed in the table that follows. In the table, mmyx represents the publication date of a manual, where mm is the month, y is the last digit of the year, and x is an internal publication code. Match the mmy of a related publication to the date on the cover of this book. This ensures that the publication selected supports the same release. 4 Teradata Query Director User Guide

5 Preface Additional Information Type of Information Description Access to Information Release overview Late information Additional product information CD-ROM images Use the Release Definition for the following information: Overview of all of the products in the release Information received too late to be included in the manuals Operating systems and Teradata Database versions that are certified to work with each product Version numbers of each product and the documentation for each product Information about available training and the support center Use the Teradata Information Products Publishing Library site to view or download specific manuals that supply related or additional information to this manual. Access a link to a downloadable CD-ROM image of all customer documentation for this release. Customers are authorized to create CD-ROMs for their use from this image. 1 Go to 2 Select the General Search check box. 3 In the Publication Product ID box, type Click Search. 5 Select the appropriate Release Definition from the search results. 1 Go to 2 Select the Teradata Data Warehousing check box. 3 Do one of the following: For a list of Teradata Tools and Utilities documents, click Teradata Tools and Utilities and then select a release or a specific title. Select a link to any of the data warehousing publications categories listed. Specific books related to Teradata QD are as follows: Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems B mmyx ODBC Driver for Teradata User Guide B mmyx Security Administration B mmyx Performance Management B mmyx Messages B mmyx Database Administration B mmyx Utilities Quick Reference B mmyx 1 Go to 2 Select the General Search check box. 3 In the Title or Keyword box, type CD-ROM. 4 Click Search. Teradata Query Director User Guide 5

6 Preface Additional Information Type of Information Description Access to Information Ordering information for manuals General information about Teradata Use the Teradata Information Products Publishing Library site to order printed versions of manuals. The Teradata home page provides links to numerous sources of information about Teradata. Links include: Executive reports, case studies of customer experiences with Teradata, and thought leadership Technical information, solutions, and expert advice Press releases, mentions, and media resources 1 Go to 2 Select the How to Order check box under Print & CD Publications. 3 Follow the ordering instructions. 1 Go to Teradata.com. 2 Select a link. 6 Teradata Query Director User Guide

7 Table of Contents Preface Purpose Audience Supported Releases Prerequisites Changes to This Book Additional Information Chapter 1: Teradata QD Overview What is Teradata Query Director How Does Teradata QD Work Teradata Query Director Userid Teradata QD Features Heterogeneous Teradata Support Teradata QD Commands Teradata QD Port Reserver Teradata QD as a Windows Service Chapter 2: Security Settings Security Mechanisms Security Features Not Supported Teradata Generic Security Services KRB5 and LDAP Denial of Service Protection Sockclient Security Teradata Query Director User Guide 7

8 Table of Contents Chapter 3: Installation Installation Requirements Hardware Requirements Supported Platforms Software Requirements Teradata Generic Security Services Supported Teradata Versions Teradata QD Version Number Installing Teradata QD on Windows Silent Install Options For Teradata QD Windows Patches Installing Teradata QD on Linux Installing Linux Dependencies Chapter 4: Configuration Files How Teradata QD Configuration Works Checking Configuration Files at Startup Routing Configuration File Overview Named Routing Preferred Routing Any Routing Using Wild Cards Routing On Roles and Profiles Routing Behavior Summary Creating a Routing Configuration File Routing Configuration File Format Naming and Saving the Routing Configuration File Creating a Routing Configuration File Changing the Routing File Dynamically Creating Error Code Files Error Code Format and Ranges Creating a Host File Teradata Query Director User Guide

9 Table of Contents Chapter 5: Teradata QD Operation Setting Teradata Query Director Parameters Prerequisites Default Directory for Teradata QD Configuration Files Setting Parameters for Teradata QD Windows Service Teradata Query Director Parameters Running Teradata QD from the Command Line Typical Command Line Syntax Starting and Stopping Teradata Query Director Running Teradata QD as a Windows Service Using Microsoft Services Console Creating a Parameter File for Teradata QD Windows Service File Location When Teradata QD Runs as a Service Viewing Teradata QD Messages with Event Viewer How Teradata QD Logs Events as a Windows Service Session Balancing Round Robin Weighted Round Robin Least Used Log Files Log File Naming Convention Log level Trace Level Files Teradata QD Port Reserver Chapter 6: Commands Teradata Query Director Commands Teradata Query Director Commands Command Line Syntax Syntax Examples Stat Command Output Ses Command Output Health Check Command Shutdown Command Syntax Example Command Behavior Teradata Query Director User Guide 9

10 Table of Contents Setsys Up or Down Command Update -rcfg Command Update -loglevel Command Command Behavior Update -trclvl Command Syntax Example Command Behavior Users Command Config Command Syntax Example Output Example Results LCD Command Syntax Example Output Example Results Options Command Syntax Example Output Example Appendix A: Messages, Error Codes, Troubleshooting Teradata QD Messages Teradata QD Error Codes Basic Troubleshooting Appendix B: Failover Behavior And Errors Failover Terms Error and Failover Scenarios Teradata Errors on Start SQL Request Teradata Errors on Logon Request Socket Failure from the Teradata System Side Socket Failure from the Client Side Teradata Query Director User Guide

11 Table of Contents Appendix C: Teradata QD Features Heterogeneous Teradata Support Failover and Heterogeneous Teradata Support Examples Troubleshooting the Heterogeneous Teradata Environment Port Reserver Service Teradata QD as a Windows Service Parameters for Teradata as a Windows Service Current Working Directory Error Messages Examples Glossary Index Teradata Query Director User Guide 11

12 Table of Contents 12 Teradata Query Director User Guide

13 List of Figures Figure 1: Overview of Teradata Query Director Figure 2: How Teradata Query Director Routes Sessions Figure 3: Teradata Query Director Installation Wizard Figure 4: Example of Formatting for the Routing Configuration File Figure 5: Example of an Error Code File Figure 6: Microsoft Management Console window Figure 7: Example of a Parameter File in Notepad for Teradata QD Service Figure 8: Event Viewer Figure 9: Teradata QD Message Window from Event Viewer Figure 10: Typical Teradata QD Log File Figure 11: Typical Teradata QD Level 1 Trace File Figure 12: Typical Teradata QD Level 2 Trace File Figure 13: Stat Command Output Example Figure 14: Ses Command Output Example Figure 15: Health Check Output Example Figure 16: Output Example for the Users Command Figure 17: Output Example for the -Options Command Figure 18: Example of tqdrsvport Log Entries Figure 19: Teradata QD Event Log Example Figure 20: Windows Event Log Example for Teradata QD Teradata Query Director User Guide 13

14 List of Figures 14 Teradata Query Director User Guide

15 List of Tables Table 1: Teradata QD Versions/Security Support Table 2: Parameters for Creating and Running an.iss File Table 3: Routing Behavior Summary Table 4: Default Directory for Teradata QD Files Table 5: Teradata QD Startup Parameters Table 6: Log File Description Table 7: Level 2 Trace File Description Table 8: Teradata QD Commands Table 9: Teradata QD Command Syntax Table 10: Stat Command Output Table 11: Ses Command Output Table 12: Users Command Output Table 13: Teradata QD Messages Table 14: Teradata QD Error Codes Table 15: Example 1: Failover Scenarios with Heterogeneous Teradata Support Table 16: Example 2: Failover Scenarios with Heterogeneous Teradata Support Teradata Query Director User Guide 15

16 List of Tables 16 Teradata Query Director User Guide

17 CHAPTER 1 Teradata QD Overview This chapter includes the following sections that provide an overview of Teradata QD: What is Teradata Query Director How Does Teradata QD Work Teradata QD Features What is Teradata Query Director Teradata Query Director (Teradata QD) is a session-routing tool that allows administrators to make full use of primary and standby systems by routing sessions between two or more systems while maintaining full backup status. Teradata QD sits between the client application and two or more Teradata Database systems and routes sessions using rules set by the administrator. The routing methods are used to spread workloads evenly among systems and to failover from one system to another if a database goes down. Teradata QD also performs a failover on user-defined Teradata Database errors. Teradata QD is a command line application (or can be run as a Windows service) that is configured at start up. Teradata QD uses command line parameters (or the parameter file if running as a service), routing configuration file, and error code files to make routing decisions. Figure 1 shows an overview of Teradata QD. Teradata Query Director User Guide 17

18 Chapter 1: Teradata QD Overview How Does Teradata QD Work Figure 1: Overview of Teradata Query Director Teradata System A Physical Database JDBC ODBC CLI Query Director Teradata System B Physical Database 2510B002 Note: Teradata QD does not support load/unload utilities or backup and restore utilities, including: Teradata Archive and Recovery Teradata FastExport Teradata FastLoad Teradata MultiLoad Teradata Parallel Transporter Teradata Parallel Data Pump is supported, but only with NAMED configurations. Note: Teradata QD does not currently support multi-byte logon names and account strings. How Does Teradata QD Work Teradata QD sits between the client and the Teradata Database system and listens for sessions to be started. When a session is initiated, Teradata QD uses a routing algorithm and a routing configuration file to decide which system the session should be routed to. The process is transparent to the client. See How Teradata QD Configuration Works on page 33 for more information on routing. See Creating a Routing Configuration File on page 38 for more information on using the routing file. Sessions are routed using the startup parameters and an optional routing file. The routing file, created by an administrator, links specific userid and account strings to specific system or systems. Refer to Teradata Query Director Userid on page 19. The parameters give Teradata QD a set of routing algorithms that help balance session loads. See Session Balancing on page 53 for more information on session balancing and routing. 18 Teradata Query Director User Guide

19 Chapter 1: Teradata QD Overview How Does Teradata QD Work The routing algorithms are designed to give the administrator the ability to take advantage of the type of systems and client applications and maximize the efficiency of all the equipment. Teradata QD also performs a failover from one system to another using routing rules and the error codes files. These files are created by the administrator before starting Teradata QD. See Routing Behavior Summary on page 37 for more information on failover behavior. Figure 2 shows how Teradata QD routes sessions between the client application and systems. Figure 2: How Teradata Query Director Routes Sessions Any Client CLI, ODBC, JDBC Tool (Mstr etc.) SQL Select Result Sets Teradata Query Director Teradata 'Listener' Load - Balanced Re-routes when needed Teradata 1 (T1) Teradata 2 (T2) Direct Connection 2510C001 Teradata Query Director Userid Teradata Query Director uses a Teradata QD userid in its routing file. The value of the Teradata QD userid is dependent on the security mechanism used at logon. When using TD methods TD1 and TD2, a user logs onto the Teradata Database using the Teradata Database username. In this case, the Teradata QD userid is the Teradata Database username. When using Kerberos (SSO and Sign-on As), the username is common to both the Teradata Database and the Windows client domain. In this case, the Teradata QD userid, the Teradata Database username, and the Windows client domain username are the same. When using LDAP (Directory sign-on), the user logs onto the Teradata Database using the directory user name (.logdata authcid=directory user name). The LDAP server authenticates the user. For directory users that are: mapped to one or more Teradata Database user names, the Teradata QD userid is the Teradata Database username that the user is mapped to at logon. mapped to EXTUSER, the Teradata QD userid is the Directory user name (authcid). On the database, these users are logged in under the Directory user name, not EXTUSER, so use this name in the routing file. For details, refer to the most recent version of Security Administration, B mmyA, where mm indicates the month and y indicates the year of publication. Note: When creating a routing file based on roles and profiles, directory-mapped roles and profiles can be used in place of a standard username. See Routing On Roles and Profiles on page 36 for more information. Teradata Query Director User Guide 19

20 Chapter 1: Teradata QD Overview Teradata QD Features Teradata QD Features The following sections provide a brief description of Teradata QD features. Heterogeneous Teradata Support Teradata QD Commands Heterogeneous Teradata Support (HTS) is a feature that allows Teradata Query Director to support different versions of the Teradata Database. Teradata QD currently supports V2R6.0, V2R6.1, V2R6.2, and Teradata Database When a Teradata QD session starts, heterogeneous support automatically scans the connected systems configuration and creates a common configuration list. This common configuration is reported to the Client for that session. When a failover occurs, Teradata QD compares the session common configuration list to the targeted system to see if it meets or exceeds the common configuration. If it does, Teradata QD performs a failover to that system. If the targeted system does not meet the common configuration, Teradata QD targets the next system for failover. The session configuration may not be met by a system if the system has been reconfigured or downgraded. When a failover occurs, Teradata QD checks supported features on targeted systems. If the system does not support the feature, Teradata QD ignores that TDS for failover and moves to next system. For example, if Teradata QD starts with two Teradata Database Systems (TDS) running versions which support a feature, and one system is downgraded to a lower version which doesn t support a feature, the existing session will not failover to the downgraded system. Here are some examples of the type of configuration features checked for commonality: APH Response capability Buffer size supported (64KB or 1MB) Session character set Default char set Number of Amps Heterogeneous Teradata Support has several commands that help determine the common feature set of the connected systems. See Teradata Query Director Commands on page 61 for more information. For further information on Heterogeneous Teradata Support, see Appendix C: Teradata QD Features. Teradata QD provides a set of commands to change Teradata QD behavior while Teradata QD is running. The sockclient command utility is used to send commands and is optionally installed with Teradata QD. See Chapter 6 Commands on page 61 for more information on using sockclient to issue commands. Teradata QD commands help the administrator change parameters while Teradata QD is running. Commands are used to change the routing file, perform a health check, retrieve session or statistics, or shutdown Teradata QD. 20 Teradata Query Director User Guide

21 Chapter 1: Teradata QD Overview Teradata QD Features Teradata QD Port Reserver The default Teradata Database TCP/IP access port is This port number can conflict with Windows usage of this port for RPC. On the Windows operating system, Teradata QD provides an optional service that reserves port 1025 for Teradata QD at system boot time. For further information about this service Port Reserver Service on page 101. Teradata QD as a Windows Service Teradata QD is also installed on Microsoft Windows as a service. See Installing Teradata QD on Windows on page 29 for more information. Also see Setting Parameters for Teradata QD Windows Service on page 44 to learn how to set the startup parameters when Teradata QD is installed as a Windows service. Teradata Query Director User Guide 21

22 Chapter 1: Teradata QD Overview Teradata QD Features 22 Teradata Query Director User Guide

23 CHAPTER 2 Security Settings Teradata QD supports several Teradata Security Mechanisms and Denial of Service Protection, which detects when a client has disconnected. Security Mechanisms Teradata Generic Security Services KRB5 and LDAP Denial of Service Protection Sockclient Security Security Mechanisms Teradata QD supports security mechanisms for each Teradata Tools and Utilities and Teradata Database version combination. The Teradata Tools and Utilities version must be equal to or higher than the Teradata Database version that is used, as shown in the next table. Using the mechanism specified in the table, Teradata QD encrypts the logon and payload portion of each session. Teradata Query Director User Guide 23

24 Chapter 2: Security Settings Security Mechanisms Table 1: Teradata QD Versions/Security Support Teradata QD Security Support TQD TTU Teradata Database V2R6.2 V2R6.1 V2R6.0 TD2 Kerberos LDAP TD2 Kerberos LDAP TD2 Kerberos LDAP TD2 Kerberos LDAP TTU V2R6.2 TD2 Kerberos LDAP V2R6.1 V2R6.0 TD2 Kerberos LDAP TD2 Kerberos LDAP Kerberos and LDAP mechanisms perform authentication. Clients requesting Kerberos or LDAP can only target Teradata Database that have Kerberos or LDAP configured. Those Teradata Databases that do not have Kerberos or LDAP configured are excluded from the session by Teradata QD. Note: Only Teradata QD on Windows has Kerberos support. For a full description of Teradata Methods (also referred to as security mechanisms), refer to Security Administration, B mmyA, and Database Administration, B mmyA (mm represents the month and y represents the year of the publication.) Security Features Not Supported Teradata QD does not support these security features: NTLM Directory integration Context expiration Credential Expiration Administrators or users, can enable or disable encryption of data transmissions (payload) between the client system and the Teradata gateway when logging on from a client application. 24 Teradata Query Director User Guide

25 Chapter 2: Security Settings Teradata Generic Security Services Logon strings are automatically encrypted to ensure the security of passwords transmitted from the client to the database through the Teradata gateway. Teradata Generic Security Services Teradata Generic Security Services (TeraGSS) is the Teradata implementation of industry standard GSS (Generic Security Services) APIs. Teradata QD uses TeraGSS as a generic interface to process Client and Teradata messages. The Teradata QD server must have the Teradata Tools and Utilities TeraGSS package installed. When Teradata QD starts, it obtains the list of configured mechanisms from the TeraGSS software installed and configured on the Teradata QD server. The TDGSS User Configuration file should already have the Teradata QD supported mechanisms defined as supported mechanisms. To modify the list of supported mechanisms, stop and restart Teradata QD to pick up the changes. Teradata QD exits if it fails to configure TeraGSS. Sessions that do not plan to use encryption still require a valid TeraGSS configuration. Refer to Security Administration for information on editing the TDGSS User Configuration file. In the event a Client selects a mechanism other than what Teradata QD supports and is configured, an error is logged and the session is not allowed to continue. The TeraGSS default security mechanism (DefaultMechanism) on the Teradata QD server should match that of the Teradata Systems targeted by Teradata QD. Choices for the default are Kerberos, LDAP or TD2. If the Teradata QD targeted Teradata Systems are only using TD1 or TD2, set the Teradata QD server default mechanism to TD2. The default security mechansim is required on the Teradata QD system. If a default is not set, the most common error returned is CLI235. KRB5 and LDAP To use KRB5 and LDAP through Teradata QD, set the TeraGSS delegated credentials flag (DelegateCredentials) on the client system to "yes" for KRB5 and LDAP mechanisms. To properly configure Teradata QD for KRB5 and LDAP, configure the Teradata QD system as if it were a normal TDS in the security environment. This means appropriately modifying the User Configuration File, TDGSSUserConfigFile.xml, and any machine specific settings such as DNS and Domain. For example, to use LDAP, fill in these fields under the LDAP mechanism in the User Configuration File: LdapServerName="" LdapServerPort="389" LdapServerRealm="" Teradata Query Director User Guide 25

26 Chapter 2: Security Settings Denial of Service Protection LdapSystemFQDN="" LdapBaseFQDN="" There are no changes needed in the file for KRB5. Because Teradata QD uses TeraGSS software, the location of TDGSSUserConfigFile.xml may be different than on a Teradata server that installs TDGSS software. Also note that support for Kerberos is only available on Teradata QD for Windows. Refer to the TDGSS sections of Security Administration, B mmyA, for details on locating and editing the TeraGSS TDGSSUserConfigFile.xml file. Denial of Service Protection Teradata QD can detect if a connection to a Teradata Database system or a client is no longer responding. This is accomplished with the TCP keepalive option. On startup, Teradata QD turns on the TCP_KEEPALIVE flag, which enables the periodic transmission of keepalive probes to the remote system. If the remote system fails to respond to the keepalive probes, the connection is broken by TCP protocol. Teradata QD provides a parameter called -keepalive, which tells Teradata QD how long the connection needs to be idle before sending keepalive probes. This parameter is optional and if not set, defaults to 10 minutes. (See Teradata Query Director Parameters on page 45 for more information.) When Teradata QD starts, it modifies TCP s Keepalive parameter to 10 minutes (default) or to the -keepalive parameter value supplied to Teradata QD. In addition, and on Windows only, Teradata QD modifies TCP s Keepalive Interval to 2 minutes. The Keepalive Interval designates how often to send keepalive probes. Three TCP configuration values that play a role in disconnecting idle sessions that are not responding are: the Keepalive parameter, the Keepalive Interval, and the number of keepalive probes. Refer to TCP and Microsoft documentation for complete information on these parameters. Sockclient Security The following is a list important notes regarding sockclient security: Sockclient messages are now encrypted using the TD2 mechanism, which is part of the TeraGSS package. Be sure the TD2 mechanism is enabled on the system. TeraGSS is now an installation requirement for sockclient. See Teradata Generic Security Services on page 28 for more information. Older versions of sockclient do not work with the current version of Teradata QD The functions and usage of sockclient has not changed with the addition of sockclient security. Sockclient does not work with older versions of Teradata QD. 26 Teradata Query Director User Guide

27 CHAPTER 3 Installation This chapter explains how to install and uninstall Teradata Query Director for Windows and Linux. Installation Requirements Installing Teradata QD on Windows Installing Teradata QD on Linux Installation Requirements Hardware Requirements The minimal hardware recommendations are: 512 MB RAM Intel Pentium 500 MHz CPU Network communications via TCP/IP (e.g., Ethernet card) Supported Platforms Windows 2000 Advanced Server SP4 Windows 2000 Professional SP4 Windows 2000 Server SP4 Windows 2003 Server SP1 on 32-bit and 64-bit OS (no Itanium) Windows XP SP2 on 32-bit and 64-bit OS (no Itanium) Redhat Linux AS 3.0 on 32-bit OS Redhat Linux AS 4.0 on 32-bit and 64-bit OS Redhat Linux AS 4.0 on Opteron SUSE Linux Enterprise 9 SP1, 2, 3 on 32-bit and 64-bit OS SUSE Linux Enterprise 10 on 32-bit and 64-bit OS SUSE Linux Enterprise 10 on Opteron Windows XP SP2 on 32-bit and 64-bit EM64T Windows 2003 R2 32-bit and 64-bit EM64T Windows Vista on 32-bit and 64-bit EM64T RedHat AS 4.0 on 32-bit, 64-bit EM64T, Opteron RedHat AS 4.x on 32-bit, 64-bit EM64T, Opteron Teradata Query Director User Guide 27

28 Chapter 3: Installation Installation Requirements Software Requirements SuSE E9 SP 1,2,3 on 32-bit, 64-bit EM64T, Opteron SuSE E10 SP1 on 32-bit, 64-bit EM64T, Opteron The following is a list of software requirements for Teradata QD. These programs are included on the install CD. CLIv Teradata ICU Teradata GSS (required for QD and Sockclient) Teradata Generic Security Services Teradata Generic Security Services (TeraGSS) is the Teradata implementation of industrystandard GSS (Generic Security Services) APIs. Teradata QD uses TeraGSS as a generic interface to process Client and Teradata messages. To use TeraGSS, first install the TeraGSS package on the Teradata QD server. In the TeraGSS package, there is a TDGSS User Configuration file called TDGSSUserConfigFile.xml. In this file, define a Teradata QD-supported encryption method as a security mechanism and specify that mechanism as the default. Otherwise, a CLI235 error will result. Refer to Security Administration for information on editing the TDGSS User Configuration file and Security Mechanisms on page 23 for more information. When Teradata QD is started, it obtains the list of supported mechanisms from the TeraGSS software that is installed and configured on the Teradata QD machine. To modify the list of supported mechanisms, stop and restart Teradata QD to pick up the changes. If Teradata QD fails to configure GSS, Teradata QD will exit. Teradata QD requires a valid configuration to proceed. Supported Teradata Versions Supported Teradata Database versions are V2R6.0, V2R6.1, V2R6.2, Teradata Database Teradata Tools and Utilities versions must match the highest Teradata Database version. For more information regarding versions, see Table 1: Teradata QD Versions/ Security Support on page 24. Teradata QD Version Number There are several ways to find the version of Teradata QD. Use one of the following methods: When starting Teradata QD from the command line, the header information provides the version number. See Running Teradata QD from the Command Line on page 48 for more information. When using Teradata QD as a service, check the version number in the log file that is created when Teradata QD starts. See Viewing Teradata QD Messages with Event Viewer on page 51 for more information on viewing the log. 28 Teradata Query Director User Guide

29 Chapter 3: Installation Installing Teradata QD on Windows Installing Teradata QD on Windows Teradata Query Director installation CD comes with an installation wizard that helps users install Teradata QD and dependencies on Microsoft Windows machines. Teradata QD also installs as a Windows service in autostart installation mode. If this feature is not wanted, disable the service after installation. For more information on Teradata Query Director as a Service, see Teradata QD as a Windows Service on page 102. To install Query Director on Linux, see Installing Teradata QD on Linux on page 31. Figure 3 shows what the wizard looks like when it opens. The wizard helps install the following components: Teradata Query Director CLIv2 Shared ICU Libraries for Teradata Teradata_GSS_Client Use the wizard to do a typical install, which installs all the dependencies or a custom install that makes it possible to choose the dependencies. Figure 3: Teradata Query Director Installation Wizard To install Teradata QD through the install wizard 1 Insert the Teradata Tools and Utilities Release Query Director CD. 2 The autorun feature should automatically open the Teradata Tools and Utilities wizard. Click the Install Product button and follow the wizard instructions. See the note below for custom install instructions. Teradata Query Director User Guide 29

30 Chapter 3: Installation Installing Teradata QD on Windows 3 If the wizard does not open, open the CD directory and click Windows> TTU.exe. Then click the Install Product button and follow the wizard. Note: There is a point in the install wizard that gives a choice to install Query Director and its dependencies silently (this is the default). The silent install feature installs each piece of software without prompting. If the silent install feature is not used, the wizard prompts for inputs as it installs each piece of software separately. To pick and choose Teradata Query Director components such as sockclient, deselect Teradata Query Director components at the silent install option window. Otherwise, these components are installed automatically. After Teradata Query Director is installed, the machine may require a restart. Follow the prompts. For information on starting Query Director and setting parameters, see Setting Teradata Query Director Parameters on page 43. Silent Install Options For Teradata QD Windows Patches Silent install is an option that installs patches for Teradata Query Director without having to enter any input. Silent install uses an.iss file to store the input information required for subsequent installations. Creating an.iss File To create an.iss file, add the following parameters while installing Teradata Query Director. Table 2 shows the parameters for creating and running the.iss file. Syntax: setup /a /r This creates an.iss file that contains the inputs used in the initial installation. The file is stored in the Windows or WINNT directory unless other wise specified. To specify a path and file name, use the following syntax: Syntax: setup /a /r /f1"<pathname\filename>" Installing a Teradata Query Director Patch with an.iss File To install a Teradata Query Director patch using an.iss file, use the following syntax: Syntax: setup /a /s /f1"<pathname\filename> Table 2 shows the parameters that are used with.iss file. Note: If no path name is specified, for example, setup /a /s /f1"myiss.iss, setup looks for the file in the WINDOWS or WINNT directory. Table 2: Parameters for Creating and Running an.iss File Parameters Description /a Required before each of the following cases. /r Creates an.iss file (use after /a). Default location is setup.iss in Windows or WINNT directory. /s Runs the silent install (use after /a). 30 Teradata Query Director User Guide

31 Chapter 3: Installation Installing Teradata QD on Linux Table 2: Parameters for Creating and Running an.iss File (continued) Parameters /fl <PATHNAME\FILENAME> Description Specifies a new target path name and file name. Used with both /r and /s (use after /a). Note: There should be no spaces between the /fl and the quoted path/filename. Installing Teradata QD on Linux Teradata QD can be installed on a Linux operating system. Teradata QD for Linux consists of two rpm packages, qrydir and sockclient. The packages are located on the CD in Linux/qrydir/. The naming convention for the packages is packages-version-release.arch.rpm. (An ARCH value of i386 indicates Intel 32-bit software.) The 32-bit version of Teradata QD and the 32-bit versions of any dependent packages should be installed on a 64-bit Linux operating system. The qrydir package installs the qrydir executable. The sockclient package installs the sockclient executable. Both executables are installed in /opt/teradata/client/bin. The man pages are in /opt/teradata/client/man. The message file is in /opt/teradata/client/msg. Use rpm -i to install a package and rpm -e to erase a package. Installing Linux Dependencies These dependencies must be installed so that Teradata Query Director can run in Linux: CLIv2 TDICU TeraGSS Each program must be installed before Teradata QD. The dependency directories are located in the Linux directory in the install CD. Teradata Query Director User Guide 31

32 Chapter 3: Installation Installing Teradata QD on Linux 32 Teradata Query Director User Guide

33 CHAPTER 4 Configuration Files Teradata QD setup involves creating several files that tell Teradata QD how to operate. The files include the routing file, error code file, and the host file. This chapter explains the function of these files and how to create them. How Teradata QD Configuration Works Routing Configuration File Overview Creating a Routing Configuration File Creating Error Code Files Creating a Host File How Teradata QD Configuration Works Teradata QD is configured through the startup command line, (unless Teradata QD is running as a Windows service, in which case it uses a parameter file. See Creating a Parameter File for Teradata QD Windows Service on page 50 for more information.) the routing configuration file, and the error code files. Teradata QD uses the command line (or the parameter file if running as a service), routing file, and error code file to determine how sessions are routed between a client and the connected system(s). The routing configuration file (or parameter file) allows the administrator to associate specific userids and account strings with specific systems to control session routing and failover. See Appendix B: Failover Behavior And Errors for information about how failover works in Teradata QD. Startup command line - tells Teradata QD which systems to connect to. For more information on startup commands, see Setting Teradata Query Director Parameters on page 43. Parameter file - if Teradata QD is running as a Windows service, the parameter file tells Teradata QD which systems to connect to. For more information, see Running Teradata QD as a Windows Service on page 49. Routing file - tells Teradata QD that specific userid/account strings should connect to specific systems. The routing file also determines the order of failover in some cases. Error code file - tells Teradata QD to failover if specified Teradata errors occur. The routing file and error code files are optional. If not specified, command line routing is used (or the parameter file if running as a service). The administrator should create the routing file and the error code files before starting Teradata QD. Teradata Query Director User Guide 33

34 Chapter 4: Configuration Files Routing Configuration File Overview Checking Configuration Files at Startup Teradata QD routing is userid/account string-oriented. When a userid starts a session, Teradata QD checks the routing file to see how the userid is configured. Teradata QD checks the following: The userid is associated with a single system. This is referred to as a Named system. In this scenario, Teradata QD connects that userid/account string to that system and does not failover. A userid is associated with more than one system in the routing file (referred to as Preferred), Teradata QD connects to the first system listed. Failover goes to the next system listed with the userid. Teradata QD does not use the routing algorithm for a userid with Preferred routing. See Session Balancing on page 53 for more information on routing algorithms. The userid is specified with a wildcard (*) as the system (referred to as Any system), Teradata QD routes that session to any system listed on the command line (or the parameter file if running as a service) starting with the first item listed. Failover goes to the next system listed on the command line (or the parameter file if running as a service). Routing algorithms indicated on the command line (or the parameter file if running as a service) are in force. See Session Balancing on page 53 for more information on routing algorithms. Routing Configuration File Overview Named Routing The routing file itself is a simple text file that has three columns. The first column indicates the userid. The second column shows the account string. The third column indicates the system or systems. There can be more than one system listed in the system (third) column. See the following example: user1 acct1 tds1 user2 acct2 tds2 tds4 tds6 * acct2 tds3 The routing file is saved as a UTF8 or ASCII text file. Teradata QD does the text conversion between UTF8 and Unicode. There are three ways to specify a userid and a system in the routing file: A userid can be specified to connect to a single system. This configuration is called named. The following example shows how this line would be created in the routing file: user1 acct1 tds1 When user1 starts a session with acct1, Teradata QD refers to the command line (or the parameter file if running as a service) and routing file configuration and directs the session to tds1. There is no failover and no routing. 34 Teradata Query Director User Guide

35 Chapter 4: Configuration Files Routing Configuration File Overview Preferred Routing A userid can be specified to connect to a list of preferred systems. This configuration is called Preferred. When the userid starts a session, Teradata QD sees there are two or more systems associated with it, then connects the first system listed. If a failover occurs, Teradata QD changes to the next system on the list. The following examples show how this line would be created in the routing file: user1 acct1 tds1 tds2 tds3 -oruser1 acct1 tds1 user1 acct1 tds2 user1 acct1 tds3 When user1 starts a session, Teradata QD connects user1 to tds1. If a failover occurred, Teradata QD directs the user to tds2, then tds3. Any Routing A userid can be specified to connect to any system indicated on the command line (or the parameter file if running as a service). This configuration is called any. The following example shows how this line would be created: user1 acct1 * The asterick (*) in the third column tells Teradata QD to use any system listed on the startup command line (or the parameter file if running as a service). Teradata QD connects to the first system on the list. If a failover occurred, Teradata QD would connect to the next system listed. Any routing algorithm specified on the command line (or the parameter file if running as a service) is in force for this userid. Using Wild Cards A wildcard (*) in the first two columns of the routing file (userid or account string) tells Teradata QD to allow any userid or account string that is not listed in the routing file to connect to the specified system. For example: * acct1 tds3 This line tells Teradata QD that any userid not listed in the routing file that has the acct1 account string uses tds3. If a wildcard is found in the account string column (second column), Teradata QD accepts any account string for that userid when log on occurs. For example: user1 * tds3 This line tells Teradata QD that user1, with any account string not already listed in the routing file, can use system tds3. Teradata Query Director User Guide 35

36 Chapter 4: Configuration Files Routing Configuration File Overview If the wildcard is in the third column, Teradata QD refers to the systems listed in the startup command line (or the parameter file if running as a service) starting for first system. For example: user1 acct1 * The wildcard can also be the second system listed in the third column. For example: user1 * tds3 * In this case, Teradata QD connects to the listed system (tds3). If failover occurs, Teradata QD refers to the command line (or the parameter file if running as a service) for the next system to connect with. If the user is not named in the configuration file and there is no * * * or * acctstr tds, then they default to ANY. Routing On Roles and Profiles Teradata QD has an option that allows the user to create a routing file based on roles and profiles. Teradata QD routing is based on roles and profiles and uses the same routing file format, but role names and profile names are substituted for userid. Teradata QD searches on the role names first, then profile names, then userid, then finally any wildcards (*) if they exist. To use this feature, external authentication such as LDAP must be used because the roles and profiles are specified in the external directory server. Teradata QD uses the directory server to extract the role or profile name before logging into the Teradata System. For more information on roles and profiles, see Chapter 3 in the Teradata Database Security Administration book (B mmyA) and Chapter 7, User Authentication and Directory Integration, in the Security Orange Book ( xxx). Rules Roles and profile names are put into the same column as userid in the routing file (see Routing Configuration File Overview on page 34 for more information about routing configuration). Order of routing is as follows: Roles, Profiles, userid, and wild card (*). Restrictions Roles/Profiles/Users cannot have the same name. External Authentication, such as LDAP must be used. The Roles/Profiles must exist on the Teradata System. Note: A user can have multiple roles, but it is not known which role will be used. As a result, it is recommended that a user only have one role mapped in the routing file. This means that a user has only one Teradata role or a user has multiple Teradata roles but only one of those roles is in the routing file. 36 Teradata Query Director User Guide

37 Chapter 4: Configuration Files Routing Configuration File Overview Routing Behavior Summary Table 3 explains how Teradata QD behaves with various combinations of command line (or the parameter file if running as a service) entries, routing files, and error codes. Table 3: Routing Behavior Summary Connection Method Command Line/Parameter File and Routing File Userid Logon Behavior Failover Behavior To connect a userid/account string to a Single Named System Specify one TDS on command line (or the parameter file if running as a service). -or- If multiple TDS are specified on command line (or the parameter file if running as a service), specify one TDS in routing file for that userid/account string. Userid/account string logs on to the TDS specified. If logon fails, log entry created and an error is returned to application. No failover. Parcel failures/errors, socket errors, etc. are returned to the application. To connect a userid/account string to multiple systems in a Preferred order Specify more than one TDS on command line (or the parameter file if running as a service). Specify userid/account string and systems (TDS) in routing file. TDS column cannot start with wildcard (*). The order of TDS is that specified in the routing file. If a wildcard (*) is used after the first system, the remaining systems (TDS) are taken in the order specified on the command line (or the parameter file if running as a service). Teradata QD connects to all TDS identified for userid/ account. If logon fails, log entry is created. An error is returned to the application only when all logons fail. "Active session" is the connection to the Preferred TDS. The other connections are "Passive session" until failover occurs. Routing rules (weighted, round robin, least used) are ignored. Failover is possible: Active session fails over to the next TDS specified in the routing file. Failover on Teradata Parcel errors/ failures only if error code is listed in -err_pref file. Failover can occur on Socket errors/disconnects. Teradata Query Director User Guide 37

38 Chapter 4: Configuration Files Creating a Routing Configuration File Table 3: Routing Behavior Summary (continued) Connection Method Command Line/Parameter File and Routing File Userid Logon Behavior Failover Behavior To connect a userid/account string to Any system based on the command line (or the parameter file if running as a service) Specify more than one TDS on command line or parameter file. Used if there is no routing file specified on the command line or parameter file -or- Used if the specific userid and account is not in the routing file. -or- Used if the routing file contains three wildcards on the same line (* * *). Because userid is not in the routing file, the userid defaults to use the TDS and routing rules specified on the command line or parameter file. For any userid, Teradata QD connects to all TDS specified on the command line (or the parameter file if running as a service). If logon fails, log entry is created. An error is returned to the application only when all logon fail. If a routing rule is specified on the command line (or the parameter file if running as a service) (-route), users are logged on to the TDS using that rule. If routing rule is not specified, the default Round Robin algorithm is applied. For each userid, the first "Active session" is the connection to the TDS identified by the routing rule. The other connections are "Passive session" until failover occurs. Failover is possible: Active session fails over to next TDS specified on the command line (or the parameter file if running as a service). Routing rules are not applied in choosing the next TDS on failover. Failover on Parcel errors/failures only if the error code is listed in the -err_any file. Failover can occur on Socket errors/disconnects. Creating a Routing Configuration File The routing configuration file is a text file created by the administrator that tells Teradata QD to associate userids and accounts strings with specific Teradata Database systems listed on the startup command line (or the parameter file if running as a service). Note: If Teradata QD is running as a Windows service, routing information is conveyed through the parameter file instead. See Setting Parameters for Teradata QD Windows Service on page 44 for more information. Routing Configuration File Format Figure 4 shows an example of the way a routing configuration file is formatted. The first column lists the userid, the second column lists the account string, and the third column lists the system name. Any column can also contain a wildcard (*). More than one system can be listed on a single line. 38 Teradata Query Director User Guide

39 Chapter 4: Configuration Files Creating a Routing Configuration File Figure 4: Example of Formatting for the Routing Configuration File Naming and Saving the Routing Configuration File The routing configuration file can be named in any way. The default is routing.cfg. The name must be referenced in the startup parameter for Teradata QD to recognize it. See Teradata Query Director Parameters on page 45 for more information about the startup line command. Save the file to any directory and indicate the location on the command line or in the parameter file. If the directory location is not specified on the command line (or the parameter file if running as a service), Teradata QD looks in the default directory. See Default Directory for Teradata QD Configuration Files on page 44 for more information. Creating a Routing Configuration File The following procedure explains how to create a routing configuration file. To create a routing configuration file 1 Open a text editor. 2 Add a userid, an account string, and a system name to the file using the correct format. See Routing Configuration File Format on page 38 for more details. Figure 4 shows an example of the correct formatting. Repeat this for all userids. Note: The file is free format with one or more whites paces (spaces or tabs) between columns. 3 Name the routing file. The default name is routing.cfg. Use any other name but ensure the name is indicated on the startup command line or in the parameter file. 4 Save the file to any directory and specific the location on the command line or parameter file (service). See Default Directory for Teradata QD Configuration Files on page 44 for more information. Changing the Routing File Dynamically To change the routing configuration file while Teradata QD is running, issue an update -rcfg command using sockclient. For the specific command parameters, see Chapter 6 Commands on page 61. Teradata Query Director User Guide 39

40 Chapter 4: Configuration Files Creating Error Code Files The update command specifies a new routing configuration without stopping Teradata QD. Upon successful completion of the update command, existing sessions continue to use the previous routing rules, but any new sessions use the new routing rules. If the update command fails, Teradata QD continues to use the existing routing rules. Creating Error Code Files Error code files tell Teradata QD to perform a failover or an exit if a specified Teradata error occurs. The error codes are listed in the file created by the administrator before starting Teradata QD. See Appendix B: Failover Behavior And Errors for more information about errors and failover. There are three types of error code files: err_pref.txt err_any.txt err_exit.txt Note: Teradata has a large list of error codes and messages that appear in Messages, B mmyA, where mm represents the month and y represents the year of the publication. The err_pref file is used for userids that have Preferred systems listed in the routing file. This error file tells Teradata QD to failover to the next Preferred system if the Teradata error is listed in err_pref file. The err_any file is used for userids that have Any system listed in the routing file and tells Teradata QD to failover to another system if the Teradata error is listed in the err_any file. The err_exit.txt is used if the error is not found in either the err_pref file or the err_any file. The exit file tells Teradata QD to exit the session if an error code match is found in this file. The type of Teradata Database errors are pclfailure or pclerror. Socket errors or other communication-type errors do not use error code files. See Error and Failover Scenarios on page 94 for more information in these types of errors. Save the error code file to any directory and specify its location in the command line or parameter file (if Teradata QD is running as a service). See Default Directory for Teradata QD Configuration Files on page 44 for more information about where Teradata QD stores files. The default error code file names are err_pref.txt, err_any.txt, and err_exit.txt. Different names or directories can be used. Use the -err_pref, -err_any, or the -err_exit parameter to indicate this change on the startup command line (or the parameter file if running as a service). See Setting Teradata Query Director Parameters on page 43 or more information about startup commands. 40 Teradata Query Director User Guide

41 Chapter 4: Configuration Files Creating Error Code Files Error Code Format and Ranges The error code file is a text file with the codes separated by white space. There can be multiple error codes per line. Error codes can range from 0 to Error codes can also have a range that is indicated by using a dash (-). For example, See Figure 5 for an example of how error codes are formatted. In addition, errors codes can contain comments. Comments must be preceded by a # symbol. For example: 2449 # A read error occurred in the a permanently journal table. See Figure 5 for an additional example. To create an error code file 1 Open a text editor and create a list of error codes separated by a space. More than one error code can be on a single line. Figure 5 shows an example of the list of error codes created in Notepad. 2 Save the list using any name. The default names are err_pref.txt, err_any.txt, and err_exit.txt. If other names are used, state the new name and directory on the command line (or the parameter file if running as a service). 3 Save the file to any directory and specify its location on the command line or in the parameter file (when Teradata QD is a service). See Default Directory for Teradata QD Configuration Files on page 44 for more information about Teradata QD default file location. Teradata Query Director User Guide 41

42 Chapter 4: Configuration Files Creating a Host File Figure 5: Example of an Error Code File Creating a Host File Before Teradata QD starts, the host file names must be available to Teradata QD. Teradata QD uses gethostbyname to locate user-specified TDS names. Teradata QD looks up the COP names in ascending numbered order until a missing entry is encountered. The host name can be stored in the DNS and/or in the local host file. Each gateway is identified by a system name and has "cop" appended to it. See the example below. Because Teradata QD only recognizes the Teradata system name, the hosts file entries must be entered in the following format: IP Address, Primary System, TDSnameCOP(n). The following is an example of a multi-hosted system: IP Address Primary System TDS name COP# xxx.xxx.xxx.xxx Node-1 system1cop1 xxx.xxx.xxx.xxx Node-2 system1cop2 xxx.xxx.xxx.xxx Node-3 system1cop3 xxx.xxx.xxx.xxx Node-4 system1cop4 Note: For every user-specified -tds system name, a call is made to gethostbyname with an ascending cop <n> number appended to the name until a missing entry is encountered. 42 Teradata Query Director User Guide

43 CHAPTER 5 Teradata QD Operation This chapter explains how to set up and run Teradata QD parameters through a startup line command or as a Windows service. The chapter also explains other Teradata QD features. Setting Teradata Query Director Parameters Running Teradata QD from the Command Line Running Teradata QD as a Windows Service Session Balancing Log Files Trace Level Files Teradata QD Port Reserver Setting Teradata Query Director Parameters Teradata QD works on both Microsoft Windows based machines and Linux machines. There are slight differences in starting and running Teradata QD on these different operating systems. The differences are noted in the following procedures. Teradata QD also runs as a service on Microsoft Windows. See Setting Parameters for Teradata QD Windows Service on page 44 for more details about setting the parameters when Teradata QD runs as a service. Teradata QD is started and configured through a single command line (or the parameter file if running as a service). The following section explains how. Prerequisites Before starting Teradata QD, there are several prerequisites to consider: The routing configuration file, if one is present, should be created and saved to the intended directory. See How Teradata QD Configuration Works on page 33 for more information on creating a routing configuration file. This file is not required. Any error code files should be created and placed in the intended directory before starting Teradata QD. See Creating Error Code Files on page 40 for more information about error files. Errors files are not required to start Teradata QD. Teradata Query Director User Guide 43

44 Chapter 5: Teradata QD Operation Setting Teradata Query Director Parameters Default Directory for Teradata QD Configuration Files Teradata QD configuration file locations can be specified either in the command line or, if using Teradata QD as a Windows service, in the parameter file. If no location is specified, Teradata QD looks in the "Default Directory". For the command line, the Default Directory is the current working directory where Teradata QD is started (or executed) from. When Teradata QD runs as a Windows service, the Default Directory is the directory where Teradata QD was installed. This applies to all Teradata QD files including configuration files, error codes files, log and trace files. The following tables summarizes file location. Table 4: Default Directory for Teradata QD Files Teradata QD Started... Default Directory for Files Configuration File Names From the command line As a Windows service The directory that Teradata QD is started from (working directory). The installation directory. rcfg err_any err_pref err_exit logfile trace files Setting Parameters from a Command Line The following steps explain how to set up parameters. To set parameters using a line command 1 Open a command window (on Windows, Start> Run. Enter cmd). 2 Change to the Teradata QD directory. 3 Enter the command line to start Teradata QD and set parameters. See Teradata Query Director Parameters on page 45 and Typical Command Line Syntax on page 48 for details about Teradata QD command lines. On Linux, Teradata QD is a root-only executable. 4 Press Enter. Teradata QD starts. See Starting and Stopping Teradata Query Director on page 49 to stop Teradata QD. If an error occurs, see Teradata QD Messages on page 79. Setting Parameters for Teradata QD Windows Service If Teradata QD is running as a Windows service, the parameter file must be created before starting Teradata QD. The following steps explain how. 44 Teradata Query Director User Guide

45 Chapter 5: Teradata QD Operation Setting Teradata Query Director Parameters Note: If Teradata QD service is already running (to check the service console, go to: Start> Administrative Tools> Services and looks for Teradata QD), it must be restarted to pickup the parameters in the parameter file. To set parameters for Teradata QD service 1 Create a file using Notepad or other text editor and name it tdqrydir.txt. 2 Add the parameters to the file. See Table 5 for a list of Teradata QD parameters. List each parameter on a separate line. Note: A - is not required before parameter names. 3 Save the file to the same directory that Teradata QD was installed into. 4 Start/restart the Teradata QD service if it was running already. See Running Teradata QD as a Windows Service on page 49 for information about starting a stopping Teradata QD as a service. Teradata Query Director Parameters Table 5: Teradata QD Startup Parameters The following table explains Teradata QD startup parameters. See Typical Command Line Syntax on page 48 for syntax examples and explanations. Note: Parameters do not require a - if they are written in a parameter file for Teradata QD running as a Windows service. Parameter Required Description Default -tds <host name> {:port} {weight] -tds <hostname> is required. Port and weight are not required. Indicates the system (TDS) that Teradata QD connects to. Repeat the parameter for each additional system. Use the :port value to specify a port other than the default. Specify a routing weight by entering a number in the {weight} value. The number indicates the number of sessions connected before changing systems (the -route parameter is required). See Weighted Round Robin on page 54 for more information about weighting. None -port No Tells Teradata QD which port to listen for Teradata connections. Default is If 1025 is not used, clients must be set for non-default port via the TDMSTPORT environment variable or ODBC DSN definition. -keepalive No Tells Teradata QD how long the connection needs to remain idle before sending keepalive probes to the remote system. If the remote system fails to respond to the probes, the connection is broken. Values range from 1 to 120 minutes, inclusive. See Denial of Service Protection on page 26 for more information min Teradata Query Director User Guide 45

46 Chapter 5: Teradata QD Operation Setting Teradata Query Director Parameters Table 5: Teradata QD Startup Parameters (continued) Parameter Required Description Default -trclvl <1, 2, 3> No Specifies trace levels intended. Levels include in any combination. Trace levels indicate the information that is collected in the trace files. -trclvl 1: collects the session statistics in trace level 1 file. -trclvl 2: collects Teradata requests and response statistics in trace level 2 file. -trclvl 12: collects both session and request/response statistics in separate files. -trclvl 3: currently disabled See Trace Level Files on page 56 for more information on the trace file. It is also possible to change the trace level using the update command while Teradata QD is running. See Teradata Query Director Commands on page 61 for more information about the update command. None -rqbytes No If trclvl is set to trace level 3, this parameter indicates the maximum number of request buffer bytes to dump. -rpbytes No If trclvl is set to level 3, maximum number of response buffer bytes to dump. -tfp No Adds an optional prefix for the trace file(s). Files are named [tfp]t_nn_yyyymmdd.txt where tfp is the optional prefix and nn corresponds to the trace level indicated at startup. -cport No This parameter changes the default sockclient port. The default port is route No Defines the session balancing algorithm. The possible values are 'rr', 'wrr', 'lu. See Session Balancing on page 53 for more information. -logfile No Defines the log file name which stores all error and warning messages. The default log file name is qrydirlog_%y%m%d.txt. See Log Files on page 54 for more information on the log file. When Teradata QD starts, it creates this file in the specified location. If no location is specified, the file is created in the default directory. See Default Directory for Teradata QD Configuration Files on page 44 for more information None 6001 rr qrydirlog_%y %m%d.txt 46 Teradata Query Director User Guide

47 Chapter 5: Teradata QD Operation Setting Teradata Query Director Parameters Table 5: Teradata QD Startup Parameters (continued) Parameter Required Description Default -loglevel [1, 2, 3, 4] No Sets the level of information written to the log file: -loglevel 1 - writes only errors and important status messages (message types 'E' and 'A'). -loglevel 2 - writes warnings, errors, and important status messages (message types 'W', 'E', and 'A'). -loglevel 3 - writes informational messages, warnings, errors, and important status messages (message types 'I', 'W', 'E', and 'A'). -loglevel 4 - writes all messages, including debug messages (message types 'D', 'I', 'W', 'E', and 'A'). The default for the parameter is -loglevel 1. See Log level on page 56 for more information. The log level can also be changed using the update command while Teradata QD is running. See Teradata Query Director Commands on page 61 for more information about the update command. -loglevel 1 -rcfg No Indicates that Teradata QD should use a routing configuration file. See Creating a Routing Configuration File on page 38 for more information about the routing configuration file. The default name is routing.cfg. When Teradata QD starts, it looks for this file in the specified location. If no location is specified, Teradata QD looks in the default directory. See Default Directory for Teradata QD Configuration Files on page 44 for more information. If the user does NOT specify a routing configuration file and default routing file exists but can not be opened, Teradata QD aborts startup. If the user did specify a routing configuration file but it can not be opened, Teradata QD aborts startup. It is also possible to change the routing configuration file using the update command while Teradata QD is running. See Teradata Query Director Commands on page 61 for more information about the update command. -block No Specifies which Teradata QD command connections types are be blocked. Possible values are: socket: blocks socket connection -err_pref No Used to change either the default file name or default file directory for this error code file. The default error file name is err_pref.txt. When Teradata QD starts, it looks for this file in the specified location. If no location is specified, Teradata QD looks in the default directory. See Default Directory for Teradata QD Configuration Files on page 44 for more information. See Creating Error Code Files on page 40 for more information about creating and using an error code file. routing.cfg None err_pref.txt Teradata Query Director User Guide 47

48 Chapter 5: Teradata QD Operation Running Teradata QD from the Command Line Table 5: Teradata QD Startup Parameters (continued) Parameter Required Description Default -err_any No Used to change either the default file name or default file directory for this error code file. The default error file name is err_any.txt. When Teradata QD starts, it looks for this file in the specified location. If no location is specified, Teradata QD looks in the default directory. See Default Directory for Teradata QD Configuration Files on page 44 for more information. See Creating Error Code Files on page 40 for more information about creating and using an error code file. -err_exit No Used to change either the default file name or default file directory for this error code file. The default error file name is err_exit.txt. When Teradata QD starts, it looks for this file in the specified location. If no location is specified, Teradata QD looks in the default directory. See Default Directory for Teradata QD Configuration Files on page 44 for more information. See Creating Error Code Files on page 40 for more information about creating and using an error code file. err_any.txt err_exit.txt Running Teradata QD from the Command Line This section explains running Teradata QD from a command line. Typical Command Line Syntax The typical command line looks like this: Note: On Linux, the name of the executable is qrydir. >qd.exe -port keepalive 20 -tds b419:5001 -tds l route wrr -rcfg qdoverride.cfg -cport err_any error_file1.txt This command line does the following: qd.exe - Starts Teradata QD for Windows. Qrydir starts Teradata QD for Linux. -port - tells Teradata QD to listen on port 6025 for application connections. -keepalive 20 - sends keepalive probes after connection is idle for 20 minutes. -tds b419: Connects Teradata QD to tds b419. Tells tds b419 to listen for client applications on port Gives b419 the default 1 (since no weight is designated). -tds l Connects Teradata QD to tds l460. Give l460 the weight 4. -route wrr - Sets the routing algorithm to weighted round robin. -rcfg qdoverride.cfg - Names the routing configuration file qdoverride.cfg. -cport Tells Teradata QD to listen for Teradata QD commands at port err_any error_file1.txt - Tells Teradata QD that the err_any error code file is named error_file1.txt. 48 Teradata Query Director User Guide

49 Chapter 5: Teradata QD Operation Running Teradata QD as a Windows Service Starting and Stopping Teradata Query Director Start Teradata QD using a line command that contains the qd.exe executable as well as all the startup parameters that direct Teradata QD how to connect. The following is an example of a startup line command: qd.exe -port tds calico -tds gingham -loglevel 4 -logfile qdlog -rcfg c:\qdrouting.cfg See Setting Teradata Query Director Parameters on page 43 for more information on startup parameters. Stop Teradata QD by issuing a shutdown command through sockclient. Invoke sockclient using a line command in the following syntax: sockclient -command shutdown Teradata QD shuts down and sockclient terminates. See Shutdown Command on page 69 for more information about the shutdown command. Running Teradata QD as a Windows Service This section explains how to run Teradata QD as a Windows service. Note: Teradata QD as a service in not available in Linux. Using Microsoft Services Console Use the Microsoft services console to control Teradata QD when its running as a service. The service console is at Start> Administrative Tools> Services. The displayed name of the service is "Teradata QD." The registered name of the service is "tdqrydir". The service console can be used to start, stop, and restart Teradata QD. The Teradata QD service is automatically started when the PC is booted. If the connection is logged off, Teradata QD continues to run. Rebooting the system causes Teradata QD service to shutdown then auto-start. Teradata Query Director User Guide 49

50 Chapter 5: Teradata QD Operation Running Teradata QD as a Windows Service To start or stop Teradata QD as a service 1 Open the Services window. It is located at: Start> Administrative Tools> Services. Figure 6 shows the Services window with Teradata QD selected as a service. Figure 6: Microsoft Management Console window 2 Select Teradata QD from the list of Services. 3 Click Start to start Teradata QD or Stop to stop QD if its running already. Restart stops, then restarts Teradata QD. Note: Teradata QD service starts automatically when Window starts. To chance this, open the service console (Start> Administration Tools> Services), right-click Teradata QD and open Properties, then choose Manual from the Startup Type field. Creating a Parameter File for Teradata QD Windows Service When Teradata QD runs as a Windows service, it looks for the parameter file in the install directory. Teradata QD parameters are the same when Teradata QD runs as a service or runs from the line command with the following exceptions: Parameter names are not preceded with a '-' as is required for the command line. List one parameter per line in the parameter file. Text on a line following the '#' character is considered a comment and ignored by QD. To create a parameter file 1 Open any text editor such as Notepad. 2 Create a list of parameters following the guidelines above. See Setting Teradata Query Director Parameters on page 43 for a complete list of Teradata QD parameters. Below is an example of the formatting of a parameter file. 50 Teradata Query Director User Guide

51 Chapter 5: Teradata QD Operation Running Teradata QD as a Windows Service 3 Save the parameter file as tdqrydir.txt into the same directory Teradata QD was installed into. 4 Start or restart Teradata QD. See Using Microsoft Services Console on page 49 for more information. Example of a Parameter File Figure 7 shows and example of a parameter file for Teradata QD written in Notepad. Note the use of # to denote comments from commands. Figure 7: Example of a Parameter File in Notepad for Teradata QD Service. File Location When Teradata QD Runs as a Service When Teradata QD runs as a service, the install directory becomes the default directory for Teradata QD files. See Default Directory for Teradata QD Configuration Files on page 44 for more information about Teradata QD files locations. Viewing Teradata QD Messages with Event Viewer When Teradata QD is running as a service on Windows, Teradata QD service messages go to the Windows event log. The log can be viewed using Event Viewer. The procedure below shows how to open Event Viewer and view messages. To open the Event Viewer and view a Teradata QD message 1 Open Event Log as Start> Administrative Tools> Event Viewer. 2 In Event Viewer select Application from the directory panel. Teradata Query Director User Guide 51

52 Chapter 5: Teradata QD Operation Running Teradata QD as a Windows Service Figure 8: Event Viewer 3 Find messages about Teradata QD by looking under the Source column for tdqrydir. Double click on a tdqrydir message to open the message. Messages can be sorted. Figure 9: Teradata QD Message Window from Event Viewer How Teradata QD Logs Events as a Windows Service There are several error messages and plain messages that are unique to Teradata QD when running as a service. These messages go to the Windows event log. See Viewing Teradata QD Messages with Event Viewer on page 51 to learn how to use the Event Viewer to read these messages. Note: Stats that are repeatedly sent out every 30 seconds to stdout when Teradata QD is run from the command line, are not available when Teradata QD runs as a service. 52 Teradata Query Director User Guide

53 Chapter 5: Teradata QD Operation Session Balancing Session Balancing Teradata QD uses several routing algorithms to route sessions to designated systems using a set algorithm. This is called session balancing. The routing algorithm is passed to Teradata QD though the startup command line (or the parameter file if running as a service). See Setting Teradata Query Director Parameters on page 43 for more information. When Teradata QD runs as a Windows service, routing algorithms are passed through the parameter file. See Creating a Parameter File for Teradata QD Windows Service on page 50for more information. Session balancing applies to userid/account strings configured with Any system on the routing file. Userids configured as Named and Preferred do not use session balancing. See Creating a Routing Configuration File on page 38 for more information about the routing configuration file. Userids not listed in the routing file can be configured with session balancing. When a client starts a session, Teradata QD selects the first system (TDS) listed on the command line (or the parameter file if running as a service) and begins using the indicated routing algorithm. The routing algorithms include: Round Robin Weighted Round Robin Least Used Routing Note: If a userid is associated with a single system (Named) or a list of systems (Preferred) in the routing file, the routing algorithm is ignored for that userid. The following sections describe each routing algorithm. Round Robin Round Robin (RR) is the default routing algorithm. The Round Robin routing algorithm rotates each new session to the next listed system in the command line (or the parameter file if running as a service). If a session is connected to system A, Teradata QD sends the new session to system B and so on. For example, assume there are three systems, SysA, SysB and SysC. The first client logs on to SysA, the second to SysB, the third to SysC, the fourth to SysA, the fifth to SysB, and so on. It doesn't matter if a session ends. The RR algorithm is used by adding an rr to the command line (or the parameter file if running as a service) following a -route parameter. For example: >qd -tds b419 -tds l460 -tds route rr In this example, Teradata QD routes each session to the next system, starting with tds b419. Teradata Query Director User Guide 53

54 Chapter 5: Teradata QD Operation Log Files Weighted Round Robin Weighted round robin applies a weight to each listed system. The weight is a number that indicates how many session are directed to a system before the next system is used. For example, if a system is configured with a weight of 4, then the system is connected to 4 times in a row before Teradata QD moves to the next system. The WRR algorithm is started by adding a wrr to the command line (or the parameter file if running as a service) following a -route parameter. Then add the weighting to each system listed on the command line. For example: >qd -tds b tds l route wrr In this example, tds b419 is weighted at 4. Teradata QD directs 4 sessions to this system, then 2 sessions to the next system, then 4 sessions to the first system again. Least Used The Least Used (LU) routing algorithm selects the system with least active sessions. The least used algorithm is started by adding an lu to the command line (or the parameter file if running as a service) following a -route parameter. For example: >qd -tds b419 -tds l460 -route lu In this example, Teradata QD would monitor the connected sessions and direct new sessions to the system with the least number active sessions. Log Files Teradata QD creates a log file that records all the actions that Teradata QD performs. See Teradata Query Director Parameters on page 45 for more information about setting the log file parameters. The log file also records all error messages and is a good source of information if Teradata QD is having trouble. The location for the log file is the default directory or the directory specified on the command line or parameter file. See Default Directory for Teradata QD Configuration Files on page 44 for more information. Log File Naming Convention The default log file name, including the date, looks like this: qrydirlog_%y%m%d.txt. For user-specified log file names (-logfile parameter), the file name is appended with the "_%y%m%d" format. Teradata QD closes out the previous days log file and opens a new log file with the new date (%y%m%d") at 12:00 a.m. each day. If the new log file can not be opened, the old log file continues to be used. There are four types of log information: Information (I) 54 Teradata Query Director User Guide

55 Chapter 5: Teradata QD Operation Log Files Warning (W) Error (E) Debug (D) Status messages (A) A log line contains information about date, time, log line type (I, W, E, D, A), text number (for universal identification) and the text itself. Figure 10 shows an example of a log file. Figure 10: Typical Teradata QD Log File Table 6: Log File Description Column Item Description Shows the date. 10:16:17:202 Shows the time in hours, minute, seconds, micro seconds P-1868 Indicates the process ID. T-556 Shows the thread ID. Note: The thread ID on Linux is a large negative number Shows the message ID. See Teradata QD Messages on page 79 for a list of all Teradata QD messages. I, E, W, D, A Indicates the type of message shown in the log. I: information E: error W: warning D: debug A: Basic system status dir7s@0116 Shows the source code module and line number. : Teradata... Shows the message. Teradata Query Director User Guide 55