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. To change net.ini settings, use a text editor. Note the following:

SQL OpenNet Client Options

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 common knowledge and is 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 or a %SSC_CMD call override them.

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 (for xfODBC) or a %SSC_CMD call (for SQL Connection) require it. For information on SSL settings for a DSN or an %SSC_CMD call, see Setting up access with DSNs or %SSC_CMD.

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, in a DSN, or with %SSC_CMD), 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 and %SSC_CMD 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 and %SSC_CMD settings may override this setting.

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