15.00 - Gateway Control Options - Teradata Database

Teradata Database Utilities

Product
Teradata Database
Release Number
15.00
Content Type
Configuration
Publication ID
B035-1102-015K
Language
English (United States)
Last Update
2018-09-25

Gateway Control Options

Gateway Control options are case sensitive and must include the hyphen prefix.

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, and indicates the operating systems that support each option.

 

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 factory default is ON.

    For additional information on External Authentication, see Security Administration.

    -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 factory default is 60 seconds.

    -d

    Displays current setting of the Gateway GDO.

    -e Eventcnt

    Specifies the number of event trace entries. The factory default is 500.

    -F

     

    Note: 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 factory default is OFF.

    For information about authentication methods, see Security Administration.

    -f Logfilesize

    Specifies the maximum log file size.

    The valid range is 1000 through 2147483647.

    The factory 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 factory default is 25.

    -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 factory default is 10 minutes.

    -L

    Toggles enable logons. The factory 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 factory default is 50.

    -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 “factory-set” gateway control defaults, and will be used for new host groups and gateway vprocs when the system is reconfigured.

    Note: 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 several 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 factory defaults, use the -Z option together with -o default.

    Note: The -o option cannot be used together with the -g or -v options.

    -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 factory default is 10 minutes.

    -s Sessions

    Specifies maximum sessions per gateway.

    The valid range is 1 through 2147483647.

    The factory default is 600.

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

    Note: During this time period, the session still counts against the number of sessions allocated to a PE.

    The factory default is 20 minutes.

    -u SendConnectRespIntegrityOnly

    Specifies whether the gateway sends connection responses encrypted.

    SendConnectRespIntegrityOnly' can be either of these values:

  • YES means the logon response is unencrypted plain text, but is secured from tampering.
  • NO means the logon response is encrypted. This is the default setting.
  • Note: Teradata recommends leaving this setting at the default of NO unless you are using 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.
  • Note: 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 factory 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 factory defaults, so new hosts and vprocs will use the original factory defaults, use the -Z option in conjunction with the ‑o default option:

    gtwcontrol -o default -Z

    Caution:

    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 factory default is OFF.

    -C

    Toggles connection tracing. The factory default is OFF.

    -D

    Toggles no gtwdie. The factory default is OFF.

    -E

    Toggles event trace. The factory default is OFF.

    The E event trace does not log the actions.

    -H

    Toggles connect heap trace. The factory default is OFF.

    -I

    Toggles interactive mode. The factory default is OFF.

    -J

    Toggles log LAN errors. The factory default is OFF.

    Logs any LAN-related errors even when properly handled by the gateway.

    -K

    Toggles session ctx lock trace. The factory default is OFF.

    This option shows the session locking to make the session context multiprocessor safe.

    -M

    Toggles message tracing. The factory default is OFF.

    -O

    Toggles output LAN header on errors. The factory default is OFF.

    Causes an error message to be written to the gateway log file.

    -R

    Toggles xport log all. The factory 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 Y trace is on.

    -S

    Toggles the action log. The factory 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 factory default is OFF.

    -U

    Toggles tdgss trace. The factory default is OFF.

    Note: 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 factory default is OFF.

    -X

    Toggles xport trace. The factory default is OFF.

    -Y

    Toggles handle trace. The factory default is OFF.