Gateway Control Options - Advanced SQL Engine

Gateway Control options are case sensitive and must include the hyphen prefix. Note that some options are preceded by two hyphens.

The following example gives the syntax for the help option which lists the syntax for all other gateway control options:

gtwcontrol -h

When a gateway option requires a field value, that option includes a field name where you define the value.

For example, to select the host group number 1 on which to perform an action, use the option -g Hostnumber and type:

gtwcontrol -g 1

where the Hostnumber for the option is 1.

You can combine options by typing them, separated by a space.

For example, to set the maximum number of sessions for host group 1 to 600, type:

gtwcontrol -g 1 -s 600

The following table describes the options for the Gateway Control utility.

Option	Description
-a ExternalAuthentication	Enables or disables external authentication. The settings are as follows: OFF rejects external authentication and accepts traditional logons. ON accepts both external authentication and traditional logons. ONLY accepts external authentication and rejects traditional logons. The Teradata default is ON. For additional information on External Authentication, see Teradata Vantage™ - Advanced SQL Engine Security Administration, B035-1100.
--auditnetsecurity[={yes\|no\|ct}]	Allows the gateway to log the level of encryption used by client interfaces that communicate with the gateway. This information is recorded in the gateway logs. Intended for use in security audits. Options: yes The gateway logs the security level of the first message after the Connect message that logs the session on. Thereafter, the gateway logs any change in the security level of incoming messages. This is the default if you do not specify yes, no, or ct. no The gateway does not log the security level of incoming messages. This is the initial setting for this option and the Teradata default. (The gtwcontrol -Z option resets --auditnetsecurity to "no".) ct The gateway logs the security level of incoming messages that are "cleartext" security level (messages that are not explicitly a "Confidentiality" level). Changes to this setting affect only sessions that log on after the change.
-b socketbuffersize	Specifies the SND and RCV buffer sizes. socketbuffersize specifies the buffer size in bytes. The valid range is 65588 through 2147483647 bytes, or you can specify one of the following special values: default specifies to use the default setting. By default, the gateway chooses a specific setting that is appropriate for most circumstances. The specific setting the gateway chooses can vary from release to release of Teradata Database. Currently, this setting specifies that the buffer size should be set automatically by the Linux auto-tuning feature. auto specifies that the buffer size should be set automatically by the Linux auto-tuning feature. Unless you are thoroughly familiar with TCP/IP and SND/RCV buffer sizing, you should only change this setting under the direction of Teradata Support Center personnel.
-c connectiontimeout	Controls the logon message timeout in seconds. The Gateway terminates any session for which a message in the logon sequence is not received in a timely manner. The turnaround time for any message during the logon should be less than the value in the connectiontimeout setting. The value ranges from 5 to 3600 seconds. The Teradata default is 60 seconds.
-d	Displays current setting of the Gateway GDO.
-e Eventcnt	Specifies the number of event trace entries. The Teradata default is 500.
-F	This option is deprecated, and should not be used. Toggles “append domain names” for authentication schemes in which domain names are required to define user identities uniquely. The Teradata default is OFF. For information about authentication methods, see Teradata Vantage™ - Advanced SQL Engine Security Administration, B035-1100.
-f Logfilesize	Specifies the maximum log file size. The valid range is 1000 through 2147483647. The Teradata default is 5000000.
-g Hostnumber	Specifies a host group to which the host-specific settings in this invocation of gtwcontrol will be applied. If you do not specify this option, the host settings are applied to all host groups. Hostnumber is an integer from 0 through 1023 that identifies a host group. The host-specific options are: -a, -b, -c, -i, -k, -m, -r, -s, -t, -A, -F, -C and -T.
-h	Displays help on gtwcontrol options.
-i InitialIothreads	Specifies the number of threads of each type that are started initially for the processing of LAN messages. When adjusting the number of threads to match the load, the number of threads of each type will never be reduced below this number. Two types of threads exist: One handles traffic from the client (that is, TCP/IP connections). One handles traffic from the database (that is, the PDE msgsystem). The Teradata default is 25.
-j EnableChannelBinding	Enables binding TDGSS-API authentication mechanisms to secure channels at lower network layers for those mechanisms that support channel binding. (PROXY is the only mechanism that currently supports channel binding.) Channel binding verifies the endpoints of the lower level network layers to eliminate man-in-the-middle attacks. In the case of the PROXY mechanism, channel binding also makes it more difficult to use stolen certificates to pretend to be a legitimate endpoint. Values for EnableChannelBinding can be YES or NO. For more information on TDGSS, see Teradata Vantage™ - Advanced SQL Engine Security Administration, B035-1100. This option is intended for use with Teradata Unity.
-k keepalivetimeout	Specifies how long the connection between the gateway and a client remains idle before the operating system begins probing to see if the connection has been lost. keepalivetimeout specifies the time in minutes, and can be any integer from 1 through 120. When a connection has been idle for the specified number of minutes, the gateway’s operating system will send a keepalive message over the connection to see if there is a response from the client’s operating system. If there is no response, the gateway’s operating system repeats the probe several times. If there continues to be no response from the client’s operating system, the gateway’s operating system closes the connection, disconnecting the session using it. The specific number of probes and the time between probes vary by operating system type. Some systems allow these values to be changed when networking is configured. If these values have not been changed, it typically takes about 10 minutes from the first probe until a dead connection is closed. If the keepalivetimeout value is 5, the actual time until the connection is closed is approximately 15 minutes. The Teradata default is 10 minutes.
-L	Toggles enable logons. The Teradata default is ON.
-m MaximumIothreads	Specifies the maximum number of threads per type. When adjusting the number of threads to match the load, the number of threads of each type will never be increased above this number. Two types of threads exist: One handles traffic from the client (that is, TCP/IP connections). One handles traffic from the database (that is, the PDE msgsystem). The Teradata default is 50.
--monitorlib suboptions	Used to control a loadable library for database monitoring. Such libraries are provided by third-party providers of Database Activity Monitoring tools. suboptions is a comma-separated list of one or more of the following name=value pairs: load=[yes\|no] YES loads the monitoring library. (By default, the library is unloaded.) NO disables the library, if it has been already loaded. If the library has been disabled by setting this value to NO, it will not be re-loaded by setting this value to YES until after the next database restart. copy=[no\|yes\|verify] Determines the method used by the gateway to pass database data. NO (the default) passes the original Teradata Database data buffer directly to the monitoring tools. YES creates a dynamic data buffer, copies the data from the original Teradata Database data buffer to the new buffer, and sends the new data buffer to the monitoring tools of the third-party monitoring provider. VERIFY implies copy=yes, and causes the gateway to compare the data in the new and original data buffers (after sending the new data buffer to the monitoring tools), to verify that the monitoring tools did not change any data in the new data buffer. trace=[yes\|no\|all] Controls the diagnostic trace facility of the monitoring library: NO causes the monitoring library to log only error messages. This is the default. YES causes the monitoring library to log both error and warning messages. ALL logs all messages, including errors and warnings, and any other types of messages the monitoring library can provide.
-n EnableDeprecatedMessages	Enables deprecated, descriptive logon failure error messages. EnableDeprecatedMessages can be one of the following: NO causes Teradata Database to return only generic logon failure error messages to users who attempt to logon unsuccessfully. This is the default setting. YES returns less secure, more descriptive logon failure error messages. Database errors that are returned to users during unsuccessful logon attempts often provide information regarding the cause of the logon failure. This information could pose a security risk by helping unauthorized users gain entry to the system. By default, Teradata Database returns only a generic logon error message. Users who attempt to log on to the system unsuccessfully will see a message indicating only that the logon failed, without indicating the reason why. Regardless of this setting, more detailed information about logon failures is always logged to the system logs and to the DBC.eventlog system table, which system administrators can use to determine the reasons for specific logon failures. Administrators can also inspect these logs for repeated unsuccessful logon attempts that might indicate attempts to breach system security.
-o default	Indicates that the other options specified in this invocation of gtwglobal should be saved as a set of user-defined default values. These defaults take precedence over the Teradata gateway control defaults, and will be used for new host groups and gateway vprocs when the system is reconfigured. Host groups and vprocs that existed before the reconfiguration retain their previous settings. To apply the custom defaults to all existing host groups and vprocs, use the -z option. gtwcontrol -o default can be run multiple times to set individual default values or groups of values. Subsequent runs do not cancel previous runs. To clear the user-defined defaults and restore the Teradata defaults, use the -Z option together with -o default. The -o option cannot be used together with the -g or -v options.
-p LocalPEPreferredPercent	Determines the Teradata Database preference or bias for assigning a new session to a local PE (a PE on the node containing the gateway that accepted the logon request) versus assigning the session to a remote PE (a PE on a different node). LocalPEPreferredPercent can be an integer from 0 (the default) to 100. The value is a measure of how much difference in relative available capacity (as a percentage) is tolerable when deciding to choose a local PE. Higher values result in a greater preference given to assigning new sessions to local PEs. A value of zero percent, the default, gives local PEs preference if the remaining available session capacity is identical for the least busy local and remote PEs. If a remote PE has more session capacity available than the local PE, the session is assigned to the remote PE. A value of 100 gives local PEs preference, even if remote PEs have more available session capacity. Values from 1 to 99 give increasing levels of preference to local PE assignment, so a local PE may get the session even if a remote PE has more session capacity available.
-r IoThreadCheck	Determines the frequency in minutes that the gateway checks to see if all the threads are busy. If they are all busy, a new thread of the appropriate type is started unless it will exceed the maximum number of threads set by the -m option. If more than one thread has not run during the IoThreadCheck period, the gateway stops a thread, unless it will leave fewer threads than are specified by the -i option. Two types of threads exist: One handles traffic from the client (that is, TCP/IP connections). One handles traffic from the database (that is, the PDE msgsystem). The Teradata default is 10 minutes.
-s Sessions	Specifies maximum sessions per gateway. The valid range is 1 through 2147483647. The Teradata default is 600.
--secpcynotsupported suboptions	This option allows the gateway to accept logons from older client software or proxies that do not support Teradata Database network security policy, even when security policy applies. Additionally, it allows you to have the gateway log messages that identify these older clients or proxies. You can use these log messages to help identify older clients that should be replaced or upgraded. Proxies are special clients that use the TDGSS PROXY authentication mechanism to communicate with Teradata Database on behalf of other clients. Currently, Teradata® Unity™ is the only proxy. suboptions is a comma-separated list of one or both of the following name=value pairs in any order: logon=[no\|all\|client\|proxy] no The gateway does not allow logons using clients or proxies that are unable to support security policy when policy applies. This is the default. all The gateway allows logons using clients or proxies that are unable to support security policy. client The gateway allows logons using clients that are unable to support security policy, but does not allow logons using proxies that are unable to support security policy when policy applies. proxy The gateway allows logons using proxies that are unable to support security policy when policy applies. Because such proxies provide no information about the security policy capabilities of the clients that connect through them, logons using these clients are allowed, whether the client supports security policy or not. For logon=all or logon=proxy, clients can logon through proxies that do not support security policy. These proxies cannot guarantee that the clients follow policy, nor can they transmit policy to clients that could otherwise follow it. For this reason, all clients that log on through such proxies must be manually configured to be within policy, even if they are otherwise capable of following policy automatically. In practice, the gateway can identify security violations by client sessions logged on through such a proxy and log them off, but not until after a single out-of-policy message has already been sent. For logon=all or logon=client, a client that has not been manually configured to be within policy can send a single out-of-policy message per session before the security violation is caught and the session is logged off. log=[no\|all\|client\|proxy] no The gateway does not log a message to the gateway log files to identify older clients or proxies that are unable to support security policy. This is the default. all The gateway logs a message in a gateway log file when an attempt is made to log on using a client or proxy that is unable to support security policy. client The gateway logs a message in a gateway log file when an attempt is made to log on using a client that is unable to support security policy. The gateway does not log a message if a logon attempt uses a proxy that is unable to support security policy, because such a proxy is incapable of telling the gateway when the client does not support security policy. proxy The gateway logs a message in a gateway log file when an attempt is made to log on through a proxy that is unable to support security policy . Changes to this setting do not affect sessions logged on at the time of the change.
--shutdowntimeout Timeoutvalue	Sets the amount of time a client is allowed to take after the gateway does a partial TCP/IP socket close until the client must complete the close. The gateway does an abortive close to preemptively free the socket if the client does not complete the close in time. Timeoutvalue is a value from 5 through 3600 seconds. The Teradata default is 60 seconds. The default value is suitable for most situations. Before you change this setting, consult with Teradata Support Center personnel.
-t Timeoutvalue	Determines how long a disconnected session has to reconnect in minutes. If the client has not reconnected within the specified time period, the client is logged off automatically. During this time period, the session still counts against the number of sessions allocated to a PE. The Teradata default is 20 minutes.
-u SendConnectRespNoSecurity	Specifies whether the gateway sends connection responses encrypted or cleartext. SendConnectRespNoSecurity can be either of these values: YES means the logon response is in cleartext (unencrypted plain text). NO means the logon response is encrypted. This is the default setting. Teradata recommends that you use the default setting unless you use third-party activity-monitoring software that requires access to the contents of the connection responses.
-v Vprocnumber	Specifies a vproc to which the vproc-specific settings in this invocation of gtwcontrol will be applied. If you do not specify this option, the vproc-specific settings apply to all vprocs. Vprocnumber is an integer from 0 through 30719 that identifies a vproc. The vproc-specific options are: -C, -D, -E, -H, -J, -K, -M, -O, -R, -S, -W, and -Y.
-x RequireConfidentiality	Determines whether the gateway requires that input messages be encrypted. The output from the gateway matches the security level of the input it receives. RequireConfidentiality can be set to either of these values: NO (the default) does not require that input messages be encrypted. YES requires input messages to be encrypted. The messages will automatically be encrypted by a client that supports the Enforce Network Security Policy feature, see Security Administration. Gateway will automatically force a session off if a message is received that is not encrypted. The following message types will be accepted, even if they are not encrypted: test, abort, assign, reassign, methods, SSO, logoff, or config. Changes to this setting affect only sessions initiated after the change. To ensure that encryption is enforced on all sessions, Teradata recommends that Teradata Database be in a quiescent state (no users logged on) when -x is changed to YES.
-z	Sets gateway control to apply the user-defined defaults created with the -o default option to all current host groups and vprocs.
-Z	Sets gateway control to apply the original Teradata defaults to all current host groups and vprocs. If a set of user-defined defaults, created with the -o default option exist, they will still be applied to new host groups and vprocs after a reconfiguration. To reset these user-defined defaults to the original Teradata defaults, so new hosts and vprocs will use the original Teradata defaults, use the -Z option in conjunction with the -o default option: gtwcontrol -o default -Z

The following options should be used only for debugging the gateway under the direction of Teradata Support Center personnel.

Option	Description
-l logonname	For remote gateway global access.
-A	Toggles assign tracing. The Teradata default is OFF.
-C	Toggles connection tracing. The Teradata default is OFF.
-D	Toggles no gtwdie. The Teradata default is OFF.
-E	Toggles event trace. The Teradata default is OFF. The E event trace does not log the actions.
-H	Toggles connect heap trace. The Teradata default is OFF.
-I	Toggles interactive mode. The Teradata default is OFF.
-J	Toggles log LAN errors. The Teradata default is OFF. Logs any LAN-related errors even when properly handled by the gateway.
-K	Toggles session ctx lock trace. The Teradata default is OFF. This option shows the session locking to make the session context multiprocessor safe.
-M	Toggles message tracing. The Teradata default is OFF.
-N	Toggles logging of security mechanism selection by TDNEGO. Used for troubleshooting if TDNEGO is choosing the wrong security mechanism. The Teradata default is OFF.
-O	Toggles output LAN header on errors. The Teradata default is OFF. Causes an error message to be written to the gateway log file.
-R	Toggles xport log all. The Teradata default is OFF. By default, the xport trace does not log every LAN operation. The xport log all option causes all LAN operations to be logged. This option only takes effect if the X trace is on.
-S	Toggles the action log. The Teradata default is OFF. The S option turns on the action trace. The S option only takes effect if the E trace is on.
-T	Toggles allow gateway testing. The Teradata default is OFF.
-U	Toggles tdgss trace. The Teradata default is OFF. The -U option causes tdgss-related errors to be logged into the gateway log file for the purpose of diagnosing problems.
-W	Toggles wait for debugger to attach. The Teradata default is OFF.
-X	Toggles xport trace. The Teradata default is OFF.
-Y	Toggles handle trace. The Teradata default is OFF.

Gateway Control Options - Advanced SQL Engine - Teradata Database

Database Utilities