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 1where 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 600The following table describes the options for the Gateway Control utility.
Option | Description |
---|---|
-a ExternalAuthentication | Enables or disables external authentication. The settings are as follows:
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:
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:
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:
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:
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:
|
-n EnableDeprecatedMessages | Enables deprecated, descriptive logon failure error messages.
EnableDeprecatedMessages can be one of the following:
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.
|
-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:
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:
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:
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:
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 |
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 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. |