sqlhosts file and SQLHOSTS registry key options

You can include server options and group options in the sqlhosts file or SQLHOSTS registry key.

The following syntax fragments show the server options. The syntax fragment for group options is described in a section after the server options.

Important: Options must be separated by commas, but the first option that is listed in each sqlhosts entry must not have a comma before it.

Server options

Lookup options

PAM options

Table 1. Server options in the sqlhosts file and SQLHOSTS registry key.
Element	Purpose	Restrictions
b	Specifies, in bytes, the size of the communications buffer space for TCP/IP connections.	The maximum buffer size supported is 32 KB.
cfd	Indicates the storage location for communication files that are used in shared-memory and stream-pipe connections.	The length of the cfd path is restricted to 70 bytes. Relative-path byte lengths include $ONEDB_HOME.
g	Specifies the name of the group to which the database server belongs.	The group must be defined.
k	Enables the network service to check periodically whether the connection between the client and server is still active. If the connection is found to be broken the network service frees resources.	Only available for TCP/IP connections.
m	Enables the database server to create multiple database connections without using up the additional computer resources that are required for more network connections.	Multithreaded client connections, shared-memory connections, and connections to subordinate database servers are not supported. The sqlbreak() function is not supported.
r	Enables the control of operating-system security-file lookups to control the way that a client (user) gains access to a database server. The s option identifies database server-side settings, and the r option identifies client-side settings.	The database server ignores r settings.
s	Enables the control of operating-system security-file lookups to control the way that a client (user) gains access to a database server. The s option identifies database server-side settings, and the r option identifies client-side settings.	A client ignores s settings.
pam_serv	Gives the name of a PAM service that a database is using.	Must be used with s=4 option.
pamauth	Describes the authorization method that is used by the PAM service.	Must be used with s=4 option.
`SPWDCSM`	The name of the simple password communication support module	The SPWDCSM must be specified in the concsm.cfg file. You cannot use an SPWDCSM with Enterprise Replication and high-availability clusters A multiplexed connection

The following syntax fragment shows the group options in the sqlhosts file.

Group options

Table 2. Group options in the sqlhosts file and SQLHOSTS registry key.
Element	Purpose	Restrictions
c	Controls connection redirection. Indicates the order in which client applications choose database servers, or the aliases within a database server group.
e	Specifies a database server name that marks the end of a database server group.
i	Assigns an identifying number to a database server group.	The identifier must be a positive integer from 1 through 32767 and must be unique within your network environment. The i option is required for Enterprise Replication.

Usage

When you change option values in an sqlhosts entry, those changes affect the next connection that a client application makes. The server automatically recognizes any changes that are made.

The database server evaluates the options entries as a series of columns. A comma or white space in an options entry represents an end of a column. Client and database server applications check each column to determine whether the option is supported.

You can combine multiple options in each entry, and you can include them in any order. The maximum length for an options entry is 256 bytes.

Attention: Unsupported or incorrect options do not trigger a notification.

Buffer option (b)

The b option applies only to connections that use the TCP/IP connection protocol. Other types of connections ignore the b option.

You can adjust the buffer size to use system and network resources more efficiently; however, if the buffer size is set too high, the user receives a connection-reject error because no memory can be allocated. For example, if you set b=16000 on a system that has 1000 users, the system might require 16 megabytes of memory for the communications buffers. This setting might exhaust the memory resources of the computer. The default buffer size for the database server for TCP/IP is 4096 bytes.

If your network includes several different types of computers, be careful when you change the size of the communications buffer.

Tip: Use the default size for the communications buffer. If you choose to set the buffer size to a different value, set the client-side communications buffer and the database server-side communications buffer to the same size.

Group connection-redirection option (c)

The c option is valid only for servers that are assigned to a server group.

Use the c option to:

Balance the load across multiple database server instances.
Set High-Availability Data Replication (HDR) to transfer over to a backup database server in the event of a failure.

Table 3. Settings for the connection-redirection option.
Setting	Result
c=0	This is the default setting. Client applications connect to the first database server instance listed in the server group in the sqlhosts information. If the client cannot connect to the first instance, it attempts to connect to the second instance, and so on.
c=1	Client applications choose a random starting point from which to connect to a database server instance in a server group.

Communication files directory option (cfd)

You can use the communication files directory option to store shared-memory or stream-pipe connection communication files in a new location. Specifying the communication files directory option for non-root installations of HCL OneDB™ is necessary if the server and client are in different locations, and increases system performance if the server and client are in the same location.

The cfd option can define an absolute path or a path relative to $ONEDB_HOME for storing communication files:

cfd=/location defines an absolute path
cfd=location defines a path relative to $ONEDB_HOME

The length of the cfd path is restricted to 70 bytes. Relative-path byte lengths include $ONEDB_HOME.

Non-root installations of HCL OneDB do not have permission to write to the /INFORMIXTMP directory, so shared-memory and stream-pipe connection communication files are written to the $ONEDB_HOME/etc directory if no communication files directory is specified as an option in the sqlhosts information.

Important: This option must be defined for non-root installations of HCL OneDB, where the server and client are in different locations, or the connection fails.

End of group option (e)

If no e option is specified for a group, but all sqlhosts entries specify either groups or group members, the network must scan the entire file. You can use the e option to specify the end of a server group, and improve system performance. The network layer scans the sqlhosts file until the entry specified by the e option is read.

If no end-of-group option is specified for a group, the group members are assumed to be contiguous. The end of the group is determined when an entry is reached that does not belong to the group, or at the end of file, whichever comes first.

In the following example, the e option specifies entry lx3, so entry lx4 is not scanned by the network layer.

#dbservername   nettype   hostname   servicename   options
g_x1            group     -          -             i=10,e=lx3
lx1             onsoctcp  apollo11   9810          g=g_x1
lx2             onsoctcp  apollo12   9820          g=g_x1
lx3             onsoctcp  apollo13   9830          g=g_x1

lx4             onsoctcp  apollo14   9840

Keep-alive option (k)

This option enables the network service to check periodically whether the connection between the client and server is still active. If the receiving end of the connection does not respond within the time that is specified by the parameters of your operating system, the network service immediately detects the broken connection and frees resources.

Table 4. Settings for the keep-alive option
Setting	Result
k=0	Disables this service
k=1	Enables this service (default)

Multiplex option (m)

This option enables the database server to create multiple database connections to client applications without using up the additional computer resources that are required for more network connections. You must restart the server after you enable this service.

Table 5. Settings for the multiplex option
Setting	Result
m=0	Disables this service (default)
m=1	Enables this service

PAM options (pam_serv, pam_auth, s=4)

The database server provides an interface to use pluggable authentication modules (PAM) for session authentication. To configure this interface, supply the PAM service name and the authentication method. Authentication can be the connection password or a user challenge that requires the user to answer a question. Distributed Relational Database Architecture (DRDA®) connections for .NET Core Provider clients can use password authentication, but not challenge authentication.

HCL OneDB PAM authentication calls the pam_authenticate() and pam_acct_mgmt() functions.

Table 6. Settings for PAM services
Option	Description	Settings
pam_serv	The name of the PAM service that the database server is using.	PAM services typically are in the /usr/lib/security directory and parameters are listed in the /etc/pam.conf file. In Linux™, the /etc/pam.conf file can be replaced with a directory called /etc/pam.d, where there is a file for each PAM service. If /etc/pam.d exists, /etc/pam.conf is ignored by Linux.
pamauth	The method of authentication that is used by the PAM service. An application must be designed to respond to the challenge prompt correctly before connecting to the database server.	pamauth=password uses the connection request password for authentication. pamauth=challenge authentication requires a correct user reply to a question or prompt
s=4	Enables PAM authentication.

Trusted-host and trusted-user lookup options (s)

With these security options, you can specifically enable or disable the use of either or both files.

Table 7. Settings for trusted-host and trusted-user lookup.
Setting	Result
s=0	Disables trusted-hosts lookup in hosts.equiv or the file specified by the REMOTE_SERVER_CFG configuration parameter. Disables trusted-user lookup in rhosts files or the file specified by the REMOTE_USERS_CFG configuration parameter. Only incoming connections with passwords are accepted. Cannot be used for distributed database operations.
s=1	Enables trusted-hosts lookup in hosts.equiv or the file specified by the REMOTE_SERVER_CFG configuration parameter. Disables trusted-user lookup in rhosts files or the file specified by the REMOTE_USERS_CFG configuration parameter.
s=2	Disables trusted-hosts lookup in hosts.equiv or the file specified by the REMOTE_SERVER_CFG configuration parameter. Enables trusted-user lookup in rhosts files or the file specified by the REMOTE_USERS_CFG configuration parameter. Cannot be used for distributed database operations.
s=3	Enables trusted-hosts lookup in hosts.equiv or the file specified by the REMOTE_SERVER_CFG configuration parameter. Enables trusted-user lookup in rhosts files or the file specified by the REMOTE_USERS_CFG configuration parameter. (default)

Secure connections for clusters option (s=6)

The s=6 option in the sqlhosts information ensures that the connections between cluster servers are trusted. Secure ports that are listed in the sqlhosts information can be used only for cluster communication. Client applications cannot connect to secure ports.

Table 8. The secure connection option for clusters.
Setting	Result
s=6	Configures Enterprise Replication and High Availability Connection Security. Cannot be used with any other s option.

netrc lookup options (r)

With r options, you can enable or disable netrc lookup.

Table 9. Settings for netrc lookup options.
Setting	Result
r=0	netrc lookup is disabled.
r=1	netrc lookup is enabled (default)