Syntax Elements - Advanced SQL Engine

-a ExternalAuthentication

Enables or disables external authentication, as follows:

ExternalAuthentication	Description
off	Rejects external authentication and accepts traditional logons.
on (Teradata default)	Accepts both external authentication and traditional logons.
only	Accepts external authentication and rejects traditional logons.

For additional information on External Authentication, see Teradata Vantage™ - Advanced SQL Engine Security Administration, B035-1100.

--auditnetsecurity[={yes|no|ct}]

Intended for use in security audits.

Changes to this setting affect only sessions that log on after the change.

Allows the gateway to log the level of encryption used by client interfaces that communicate with the gateway, as follows:

Option	Description
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 this option 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).

This information is recorded in the gateway logs.

-b { socketbuffersize | default | auto }

Specifies the SND and RCV buffer sizes, as follows:

Option	Description
socketbuffersize	Specifies the buffer size in bytes. The valid range is 65588 through 2147483647 bytes.
default	Specifies to use the default setting. The gateway chooses the default setting that is appropriate for most circumstances. This setting is set automatically by the Linux auto-tuning feature, but depends on the database software release. 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.
auto

-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 [ OFF | ON ]

This option is deprecated. Do not use.

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.

There are two types of threads:

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

This option is intended for use with Teradata Unity.

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.

EnableChannelBinding can be yes or no.

For more information on TDGSS, see Teradata Vantage™ - Advanced SQL Engine Security Administration, B035-1100.

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

If the value is changed, a database restart is necessary for it to take effect.

The Teradata default is 10 minutes.

-L [ OFF | ON ]

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.

There are two types of threads:

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 suboption [,…]

Used to control a loadable library for database monitoring. Such libraries are provided by third-party providers of Database Activity Monitoring tools.

suboption

Description

load=[yes|no]

yes	Loads the monitoring library.
no (default)	Disables the library if it has been loaded. If the library has been disabled by setting this value to no, it will not be reloaded 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, as follows:

no (default)	Passes the original data buffer directly to the monitoring tools.
yes	Creates a dynamic data buffer, copies the data from the original 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, as follows:

yes (default)	Causes the monitoring library to log only error messages.
no	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, as follows:

EnableDeprecatedMessages	Description
no (default)	Causes Vantage to return only generic logon failure error messages to users who attempt to logon unsuccessfully.
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.

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

The -o option cannot be used with the -g or -v option.

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 this option with the -Z option.

-p LocalPEPreferredPercent

Determines the Vantage 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) or assigning the session to a remote PE (a PE on a different node).

LocalPEPreferredPercent 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. LocalPEPreferredPercent is in the range [0, 100]:

LocalPEPreferredPercent	Description
0 (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.
100	Gives local PEs preference, even if remote PEs have more available session capacity.
1 through 99	Gives 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.

There are two types of threads:

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 suboption [,…]

Changes to this setting do not affect sessions logged on at the time of the change.

This option allows the gateway to accept logons from older client software or proxies that do not support Teradata 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 Vantage on behalf of other clients. Currently, Teradata® Unity™ is the only proxy.

suboption

Description

logon=[no|all|client|proxy]

no (default)	The gateway does not allow logons using clients or proxies that are unable to support security policy when policy applies.
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 (default)	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.
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.

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

Configures TLS and turns on diagnostic trace.

Changes to the disable|enable|require|nolegacy setting take effect after the next database restart.

Option

Description

enable

Default. The gateway listens to both the HTTPS port (default is 443) and the legacy port (default is 1025) and accepts a new TLS connection through the HTTPS port and a new legacy connection through the legacy port.

If the TLS flag is enabled, but there is not a valid certificate-private key pair installed on the node, the gateway will not be able to listen to the HTTPS port until a valid certificate-private key pair is installed.

disable

The gateway does not listen to the HTTPS port. It only listens to the legacy port and accepts a new legacy connection through the legacy port.

require

The gateway listens to both the HTTPS port and the legacy port and only accepts a new TLS connection through the HTTPS port. The gateway returns an error to the client application if it receives a legacy connection request from the legacy port.

nolegacy

The gateway only listens to the HTTPS port and accepts a new TLS connection through the HTTPS port. The gateway no longer listens to the legacy port.

trace=no|yes|all

no (default)	The gateway only logs severe error events.
yes	The gateway logs both error and informational messages.
all	The gateway logs all messages, including errors, informational, and diagnostic logs.

-u SendConnectRespNoSecurity

Specifies whether the gateway sends connection responses encrypted or cleartext, as follows:

SendConnectRespNoSecurity	Description
no (default)	The logon response is encrypted.
yes	The logon response is in cleartext (unencrypted plain text).

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

Changes to this setting affect only sessions initiated after the change. To ensure that encryption is enforced on all sessions, Teradata recommends that the Teradata system be in a quiescent state (no users logged on) when -x is changed to yes.

Determines whether the gateway requires that input messages be encrypted. The output from the gateway matches the security level of the input it receives, as follows:

RequireConfidentiality	Description
no (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.

RequireConfidentiality

Description

no (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.

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

-1 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 options 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.

Syntax Elements - Advanced SQL Engine - Teradata Database

Database Utilities