vtxnetd and vtxnet2 programs

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS

Vtxnetd and vtxnet2 are service programs that implement SQL OpenNet. Vtxnet2 is available only on Windows. Note the following operating system–specific information:

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

‑e crt key [p]

Use SSL data packet encryption. Crt is the name and location of the SSL certificate file, key is the name and location of the private key file, and p (optional) specifies supported protocols (TLS levels).

‑f filename

Use the specified file to check inbound service requests. (Windows, UNIX only)

‑h

Display a list of options.

‑kn

Encrypt user names and passwords in connect strings; n specifies the key for the encryption algorithm.

log

Output a connection log.

log2

Output a connection log that does not include vtxping events.

‑p nnnn

Listen for requests on port nnnn. (Windows, UNIX only)

‑sn

Specify thread stack size for vtxnetd in kilobytes. (Windows only)

‑v6

Specify that the port allows IPv6 connections. Default is IPv4. If the OS supports IPv4 and IPv6 connections on the same port, specifying ‑v6 means both IPv4 and IPv6 are supported. If the OS does not support IPv4 and IPv6 on the same port, specifying ‑v6 results in only IPv6 support. (Currently, only Solaris and HP‑UX do not offer this support.) (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. (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 user name and password for the host must be passed in the connect string from the client machine (in addition to any database user name and password). The host user name and password could be an account on the server machine or (on Windows) on a domain controller.

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

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 user name and password.

Encrypting data packets (‑e)

By default, no data packet encryption occurs for SQL OpenNet. To enable data packet encryption, use the ‑e option:

-e crt key [p]

This option invokes SSL encryption functionality supplied by a third‑party library, OpenSSL. Crt specifies the name and location of the SSL certificate file, and key specifies the name and location of the private key file. These can include a full path or logical. The optional p argument enables you to specify the supported TLS levels (TLS 1.0, 1.1, 1.2). By default, all three are supported. To specify more than one TLS level, separate values with commas. For example,

vtxnetd -e c:\ssl\crt.txt c:\ssl\key.txt 1.1,1.2 

See Using data packet encryption for SQL OpenNet for more information.

Rejecting invalid service requests (‑f)

The ‑f option is supported on Windows and UNIX only.

Using the ‑f option tells the service manager to check inbound service requests and reject invalid requests. The ‑f option specifies a text file, in which you list the connect strings that this instance of the service manager can connect to. For example, if the file of valid connection strings contains only this:

/usr2/synergyde/connect/vtx0

then only a connection request from a client specifying exactly

!/usr2/synergyde/connect/vtx0

will be allowed.

Encrypting user names 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 user name and password and the host user name 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. On the client, set it in the net.ini file in the connect\synodbc\lib directory. See Setting connect string defaults and encryption in net.ini. If these numbers do not match, you’ll get the error “Invalid connect syntax (uid/pwd/datasource).”

Using a log file (log, log2)

Use the log option to produce a log file that contains error information and connection requests, including vtxping events, such as occur when sqld polls vtxnetd/vtxnet2. Use the log2 option to produce a log file that contains error information and connection requests, without the vtxping events. Using log2 produces a smaller logfile. By default, the log file is located in the directory that the service manager was started in and is named tcm_pid.log, where pid is the current process ID.

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

Overriding the default port number (‑p)

The default port (1958) used by the service manager is defined in the services file (on Windows and UNIX) and in the NET.COM file on OpenVMS. On Windows and UNIX, the default port can be overridden with the ‑p option; this option is not supported on OpenVMS.

Important

If you use a non‑default port for vtxnetd/vtxnet2, you must also change the port number on the client. For SQL Connection, For SQL Connection, see Configuring SQL Connection (client) for Windows; SQL Connection: configuring client or stand‑alone access for UNIX; or SQL Connection: configuring and testing client or stand‑alone access for 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 on Windows. You can change this with the ‑s option, which determines how much memory vtxnetd will use by limiting the thread stack size allocated to it. Reducing the amount of memory used may enable vtxnetd to support more concurrent users.

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

vtxnetd -s256
Important

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.

Note

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:

vtxnetd.exe -p1960
nohup vtxnetd -p1960 &
$ VTXNETD -p1960