freetds.conf man page

freetds.conf — configuration file for FreeTDS

Synopsis

The freetds.conf file describes Sybase and Microsoft database servers to the FreeTDS library. It comprises sections headed by a servername, followed by a list of connection properties denoted as name-value pairs. Defaults are defined via a [global] section. This file supersedes the interfaces file that Sybase defines for the same purpose, although the latter is still supported.

Description

A section begins with a servername — the name of the server — in square brackets. The servername is chosen at the client's descretion. (One exception: with Sybase ASA the servername must match the database name to be used.)

Sections contain properties, one per line, in the form

name = value

where name is the connection property to be described. Servernames and properties are not case sensitive. Values are case-preserving i.e., copied literally. Comments begin with either a semicolon (‘;’) or pound sign (‘#’) and continue to end of line. Blank lines are ignored. Whitespace surrounding the ‘=’ is ignored.

Properties

client charset

encoding of client data; overrides locale(1) settings

Domain:

iconv character set names

Default:

ISO-8859-1

connect timeout

seconds to wait for response from connect request

Domain:

0 to MAX_INT

Default:

none

debug flags

logging granularity

Domain:

32-bit integer

Default:

0x4fff

dump file

specifies location of a logfile and turns on logging

Domain:

valid file name

Default:

none

dump file append

log data appended to file instead of re-writing for each connection

Domain:

yes/no

Default:

no

emulate little endian

forces big endian machines to act as little endian to communicate with Microsoft Servers

Domain:

yes/no

Default:

no

encryption
off

disables encryption (default)

request

use if available

required

allow encrypted connections only

host

Name of the host the server is running on.

Domain:

host name or IP address

Default:

SYBASE

initial block size

maximum size of a protocol block

Domain:

multiple of 512

Default:

512

instance

name of Microsoft SQL Server instance to connect to (supersedes port)

Domain:

instance name

Default:

none

port

port number that the server is listening to

Domain:

any valid port

Default:

TDS 5.0, 5000; TDS 7.0 and up, 1433

tds version

TDS protocol version to use

Domain:

4.2, 5.0, 7.0, 7.1, 7.2

Default:

--with-tdsver value (5.0 if unspecified)

text size

default value of TEXTSIZE, in bytes

Domain:

0 to 4,294,967,295

Default:

4,294,967,295

timeout

seconds to wait for response to a query

Domain:

0 to MAX_INT

Default:

none (wait forever)

Do not define both port and instance. One implies the other.

Boolean property values may be denoted as on/off, true/false, or 1/0.

Debug Flags

The log's granularity can be controlled with the debug flags property.

Value Meaning
  0x02 severe error
  0x04 error
  0x08 warning
  0x10 network
  0x20 information level 1
  0x40 information level 2
  0x80 function trace and info
0x1000 show pid
0x2000 show time
0x4000 show source level info (source file and line)
0x8000 thread id (not implemented).

Names and Locations

The file is normally named /etc/freetds.conf or ${HOME}/.freetds.conf. That name can be overridden with the FREETDSCONF environment variable.

FreeTDS will search conf files for a servername in the following order:

  1. a filename set programatically via dbsetifile() that is in .conf format
  2. a filename in the environment variable FREETDSCONF that is in .conf format
  3. ${HOME}/.freetds.conf if extant
  4. /etc/freetds.conf

The search stops with the first file containing the servername.

If no conf file is found, FreeTDS searches for an interfaces file in the following order:

  1. a filename set programatically via dbsetifile() that is in interfaces format
  2. ${HOME}/.interfaces
  3. $SYBASE/interfaces (where $SYBASE is an environment variable)

If the requested servername is not found in any configuration file, the fallback mechanism is:

  1. attempt to convert the name to an IP address with inet_addr(3), else
  2. attempt to convert the name to an IP address with gethostbyname(3), else
  3. attempt to look up the literal name “SYBASE”

Environment

FREETDSCONF

overrides name and location of the system-wide conf file

TDSDUMP

overrides the name and location of the FreeTDS log file

TDSDUMPCONFIG

specifies a name and location of a file that logs the search of configuration files

TDSHOST

overrides the host property

TDSPORT

overrides the port property

TDSQUERY

synonym for DSQUERY, the default servername

TDSVER

overrides the version specified in the freetds.conf

The environment variables TDSVER, TDSDUMP, TDSPORT, TDSQUERY, and TDSHOST override values set by a .conf or interfaces file.

Files

/etc/freetds.conf, ${HOME}/.freetds.conf

See Also

FreeTDS User Guide

History

Info

December 23, 2007