Setting SQL OpenNet client options in net.ini

The net.ini file enables you to specify a client-side encryption key, client options for SSL encryption, and other SQL OpenNet client settings.

When you install Connectivity Series, the installation creates a default net.ini file with a default encryption setting in the connect\synodbc\lib directory. This file is not overwritten when you upgrade Connectivity Series, nor is it removed when you uninstall. We also distribute a file named net_base.ini (located in the same directory), which contains the default settings and can be used as a reference. The net_base.ini file is overwritten when you upgrade Connectivity Series.

The primary purpose of the net.ini file is to enable you to specify an encryption key for the client using the key_connect setting and to specify SSL settings. We recommend that you not change any other settings. However, it is important that you change the default key_connect setting in net.ini because the default is widely-used and therefore not secure.

Important

The net.ini file must be located on the client in the lib subdirectory of the directory specified by the VORTEX_HOME environment variable. The Connectivity Series installation (Windows), setsde (UNIX), or SYS$MANAGER:CONNECT_STARTUP.COM (OpenVMS) sets VORTEX_HOME to point to the connect\synodbc directory, which contains the \lib subdirectory where net.ini is located. Do not change this setting.

We recommend that you have only a single net.ini file on the client machine. xfODBC checks the current directory before VORTEX_HOME\lib, so additional net.ini files in other locations may be used and could cause an “Invalid connect syntax” error.

On Windows, because VORTEX_HOME is set at the system level, if you install both 64-bit and 32-bit Connectivity Series on the same 64-bit machine, the last version installed determines the VORTEX_HOME setting by overwriting the previous setting.

Do not include any control characters in the net.ini file; they will cause an “invalid integer” error when connecting with SQL OpenNet.

SQL OpenNet Client Options (net.ini file settings)

Option

Description and syntax

connect_timeout

Specifies the number of seconds for socket connection time-out. The default is 0 (no time-out). To set this, use the following syntax, where n is the number of seconds:

connect_timeout n

hostenv0

Specifies a comma-delimited list of environment variables to be passed to and set on the server.

hostenv0 var_name=var_spec[,var_name2=var_spec2,...]

key_connect

Specifies a key for the algorithm used to encrypt user names and passwords for the database and for the host (if vtxnetd or vtxnet2 is also started with the -k option). This encrypts user names and passwords being sent across the wire. Use the following syntax:

key_connect n

where n is any number between 1 and 2147483647. The value for n must be set the same on both the client (set with this net.ini option) and the server (set with the -k option on the vtxnetd or vtxnet2 command line). We recommend changing this setting (on the server and clients); the default setting is widely-used and therefore not secure. See vtxnetd and vtxnet2 programs for more information.

packetsize

Sets the minimum network packet size used by SQL OpenNet on both sides of the connection. The default is 8192 bytes. This option defines a minimum size for an aggregate buffer that is created when data for multiple network packets needs to be sent to the client. By combining packets and sending them as a unit, network traffic is reduced. If you are using a WAN, you may want to change this value to reduce load on the network. Note, however, that changing the default packet size may cause performance problems.

To set this, use the following syntax, where size is the size in bytes:

packetsize size

port

Sets the communication port number, which defaults to the vtxnet setting in the services file. For more information, see Specifying the port number.

port port_number

read_timeout

Specifies the length of time (in seconds) SQL OpenNet should wait for a read operation to complete. By default, this is set to 0, which prevents a time-out.

read_timeout time

return_errno

Instructs SQL OpenNet to return an operating system error code (rather than -1) if there is a communication error. By default, return_errno is set to no.

return_errno yes|no		

ssl

Specifies whether the SQL OpenNet client requires SSL encryption (data packet encryption).

ssl yes|no

If ssl is set to yes, the SQL OpenNet service must use SSL encryption, and the ssl_certfile and ssl_protocol settings in net.ini are used as default client settings for SSL — i.e., they are used unless SSL settings for a DSN override them (see Setting up access with DSNs).

If ssl is set to no (the default), ssl_certfile and ssl_protocol settings in net.ini are ignored, and the SQL OpenNet client will not require SSL encryption unless SSL settings for a DSN require it.

Note that SSL encryption is used if the SQL OpenNet service is set to use it, regardless of this or any other client-side SSL setting for SQL OpenNet. (For information on server-side SSL settings for SQL OpenNet, see vtxnetd and vtxnet2 programs.)

For information on installing and configuring SSL for SQL OpenNet, see Using data packet encryption for SQL OpenNet.

ssl_certfile

Specifies the name and location of a file on the client that is used by default to validate the server certificate for SSL (the certificate used for the SQL OpenNet service). If the server certificate is from a trusted certificate authority (CA), this setting should specify a certificate trust store file on the client (see Requesting a certificate from a certificate authority). If the server certificate is self-signed, this setting should specify a root certificate on the client (see Creating a local certificate authority).

If no certificate trust store or root certificate is specified for an SQL OpenNet connection (specified in net.ini or in a DSN), the SQL OpenNet client will not validate the server certificate.

This setting is used only if the ssl option (in net.ini) is set to yes. DSN settings may override this setting.

ssl_protocol

Specifies which TLS protocol level(s) the SQL OpenNet client will require by default for SSL encryption. Levels 1.1 and 1.2 are supported, but SQL OpenNet server settings determine which levels are available (see Encrypting data packets (-e)). Security best practices require TLS 1.2. If the level (or levels) specified by the client is lower than available levels for SQL OpenNet, an error will be reported.

To specify more than one TLS level, enter the levels separated by a comma:

ssl_protocol tls_level#[,tls_level#,...]

With OpenSSL 1.0.2, SQL OpenNet will use the highest of these levels that is available for the SQL OpenNet service. With OpenSSL 1.1.1x, SQL OpenNet will use the first level specified here as a minimum (if a higher level is available, it will use that), and it will ignore any other TLS levels specified here.

This setting is used only if the ssl option (in net.ini) is set to yes. DSN settings may override this setting.

tcp_keepalive

Sets the value of the TCP keepalive timer (in seconds). This reduces the delay before a broken socket is detected. The default is 600 seconds (10 minutes).

tcp_keepalive time 						

write_timeout

Specifies how long (in seconds) SQL OpenNet should wait for a write operation to complete. By default, this is set to 0, which prevents a time-out.

write_timeout time

The following example net.ini file sets the encryption key to 6541, sets the packet size to 1300, sets the port to 1990, instructs SQL OpenNet to return error codes for communication errors, sets the read time-out to 60 seconds, sets the write time-out to 60 seconds, and sets the ENV1 and ENV2 environment variables on the server.

rem           SQL OpenNet init file
key_connect 6541
packetsize 1300
port 1990
return_errno yes
read_timeout 60
write_timeout 60
hostenv0 ENV1=c:\data,ENV2=c:\data2