vtxnetd and vtxnet2 programs

WSupported on Windows

USupported on Unix

VSupported on OpenVMS

NSupported in Synergy .NET

Vtxnetd and vtxnet2 are service programs that implement SQL OpenNet. Vtxnet2 is available only on Windows. See Understanding SQL OpenNet on Windows for information on the differences between these programs.

Note the following operating system-specific information:

• On Windows, the command line that starts vtxnetd or vtxnet2 is in the opennet.srv file. Vtxnetd is the default. See Customizing the opennet.srv file.
• On Unix, the command line to start vtxnetd is located in the startnet script. Vtxnetd can also be run from the command line. We don’t recommend running vtxnetd with root privileges or uid=0 (unless you are using the -a option). See Starting SQL OpenNet for SQL Connection.
• On OpenVMS, the line for starting the database driver is located in the input file NET.COM.

If the SQL OpenNet service fails to start, an error will be written to the tcm_pid.log file if you are using vtxnetd/vtxnet2 logging. There will be no other indication that the service failed to start, except that SQL OpenNet connections will fail.

vtxnetd [option] [...]

or

vtxnet2 [option] [...]

Options

-a[L]

Use the operating system to validate the username and password in connect strings. On Windows, you can use -a with the L option (that is, -aL; L must be capitalized) to log authorization errors to the Windows Event Viewer. See Starting the service manager with a password (-a[L]) below.

-e cert_file [CA_file] [invcertOK] [tls_version]

Use SSL data packet encryption. Certificate is the certificate to use on the server; CA_file (optional) is the certificate authority to use to validate an incoming certificate from the client; invcertOK (optional; Windows and Unix only) enables the server to start when the .pem file is invalid; and tls_version (optional) tells the server which TLS version to use. See Encrypting data packets (-e) below for details.

-ffilename

Use the specified file to check inbound service requests or preload DLLs. See Rejecting unspecified service requests or preloading DLLs (-f) below. (Windows, Unix only)

-h

Display a list of options.

-kn

Encrypt usernames and passwords in connect strings; n specifies the key for the encryption algorithm. See Encrypting usernames and passwords (-k) below.

log

Output a log file. See Using a log file (log, log2, log3) below.

log2

Output a log file that does not include vtxping events. See Using a log file (log, log2, log3) below.

log3

Output a log that includes all the information from the log2 option, plus the arguments used to start VTX4. See Using a log file (log, log2, log3) below.

-pnnnn

Listen for requests on port nnnn. See Specifying a port number (-p) below.

-sn

Specify thread stack size for vtxnetd in kilobytes. See Specifying the amount of memory used by vtxnetd on Windows (-s) below. (Windows only)

-v6

Specify that the port allows both IPv4 and IPv6 connections. Default is IPv4. (Windows, Unix only)

-wn

Terminate existing connections when vtxnetd is shut down. There is a delay of up to n seconds after the shut down is requested for underlying operations to complete. The default is 10 seconds. See Shutting down vtxnetd on Windows (-w) below. (Windows only)

Discussion

Starting the service manager with a password (-a[L])

By default, no system-level remote user authentication occurs. This behavior can be overridden with the -a option. When -a is used, the username and password for the host must be passed in the connect string from the client machine (in addition to any database username and password). The host username and password could be an account on the server machine or (on Windows) on a domain controller.

The service manager validates the username and password using operating system security validation. Assuming the username and password are valid, the service manager creates a new process or thread for the connection using the persona of the username that was passed to it. Note the following operating system restrictions for using the -a option:

• On Windows, if you are using vtxnet2, the account for this user must have the “log on as a batch job” user privilege.
• On Unix, vtxnetd must be started by a user with root privileges or uid=0. Otherwise, we do not recommend running vtxnetd as root or uid=0.
• On OpenVMS, the requested driver must be started with the system user ID [1,4].

On Windows, by including “L” with the -a option (that is, -aL), you can log authorization errors in the Windows application event log, which can be viewed with the Windows Event Viewer. If the authentication fails, this log will contain information that may be helpful in troubleshooting.

See Building connect strings and Setting up access with DSNs for more details on connection strings and specifying the optional username and password.

Encrypting data packets (-e)

The -e option enables data packet encryption for SQL OpenNet, as described in Using data packet encryption for SQL OpenNet. See that topic for information on installing and setting up encryption for SQL OpenNet.

The syntax is

-e cert_file [CA_file] [invcertOK] [tls_version]

• cert_file specifies the certificate file on the server. This argument is required and the certificate is, by default, validated when the server starts. Certificate may be the name and path to a .pem file or, on Windows, a certificate in the Windows Certificate Store. For details on the format, see Windows Certificate Store specification.
• CA_file (optional) is the location of the certificate authority used to validate an incoming certificate from the client. The CA_file cannot contain a pass phrase.
• invcertOK (optional; Windows and Unix only) allows the server to start when an invalid certificate (.pem file) is found. When encryption is enabled, by default vtxnetd/vtxnet2 validates that the certificate file is valid when it starts up, and, if it’s not valid, an error is logged to the tcm_pid.log file, and the service terminates. Setting the invcertOK option allows the server to continue running in the event of an invalid .pem file; the error is still logged. Note that the invcertOK option applies only when the certificate is a .pem file, not for certificates in the Windows Certificate Store. In the latter case, the server will always terminate if an invalid certificate is found.
• tls_version (optional) indicates the TLS level allowed for SQL OpenNet connections. Valid options are 1.1 (for 1.1 or higher), 1.2 (for 1.2 or higher), or 1.3 (for 1.3 or higher). If not specified, TLS defaults to 1.2 and higher.

For information on default SSL client settings for SQL OpenNet, see Setting SQL OpenNet client options in net.ini. For information on setting connection-specific client settings for SSL encryption, see %SSC_CMD (for SQL Connection) and Setting up access with DSNs (for xfODBC).

Rejecting unspecified service requests or preloading DLLs (-f)

The -f option is included on the command line for vtxnetd in the distributed opennet.srv file on Windows. Do not add, change, or remove this command line option or the distributed synpreload.config file it references.

The -f option is supported on Windows and Unix and is automatically used for vtxnetd on Windows. Its function depends on the platform and program (vtxnetd or vtxnet2) in use. The -f option takes a text file (filename) as a parameter. If filename does not include a path, vtxnetd or vtxnet2 attempts to find the specified file in the lib directory in the location specified by VORTEX_HOME. Lines in the specified text file that begin with the pound sign (#) are comments.

With vtxnetd on Unix and vtxnet2 on Windows, the -f option instructs the SQL OpenNet service to reject requests for services that aren’t listed in the specified text file. This protects the SQL OpenNet service from being used to run harmful processes. If the text file includes a database driver specification exactly as it appears in connect strings (including any path information), requests for that database driver service will be accepted. All others will be ignored. For example, if the file includes only the following line:

/usr2/synergyde/connect/VTX0

only a connection request with exactly the following in the connect string will be accepted:

!/usr2/synergyde/connect/VTX0

The database driver specification can appear by itself on a line of this file, or it can be prefixed with “service:”. For example:

service:/usr2/synergyde/connect/VTX0

With vtxnetd on Windows, the -f option instructs the SQL OpenNet service to preload specified DLLs to prevent memory leaks in third-party software. It is automatically set to the following:

-fsynpreload.config

The distributed opennet.srv and opennet_base.srv files on Windows include this setting (which preloads DLLs specified in the synpreload.config file in the /synergyde/connect directory). If opennet.srv does not have this setting, sqld automatically adds it when it spawns vtxnetd on Windows.

As distributed, the synpreload.config file specifies all DLLs that should be preloaded, so do not make changes to this file. DLLs specified in this file must be prefixed with “preload:” (without the quotation marks). For example:

preload:VTX12_SQLNATIVE

Encrypting usernames and passwords (-k)

By default, the -k option is included on the command line in the start-up file. This option encrypts both the database username and password and the host username and password being sent across the wire.

The key n can be any number between 1 and 2,147,483,647. It must be set to the same value on both the server and the client or you will get the error “Invalid connect syntax (uid/pwd/datasource).” On the client, set it in the net.ini file in the connect\synodbc\lib directory. See Setting options in net.ini.

We strongly recommend that you change the n value because the default setting is widely-known and therefore is not secure.

Using a log file (log, log2, log3)

All of these options create a log file in the directory that the service manager was started in and name it tcm_pid.log, where pid is the current process ID.

• The log option produces a log file that contains error information and connection requests, including vtxping events (e.g., the vtxping events that take place when sqld polls vtxnetd/vtxnet2).
• The log2 option produces a log file that contains error information and connection requests, but without vtxping events. This creates a smaller log file to start with, and once the file reaches 20 MB, it’s truncated to the last 10 MB.
• The log3 option produces the same file as log2, with the addition of the arguments used to start VTX4.

The log, log2, or log3 option must be the last option on the vtxnetd or vtxnet2 command line; otherwise the log file won’t be generated. Note that there is no minus sign preceding the log options. We recommend using log2 whenever possible and cleaning up unneeded log files.

Other types of logging are available; see SQL Connection troubleshooting and error logging and Error logging for xfODBC.

Specifying a port number (-p)

Use the -p option to specify the port that SQL OpenNet will use on the server.

On OpenVMS SQL OpenNet uses port 1958 by default; you can override that default by specifying the port number using -p (in the NET.COM file).

On Windows and Unix there is not a default port; we recommend you specify one with -p. You can optionally specify a port in the services file, but this it is not recommended; a port number setting in the services file is used only when -p is not used. (See Specifying the port number and Configuring SQL OpenNet for SQL Connection.)

Make sure the port you specify for SQL OpenNet isn't used by another program on the system. Make sure the port number that clients use for SQL OpenNet matches the port number used by vtxnetd/vtxnet2. For SQL Connection, see Configuring SQL Connection (client) (Windows); SQL Connection: configuring client or stand-alone access (Unix); or SQL Connection: configuring and testing client or stand-alone access (OpenVMS). For xfODBC, see Setting up access with DSNs.

Specifying the amount of memory used by vtxnetd on Windows (-s)

By default, vtxnetd uses 512K of memory for the stack for each thread. You can change this with the -s option, which determines how much memory vtxnetd will use by limiting the thread stack size allocated to each thread. Reducing the amount of memory used may enable vtxnetd to support more concurrent users; however, we do not recommend changing this value because it can cause random instability.

For example, to reduce the amount of memory used by vtxnetd to 256K, you would use the following:

vtxnetd -s256

Database drivers have minimum requirements for thread stack size. If you set the thread stack size to a value that is less than the minimum required by your database driver, vtxnetd will likely fail or generate random errors.

Shutting down vtxnetd on Windows (-w)

By default, the -w option is included on the command line in the opennet.srv file. When -w is specified, shutting down SQL OpenNet will disable new connections and terminate existing ones, resulting in a “Network connection lost” (10054) error on the client. There is a delay of up to n seconds before existing connections are terminated, allowing underlying operations to complete. The default is 10 seconds, but you can change this value by editing the -w option on the vtxnetd command line in opennet.srv. If you set it to 0 (zero), all connections will be terminated immediately.

If -w is not specified, new connections are disabled, but existing connections are not terminated, and vtxnetd does not completely shut down until all child processes have terminated. Only the third-party applications that are connected to the Synergy data can stop existing processes in this case.

See Stopping and removing SQL OpenNet for details on the various ways to stop the service.

The -w option was introduced in version 10.3 and is included on the vtxnetd command line in the opennet.srv and opennet_base.srv files for 10.3 and higher. The opennet.srv file is not overwritten on an upgrade, however, so if you are upgrading from a previous version and want client connections to be terminated when vtxnetd is shut down, you will need to edit opennet.srv to add -wn to the command line. For example, vtxnetd.exe -k67834 -p1958 -s512 -w10 log2

Running multiple SQL OpenNet servers

You can run multiple SQL OpenNet servers by specifying multiple start-up lines, with a different port number for each server. For example:

• On Windows, add the additional start-up lines to the opennet.srv file:

vtxnetd.exe -p1960

• On Unix, add the additional start-up lines to the startnet script file:

nohup vtxnetd -p1960 &

• On OpenVMS, add the additional start-up lines to the NET.COM file:

$ VTXNETD -p1960