The freetds.conf file

What it does

FreeTDS uses a configuration file called freetds.conf (the name of the file can be controlled by an environment variable). Its format is similar to Samba's modified "win.ini" format. Its foremost job is to relate dataserver names, as known to your programs[1] , to machine names, as known your network. That is, while your machines have names known to the network, the dataservers on your machines have names known only to your FreeTDS client programs. The configuration file can then further describe that dataserver in greater detail, as need be.

Note: FreeTDS also supports an older configuration file format, known as the interfaces file. Use freetds.conf unless interfaces is needed for your situation. It is easier to read, and it is where all the new options are being added. FreeTDS looks for freetds.conf first, falling back on interfaces only if freetds.conf is not found.

Should you need it, more information about interfaces can be found in the Appendix.

Where it goes

The default location of freetds.conf is determined by the sysconfdir option of configure. If you don't specify anything, configure's default sysconfdir is /usr/local/etc.

In addition, FreeTDS will look for a file .freetds.conf in the user's home directory (~/.freetds.conf).

The actual name and location of freetds.conf may be specified by the environment variable FREETDSCONF. See Environment Variables, below.

FreeTDS reads the user's .freetds.conf before resorting to the system-wide sysconfdir/freetds.conf. The first properly configured (i.e., a readable file with a section for the server) freetds.conf file will be the one used.

What it looks like

The freetds.conf file is composed of two types of sections: a [global] section, and one [dataserver] section for each dataserver. Settings in the [global] section affect all dataservers, but can be overridden in a [dataserver] section. For example

Example 3-1. A freetds.conf file example

	tds version = 4.2

	host =
	port = 1433

	host =
	port = 4000
	tds version = 5.0

In this example, the default TDS version for all dataservers is set to 4.2. It is then overridden for myserver2 (a Sybase server) which uses 5.0.

Table 3-2. freetds.conf settings

NameDefaultMeaningPossible Values
tds version--with-tdsver value (5.0 if unspecified)The TDS protocol version to use when connecting.4.2, 5.0, 7.0, 8.0
hostserver nameThe host that the dataserver is running name or IP address
ProductVersionDefault Port
Sybase SQL Serverprior to System 101433
Sybase SQL Server10 and up5000
Sybase SQL Anywhere72638
Microsoft SQL Serverall1433
The port number that the dataserver is listening to.any valid port
initial block size512Specifies the maximum size of a protocol block. Don't mess with unless you know what you are doing.multiple of 512
try server loginyesDisable use of server logins when domain logins are in use.yes/no
try domain loginyesAttempt a domain login. Setting try domain login has the effect of disallowing server logins! To configure a dataserver for both server logins and domain login disable this option and use DOMAIN\username for login.yes/no
nt domainnoneSpecify an explicit domainany
cross domain loginno(Experimental) If server is member of different domain, attempt to login via that domain.yes/no
dump filenoneSpecifies the location of a tds dump file and turns on loggingany valid file name
dump file appendnoAppends dump file instead of overwriting it. Useful for debugging when many processes are active.yes/no
debug level99Sets granularity of logging. Higher number catches more.0-99
timeoutnoneSets period to wait for response of query before timing out.0-
connect timeoutnoneSets period to wait for response from connect before timing out.0-
emulate little endiannoForces big endian machines (Sparc, PPC, PARISC) to act as little endian to communicate with MS Servers. Set automatically for TDS 7.0/8.0 on big endian hostsyes/no
client charsetstrip high-order byte [a]Makes FreeTDS use iconv to convert to and from the specified character set from UCS-2 in TDS 7.0/8.0any valid iconv character set
text size4,294,967,295default value of TEXTSIZE, in bytes. Affects column width of text and image datatypes. 0 to 4,294,967,295
a. Valid for ISO 8859-1 character set. See TDS 7.0 for Nonwestern Languages for more information.

Many settings in can be overridden by environment variables



In general, the dataserver name is arbitrary and local; it's used only by your client programs to tell FreeTDS which server to connect to. You can choose any name you like.

Sybase SQL Anywhere (a/k/a Sybase ASA), however, is fussy. You must use the database's name as your dataserver name. Otherwise, the server will refuse your connection.