Close menu

odbc.cfg

The odbc.cfg configuration file specifies the configuration and defaults of the sqlrodbc process. It is read by the SQL/R ODBC server on startup.

The odbc.cfg configuration file has sections and configuration items. Each section begins with a title which is enclosed in square brackets ([...]).

Configuration items contain information in the form of single lines of text. Lines starting with a hash character (#) are comments.


[config] section

The following configuration items are recognized in the [config] section:
Title
The sqlrodbcd instance title. If set, this is included in the command line (ps) and the http status. When using multiple sqlrodbcd server instances on a single system this may be used to distinguish between different server instances. By default this value is not set.

Service
The service name (as defined in /etc/services) or the TCP port number where the server should listen for requests. The default value is sqlrodbc.

A suffix /4, /6, or /46 may be used for establishing IPv4 only, IPv6 (with implied IPv4) or separate IPv4 and IPv6 listening sockets. By default, separate IPv4 and IPv6 sockets are used.

For example: 

Service = sqlrodbc/46

HttpService
The service name (as defined in /etc/services) or the TCP port number where the server should listen for HTTP requests. If not specified, the HTTP status is disabled.

A suffix /4, /6, or /46 may be used (see Service above).

For example: 

HttpService = 8083
When enabled, a Web browser may be used to view the configuration and current use of the SQL/R ODBC server process by opening a URL as below: 
http://server:port/
where server is the host name or IP address of the system running the SQL/R ODBC Server and port is the port number specified with HttpService.

Find an example of these http status pages for SQL/R here.

Security
Specifies how user names and passwords are validated. The following choices are supported:

  • odbc - The server will validate passwords and user names using the odbc.user file. The access lists in odbc.dsn, if configured, may be used to restrict which users are authorized to access a data source. This is the default.

  • db - The server passes logon credentials to the database server. When security is set to db, the user configuration in the file odbc.user and group access lists in odbc.dsn are ignored. The DSN is considered writable, as specified by the EnableWrite configuration item and the permissions associated with the database login.

  • ldap - The ODBC server uses the configured LDAP server to verify the user credentials. The user configuration in the odbc.user file is ignored. The access lists in odbc.dsn, if configured, may be used to restrict which users are authorized to access a data source.

This configuration may be re-defined for a data source. 

Security = odbc

User (HP-UX / Linux)
The name (or id) of the operating system account used to run the server process. The default account is sqlr.
This option is ignored, if the server is not started with root privileges.
A configuration value is required, when the server is started with root privileges. 
User = sqlr

Group (HP-UX / Linux)
The name (or id) of the operating system group used to run the server process. The default group is sqlr.
This option is ignored, if the server is not started with root privileges.
A configuration value is required, when the server is started with root privileges. 
Group = sqlr

dsnFile
The path and name of the odbc.dsn file. This configuration file defines the data sources. The default is odbc.dsn.
If specified without a path, or if a relative path is specified, the absolute path is resolved relative to the location of this configuration file. 
dsnFile = odbc.dsn

userFile
The path and name of the odbc.user file. This configuration file defines the ODBC users. The default is odbc.user.
If specified without a path, or if a relative path is specified, the absolute path is resolved relative to the location of this configuration file. 
userFile = odbc.user
This configuration may be re-defined for a data source.

pswdFile
The path and name of the odbc.pswd file. This configuration file holds encrypted passwords for either users or databases (referenced by the passKey config item) and is maintained with the sqlrpasswd utility. The default is odbc.pswd.
If specified without a path, or if a relative path is specified, the absolute path is resolved relative to the location of this configuration file. 
pswdFile = odbc.pswd
This configuration may be re-defined for a data source.

panic (HP-UX, Linux)
This option defines the action which should be taken when a fatal error is encountered.

The following values are valid:

  • exit - Terminate the process. This is the default.
  • dump - Create a core dump. 
panic = exit
This configuration may be re-defined for a data source.

tmpDir
Path where temporary result files during runtime are created. If not defined, the system default location is used.
Please refer to tempnam(3) for more information. 
tmpDir = /var/tmp
This configuration may be re-defined for a data source.

Please note that the required disk space at runtime depends on the query result size and may be noticeable.

UseKeepAlive
Numeric flag that specifies whether the KEEP ALIVE socket option should be used. Valid values are 1 or 0. The default value is 1.
If this option is enabled (the default), the server will check after a system defined period of inactivity, if the client is still alive or close the client connection if not. 
UseKeepAlive = 1

NoDNS
Numeric flag that specifies that no reverse DNS lookup is performed to obtain the DNS name of a client system upon connection. This avoids DNS overhead and latency when writing LogFile messages. Valid values are 1 or 0. The default value is 1. 
NoDNS = 1

LogFile
This defines where log messages are written to. This configuration value either specifies a fully qualified filename or one of the keywords below:

  • syslog - log messages will be sent to the system log. For HP-UX and Linux, the syslog daemon. On Windows the the Windows Event Log.

  • console - log messages are written to the console (HP-UX, Linux) /dev/tty if the process is running in foreground, HP-UX: /dev/syscon or /dev/console

The default value is "syslog".

LogFile = syslog
This configuration may be re-defined for a data source.

LogFlags
The LogFlags config item defines which messages are logged. Each message has an associated type and severity. The type "*" is a wildcard covering any message type. The message priority 0 indicates error messages, priority 1 indicates informational messages.
The default LogFlags is "*0" which specifies to log error messages only. 
LogFlags = *0
This configuration may be re-defined for a data source.

The following types are used (upper case):

  • Wildcard = '*'
  • Config = 'C'
  • Server = 'D'
  • Audit = 'E'
  • Isam = 'F'
  • HTTP status = 'H'
  • Image = 'I'
  • Kernel = 'K'
  • LDAP = 'L'
  • Optim = 'O'
  • Protocol = 'P'
  • Sqlr = 'S'
  • Cursor = 'T'
  • Network = 'X'
  • Parser = 'Y'

The following message severities are in use:

  • ERROR = 0 - error messages
  • INFO = 1 - information
  • DEBUG = 2 - debug
  • VDEBUG = 3 - verbose debug

For example: 

LogFlags = *1Y2

When using syslog, the following priorities are mapped:

  • ERROR = LOG_ERR
  • INFO = LOG_NOTICE
  • DEBUG = LOG_DEBUG
  • VDEBUG = LOG_DEBUG

LogTimeFmt
Defines the format of the timestamp for log messages written to a log file. Follows strftime conventions. 
LogTimeFmt = "%Y-%m-%d %H:%M:%S"

SysIdent (HP-UX, Linux)
syslog identifier. The default is sqlrodbc.
See syslogd(1M) for more information.

SysFacility (HP-UX, Linux)
syslog facility (USER/DAEMON/LOCAL0..LOCAL7). The default is USER.
See syslogd(1M) for more information.

MaxUsers (HP-UX, Linux)
Specifies the maximum number of simultaneous connections. A separate connection is used for any active sqlrexec or Sqlr.DLL process or ODBC connection. The default is 40 simultaneous connections. 
MaxUsers = 40
The server might reject new connection attempts if the number of concurrent connections exceeds the MaxUsers value.

ArraySep
Specifies the separator that is used to delimit the name and index of array elements. The default is "__" (two underscore characters).
The Eloquence database supports arrays while SQL does not. Array elements are represented as separate fields. 
ArraySep = "__"
This configuration may be re-defined for a data source.

SortOrder
Specifies the collating sequence used to sort string values. The collating sequence is defined as a language specifier and either a "fold" or "nofold" modifier separated by a @ character, such as "french@nofold". 

SortOrder=german@nofold
A "fold" sort order interleaves upper- and lowercase characters, such as AaBbCc...Zz, where a "nofold" sort order separates upper- and lowercase characters, such as "ABC...Z abc...z".

Please refer to the lib/nls/collate directory in the SQL/R installation for a list of supported collating sequences.
By default no collating sequence is defined and string values are ordered by their binary value (ASCII). This configuration may be re-defined for a data source.


LDAP configuration

The following LDAP specific configuration items are recognized in the [config] section. These settings are only relevant if security = LDAP is configured globally in the odbc.cfg or for a DSN.
For more information on using LDAP with SQL/R please refer to the LDAP support document.
LdapURI
This specifies the uri of the LDAP server. 
Syntax: {ldap|ldaps}://server[:port] [server[:port] ...]
A leading ldap or ldaps specifies the protocol. The ldap protocol is not encrypted, the ldaps protocol specifies an encrypted connection is used. Server specifies the name or IP address (and optional port number) of the LDAP server. If no port number is specified, the default port number associated with the protocol is used (389 for ldap and 636 for ldaps). Multiple servers may be specified, separated by spaces.

Please refer to the HP-UX or Windows platform specifics for prerequisites to use an encrypted connection.

For example, 

LdapURI = ldap://ldap.marxmeier.com
This configuration may be re-defined for a data source.

LdapCertsDir (HP-UX)
Used on HP-UX to specifiy the directory holding the certificate database cert8.db and key3.db. These are required for an encrypted LDAP connection. The default is /etc/opt/sqlr/4.0/certs

Please refer to the HP-UX platform specifics for more information.
This configuration may be re-defined for a data source.

LdapTimeout
Numeric value, specifying the timeout (in ms) connecting the LDAP server. When specified, the LDAP enquery will fail if the time exceeds the specified timeout. A zero value specifies the platform defaults. The default is zero.
This configuration may be re-defined for a data source.

LdapBindDn
Specifies how a user name is transformed into an LDAP binddn. The %U token is replaced with the user name. The default is %U so that the binddn is equivalent to the user name.
To authenticate against a Windows Active Directory server, the user name must be qualified with the Active Directory domain, using a configuration like: 
LdapBindDn = %U@my.active.directory.domain
This configuration may be re-defined for a data source.

LdapBase
Specifies an optional search base. If not specified, a successful LDAP bind is sufficient to authenticate the user. Specifying LdapBase is required if the LDAP group membership should be checked against a group access list.

For example, 

LdapBase = cn=users,dc=marxmeier,dc=com
This configuration may be re-defined for a data source.

LdapUserMatch
Specifies how a user name is matched if a search base is configured. The %U token is replaced with the user name. The default is cn=%U so that the common name must match the user name. An LdapFilter may be configured to further narrow the LDAP search result.
This configuration may be re-defined for a data source.

LdapFilter
Specifies an additional condition to be verified by the LDAP server. This is optional and requires that a search base is configured. It is combined with LdapUserMatch. For example, 
LdapFilter = (memberOf=cn=ODBC,cn=users,dc=marxmeier,dc=com)
This configuration may be re-defined for a data source.

LdapGroupAttr
Specifies the attribute which is used to obtain the LDAP group membership to be checked against a group access list. By default the memberOf attribute is used.
This configuration may be re-defined for a data source.


Encryption configuration

The [encryption] section allows to specify the properties of the encryption protocol used to communicate with the driver. It also allows to specify IP addresses that use an encrypted connection.

When using an encrypted connection, the server uses an RSA public/private key pair to distribute an AES key that is actually used to encrypt the communication. The key is periodically exchanged.

For more information on using encrypted communication please refer to the Encryption document.

The following encryption configuration items are recognized. These settings are only relevant if encryption is enabled in either the odbc.cfg or for a DSN.

RsaExchangeKeySize
Specifies the size of the RSA key (in bits) that is used to encrypt the AES session key. Valid values must be a multiple of 512. The default is 1024. The default should only be changed if generating the RSA key is found to be a performance issue. 
RsaExchangeKeySize = 1024

KeyRefreshInterval
Specifies the interval after which a new RSA key is generated. The default is 60 minutes. 
KeyRefreshInterval = 60

AesSessionKeySize
Specifies the length (in bits) of the AES key that is used to encrypt the driver communication. Valid values are: 128, 192, 256 The default is 128 bits. 
AesSessionKeySize = 128

On
Off
The On/Off config item specifies the IP addresses that use encrypted communication. This is controlled by the server config, either per (client) IP address or in addition per data source.

The following syntax is supported: 

{on|off} = { All | hostname | ip-address [/{addrbits|netmask]} }
Multiple Allow/Deny entries are recognized and combined.

hostname is the name of a host or network that is resolved into one or more ip addresses.

ip-address is either an IPv4 or IPv6 address.

  • An IPv6 address, enclosed in square brackets, such as [::1]. The addrbits option may be used to specify the number of relevant bits in the IP address.

  • An IPv4 address, such as 127.0.0.1. The addrbits option may be used to specify the number of relevant bits in the IP address. The netmask option allows to specify an IPv4 network mask, such as 255.255.255.0.

If not matched an unencrypted connection is used by default. The On = All directive may be used to specify encrypted communication to be used by default and to specify the exceptions separately.

By default, clients do not use encryption. 

Off = All

For example: 

On = All
Off = localhost
Off = 194.64.71.101
Off = 10.64.72.0/24
In this example, encryption is used by default except for the specified addresses.


Remote access

The [access] section may be used to enable or reject client connections.

The following syntax is supported: 

{allow|deny} = { All | hostname | ip-address [/{addrbits|netmask]} }
Multiple Allow/Deny entries are recognized and combined.

hostname is the name of a host or network that is resolved into one or more ip addresses.

ip-address is either an IPv4 or IPv6 address.

If configured, an connection attempt is denied unless specifically allowed (implied denied=all). If not configured, access is not restricted. 

[access]
#allow = all
The example below disables any network access besides the specified addresses. 
deny = All
allow = localhost
allow = 192.168.1.101
allow = 10.64.72.0/24
The "deny = all" is redundant (and may be omitted) as it is the default if an access list is specified.