Share this page

# web_set_sockets_option

Sets an option for sockets.

## C Language

    int web_set_sockets_option( const char *option, const char *value );

Miscellaneous Functions

## Java Language

    int object.set_sockets_option( String option, String value );

Miscellaneous Functions | Java Syntax

Argument | Description
--- | ---
object | An expression evaluating to an object of type WebApi. Usually web for Java. See also Function and Constant Prefixes.
option | The option whose value you want to set.
value | The value of the specified option.

## Return Values

This function returns LR_PASS (0) on success, and LR_FAIL (1) on failure.

## Parameterization

The following argument(s) can be parameterized using standard parameterization: OptionID, OptionValue

## General Information

The web_set_sockets_option function configures options for sockets on the client machine. This function supports socket-level replay. In the Web HTML protocol, it supports both HTML-based scripts (Mode=HTML) and URL-based scripts(Mode=HTTP modes). web_set_sockets_option has no effect on replay using WinInet.

To print a list of the supported options, specify the HELP flag with a null string and execute the function. A list of all the available options is displayed in the Output window's Execution log.

For options that enable or disable a feature (such as TRACE_SSL_IO), specify `"1"` to enable and `"0"` to disable.

Supported Options
ALLOW_ONLY_HOSTS | Only allows requests to servers in the list. (see also DISALLOW_HOSTS option). Only use under Sockets. Do not use wildcards or other regular expressions in value.
CHECK_CONNECTION_ABORT_DURING_RECEIVE | If server has aborted the connection during reading from the socket, treat it as if the socket has been closed. Default: True
CLOSE_KEEPALIVE_CONNECTIONS | Closes all open connections.
DEFAULT_VERIFY_PATH | A directory containing a list of Certificate Authority files (in PEM format).
DESPAIR_TIMEOUT | Timeout to wait for useless body. An example would be the body of an HTTP 302 response (Moved Temporarily). Default: 2 seconds
DISALLOW_HOSTS | Ignores all requests to the listed servers. This option is useful for excluding resources that come from external sites. For example, you can use this option to exclude advertisements that are hosted on external servers. Only use under Sockets. Do not use wildcards or other regular expressions in value.
HELP | Output information about the available options to the execution log. This is useful during development. Use an empty string ("") for value.
IGNORE_PREMATURE_SHUTDOWN | Do not consider server closing the connection prematurely as error. Default: False
INITIAL_AUTH | Force sending user credentials with the first request without waiting for HTTP 401. For example, `web_set_sockets_option("INITIAL_AUTH", "NTLM");`
IP_ADDRESS_BY_INDEX | Sets the IP address of the client machine to be the nth address on the client machine. This option is useful for IP spoofing. If this option is used, lr_get_vuser_ip returns the IP set with this call.
LOAD_VERIFY_FILE | Load the certificate file in PEM–format. The file contains a list of Certificate Authorities.
MAX_CONNECTIONS_PER_HOST | Specifies the maximum number of concurrent connections per host. Default: 6
MAX_TOTAL_CONNECTIONS | Specifies the global maximum number of simultaneous connections per Vuser. Default: 16
NO_DELAY | Set the TCP_NODELAY option on the socket – it will prevent the socket from accumulating small buffers to larger ones before sending. Default: False
NO_STARVATION | Prevent starvation from sockets (false by default).
NEW_BEHAVIOR_OF_OVERLAPPED_SEND | If overlapped send is available, use IBM specific method (false by default). Use when there are retries in the transaction breakdown results an IBM server.
NTLM_USE_REAL_CLIENT_HOST_NAME | Use the real client host name in NTLM authentication instead of the default 'dummy_host'. Set to "1" to activate. Default: "0"
OVERLAPPED_SEND | When set to 0, this option disables the breakdown of the "First Buffer" into server and network time. The breakdown remains disabled until you enable it by setting the option's value to 1. This option is primarily used when encountering the following error: "Error -27740: overlapped transmission of request". Place the following statement web_set_sockets_option("OVERLAPPED_SEND", "0") at the beginning of the script, to prevent this error.
PRINT_SSL_INFO | Print information about SSL connections to brief log. Value of zero in quotes ("0") suppresses output. Any other integer (for instance, "1", "–3", and so forth) enables output.
PRINT_USER_IP_ADDRESS_LIST | Output a list of IP addresses available on a given machine to the execution log. value is the name of the machine.
PROXY_INITIAL_AUTH | Force sending user credentials to proxy server with the first request. For example, `web_set_sockets_option("PROXY_INITIAL_AUTH", "NTLM");`
PROXY_INITIAL_BASIC_AUTH | If enabled, send basic authentication to proxy before receiving 407 error. If disabled, send the regular header in the first request. Default: Enabled.
SHUTDOWN_MODE | Controls how ports are shutdown and disconnected from the TCPIP connection: GRACEFUL (default), FAST, or ABRUPT. See Shutdown Mode Option.
SO_REUSE_ADDRESS | Enable the reuse of ports (currently not supported).
SSL_CIPHER_LIST | A list of colon–delimited SSL ciphers to use for SSL connections. For the list of ciphers, see the Cipher List.
SSL_NO_PROXY_TUNNEL | Default: False
SSL_VERSION | The SSL version preference: 2, 3, 2&3, TLS, TLS1.1, TLS1.2, TLS1.3, or AUTO
STRONG_PRNG | Uses a strong pseudo–random number generator to generate SSL keys. (disabled by default) Although the standard (non–strong) random number generator is more predictable, it is more efficient. Warning: This option is not thread–safe.
SYNCHRONOUS_CONNECT | Specify blocking connect.
TCP_BUFFER_SIZE | Set the TCP send and receive buffer size.
TLS_SNI | The Server Name Indication (SNI) extension configuration. One of: 1 - Enable extension (default) 0 - Disable extension <server name> - If a server name is specified, that server name is used once: for the next handshake. After the next handshake, the option reverts to the previous setting, 1 or 0.
TRACE_SSL_IO | Performs a raw trace of all bits sent through the SSL connection.
UPLOAD_CHUNK_SIZE | Set maximum chunk size for large request body. Default: 64*1024 bytes
USE_SELECT | Use standard select() instead of responsive select. Default: False
USER_IP_ADDRESS | Sets the preferred IP address of client <ip_addr>[:<port>]. This option is useful for IP spoofing.

This function is supported for all web scripts. The `USER_IP_ADDRESS` setting is supported under WSP.

## Cipher List

The suggested ciphers for `SSL_CIPHER_LIST` are:

`"TLS_AES_256_GCM_SHA384","TLS_CHACHA20_POLY1305_SHA256","TLS_AES_128_GCM_SHA256","ECDHE-ECDSA-AES256-GCM-SHA384","ECDHE-RSA-AES256-GCM-SHA384","DHE-RSA-AES256-GCM-SHA384","ECDHE-ECDSA-CHACHA20-POLY1305","ECDHE-RSA-CHACHA20-POLY1305","DHE-RSA-CHACHA20-POLY1305","ECDHE-ECDSA-AES128-GCM-SHA256","ECDHE-RSA-AES128-GCM-SHA256","DHE-RSA-AES128-GCM-SHA256","ECDHE-ECDSA-AES256-SHA384","ECDHE-RSA-AES256-SHA384","DHE-RSA-AES256-SHA256","ECDHE-ECDSA-AES128-SHA256","ECDHE-RSA-AES128-SHA256","DHE-RSA-AES128-SHA256","ECDHE-ECDSA-AES256-SHA","ECDHE-RSA-AES256-SHA","DHE-RSA-AES256-SHA","ECDHE-ECDSA-AES128-SHA","ECDHE-RSA-AES128-SHA","DHE-RSA-AES128-SHA","RSA-PSK-AES256-GCM-SHA384","DHE-PSK-AES256-GCM-SHA384","RSA-PSK-CHACHA20-POLY1305","DHE-PSK-CHACHA20-POLY1305","ECDHE-PSK-CHACHA20-POLY1305","AES256-GCM-SHA384","PSK-AES256-GCM-SHA384","PSK-CHACHA20-POLY1305","RSA-PSK-AES128-GCM-SHA256","DHE-PSK-AES128-GCM-SHA256","AES128-GCM-SHA256","PSK-AES128-GCM-SHA256","AES256-SHA256","AES128-SHA256","ECDHE-PSK-AES256-CBC-SHA384","ECDHE-PSK-AES256-CBC-SHA","SRP-RSA-AES-256-CBC-SHA","SRP-AES-256-CBC-SHA","RSA-PSK-AES256-CBC-SHA384","DHE-PSK-AES256-CBC-SHA384","RSA-PSK-AES256-CBC-SHA","DHE-PSK-AES256-CBC-SHA","AES256-SHA","PSK-AES256-CBC-SHA384","PSK-AES256-CBC-SHA","ECDHE-PSK-AES128-CBC-SHA256","ECDHE-PSK-AES128-CBC-SHA","SRP-RSA-AES-128-CBC-SHA","SRP-AES-128-CBC-SHA","RSA-PSK-AES128-CBC-SHA256","DHE-PSK-AES128-CBC-SHA256","RSA-PSK-AES128-CBC-SHA","DHE-PSK-AES128-CBC-SHA","AES128-SHA","PSK-AES128-CBC-SHA256","PSK-AES128-CBC-SHA"`"

Note: Some ciphers are not supported by HTTP/2. The cipher suite blacklist can be found in article RFC 7540 (Appendix A. TLS 1.2 Cipher Suite Black List).

## Shutdown Mode Option

Some clients and servers do not terminate connections cleanly. The result is that connections may get trapped in wait states during tests, draining networking resources. The following options are provided to solve this problem. The correct choice depends on your system and networking environment.

GRACEFUL (default) – a full shutdown sequence. This is the normal mode of shutdown – a 4–way handshake between the web client and server. If any of the following occur, consider changing to the ABRUPT option:

- Connections fail during Vuser loading

- While using the netstat application, many sockets are found to be in the WAIT state

- The handle count of driver mmdrv rises during the running of the Vusers

- A "No buffer space available" error message when trying to establish a connection

ABRUPT: a reset packet is sent to the web server causing it to close the connection. Note, however, that servers sometimes do not receive the packet or do not successfully execute cleanup operations. This usually results in dead connections.

FAST: a compromise between GRACEFUL and ABRUPT. A full shutdown sequence is initiated by the web client with a very fast timeout.

## C Example

In the following example, the web_set_sockets_option function sets a cipher list:

    /* Use RC4-MD5 cipher for SSL */
    web_set_sockets_option("SSL_CIPHER_LIST", "RC4-MD5");
    /* Prevent downloading of images from unwanted_server */
    web_set_sockets_option("DISALLOW_HOSTS",
        "a372.g.unwanted_server.net;a372.g.unwanted_server.net");
    /* Sets the client's preferred IP address */
    web_set_sockets_option("USER_IP_ADDRESS", "200.100.100.100");

In the following examples, the web_set_sockets_option function performs pre-emptive authentication.

    // Turn on pre-emptive authentication for web server. The pre-emptive authenticate scheme is always “BASIC”.
    web_set_sockets_option("INITIAL_AUTH","BASIC");

    // Turn on pre-emptive authentication for web server. The pre-emptive authenticate scheme is always “NTLM”.
    web_set_sockets_option("INITIAL_AUTH","NTLM");

    // Turn on pre-emptive authentication for web server. The pre-emptive authenticate scheme is always “KERBEROS”.
    web_set_sockets_option("INITIAL_AUTH","KERBEROS");

    // Turn off pre-emptive authentication for web server.
    web_set_sockets_option("INITIAL_AUTH","NONE");

    // Do the same for proxy server.
    web_set_sockets_option("PROXY_INITIAL_AUTH","BASIC");
    web_set_sockets_option("PROXY_INITIAL_AUTH","NTLM");
    web_set_sockets_option("PROXY_INITIAL_AUTH","KERBEROS");
    web_set_sockets_option("PROXY_INITIAL_AUTH","NONE");

## Java Example

In the following example, the function sets a cipher list:

    /* Use RC4-MD5 cipher for SSL */
    web.set_sockets_option("SSL_CIPHER_LIST", "RC4-MD5");
    /* Prevent downloading of images from unwanted_server */
    web.set_sockets_option("DISALLOW_HOSTS",
        "a388.g.unwanted_server.net;a372.g.unwanted_server.net");
    /* Sets the client's preferred IP address */
    web.set_sockets_option("USER_IP_ADDRESS", "200.100.100.100");

Tips to improve your search results... VuGen Function Reference Version 26.1 Function Reference 26.1 All View Local Help Center View Online Help Center Version: