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. 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 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 key file, and p (optional) specifies supported protocols (TLS levels). See Encrypting data packets (-e) below.

-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 connection log. See Using a log file (log, log2) below.

log2

Output a connection log that does not include vtxping events. See Using a log file (log, log2) 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 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. 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)

By default, no data packet encryption (SSL encryption) occurs for SQL OpenNet. To enable SSL encryption for SQL OpenNet, 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 key file. These can include a full path or logical.

The optional p argument enables you to specify which TLS levels are allowed for SQL OpenNet connections. TLS level 1.1 and 1.2 are supported. By default, both levels are allowed for SQL OpenNet. Current security best practices require TLS 1.2.

• If the server has OpenSSL 1.0.2, you can specify one or more allowed TLS levels for SQL OpenNet connection. If you specify more than one level, separate them with a comma:

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

• If the server has OpenSSL 1.1.1x, the number you pass as p specifies the lowest allowed TLS level. The highest supported version is 1.2. (If you specify more than one level for a server with OpenSSL 1.1.1x, the first number is used as the minimum TLS level, and the second number is ignored.)

See Using data packet encryption for SQL OpenNet for information on installing and setting up SSL for SQL OpenNet.

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)

Use the log option to produce 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).

Use the log2 option to produce a log file that contains error information and connection requests, but without vtxping events. This produces a smaller log file, and with log2 the log file is truncated to the last 10 MB once it reaches 20 MB.

With either option, the log file is created in the directory that the service manager was started in and is named tcm_pid.log, where pid is the current process ID.

The log or log2 option must be the last option on the vtxnetd or vtxnet2 command line. Otherwise the log file will not be generated. Be sure to manage log files. Use log2 whenever possible, and clean 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