The freetds.conf file

What it does

Just as DNS defines hostnames for network addresses, freetds.conf uses a servername to define the properties of your server. [1] In particular, FreeTDS needs to know:

Primary Server Properties

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. tsql -C reports the sysconfdir to let you confirm it.

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

The actual name and location of freetds.conf may be specified by the environment variable FREETDS (or FREETDSCONF, same effect). See Environment Variables, below.

FreeTDS reads the user's ${HOME}/.freetds.conf before resorting to the system-wide sysconfdir/freetds.conf. The file used is the first one that is readable and contains a section for the server.

What it looks like

Tip

The following information is also provided in the freetds.conf manual page, cf. man freetds.conf.

The freetds.conf file format is similar to that of Samba's modified "win.ini". It is composed of two types of sections: one [global] section, and a [servername] section for each servername. Settings in the [global] section affect all servernames, but can be overridden in a [servername] section. For example

Example 3-1. A freetds.conf file example

					[global]
					tds version = 4.2
					
					[myserver]
					host = ntbox.mydomain.com
					port = 1433
					
					[myserver2]
					host = unixbox.mydomain.com
					port = 4000
					tds version = 5.0
					
					[myserver3]
					host = instancebox.mydomain.com
					instance = foo
					tds version = 7.1
					

In this example, the default TDS version for all servernames is set to 4.2. It is then overridden for myserver2 (a Sybase server) which uses 5.0, and myserver3 (a MSSQL 2000 server) which uses 7.1.

Usually, it is sufficient to state just the server's hostname and TDS protocol version. Everything else can be inferred, unless your setup (or your server's) strays from the defaults.

Tip

Some people seem to feel safer using the IP address for the server, rather than its name. We don't recommend you do that. Use the name, and benefit from the inherent advantages. That's why DNS was invented in the first place, you know.

It bears mentioning here that prior versions of FreeTDS were quite fussy about domain logins, forcing users to make explicit per-server entries in freetds.conf. That is no longer the case. If the username has the form DOMAIN\username, FreeTDS will automatically use a domain login.

Table 3-2. freetds.conf settings

NamePossible ValuesDefaultMeaning
tds version4.2, 5.0, 7.0, 7.1, 7.2, auto--with-tdsver value (5.0 if unspecified) Overridden by TDSVER.The TDS protocol version to use when connecting. "auto" tells FreeTDS to use an autodetection (trial-and-error) algorithm to choose the protocol version.
hosthost name or IP addressnoneThe host that the servername is running on.
portany valid port
ProductVersionDefault Port
Sybase SQL Serverprior to System 101433
Sybase SQL Server10 and up5000
Sybase SQL Anywhere72638
Microsoft SQL Serverall1433
The port number that the servername is listening to. Please note: The "defaults" to the left are the server's default settings. FreeTDS chooses its default port based on the TDS protocol version: 5000 for TDS 5.0, and 1433 for everything else. Mutually exclusive with instance, below. Overridden by TDSPORT.
instanceinstance namenone

Name of Microsoft SQL Server instance to connect to. The port will be detected automatically. Mutually exclusive with port, above. Requires UDP connection to port 1434 on the server.

ASA databasevalid database nameservername [section] nameSpecifies the name of the default database when connecting to an ASA server. A TDS 5.0 login packet has a field called lservname. For most TDS servers, lservname is a user-defined string with no inherent meaning. ASA servers, however, requires that lservname contain a valid database name, and sets that as the default database for the connection. FreeTDS normally fills lservname with the [section] text.. This entry instead sets the database name independently of the [section] name.
initial block sizemultiple of 512512Specifies the maximum size of a protocol block. Don't mess with unless you know what you are doing.
dump fileany valid file namenone Overridden by TDSDUMP. Specifies the location of a tds dump file and turns on logging
dump file appendyes/nonoAppends dump file instead of overwriting it. Useful for debugging when many processes are active.
timeout0-noneSets period to wait for response of query before timing out.
connect timeout0-noneSets period to wait for response from connect before timing out.
emulate little endianyes/nonoForces big endian machines (Sparc, PPC, PARISC) to act as little endian to communicate with MS Servers. Set automatically for TDS 7.0 or above on big endian hosts
client charsetany valid iconv character setISO-8859-1[a]Makes FreeTDS use iconv to convert to and from the specified character set from UCS-2 in TDS 7.0 or above. FreeTDS uses iconv to convert all character data, so there's no need to match the server's charset to insert any characters the server supports.
text size0 to 4,294,967,2954,294,967,295default value of TEXTSIZE, in bytes. For text and image datatypes, sets the maximum width of any returned column. Cf. set TEXTSIZE in the T-SQL documentation for your server.
debug flagsAny number even in hex or octal notation0x4fffSets granularity of logging. A bitmask. See table below for specification.
encryptionoff/request/requireoffSpecify if encryption is desidered. Supported for Microsoft servers. off disables encryption (only if needed); request means use if available; require means create and allow encrypted connections only.
enable gssapi delegationon/offoffEnable delegation flag using Kerberos.
use ntlmv2yes/nonoUse NTLMv2. An alternative to the UseNTLMv2 option in odbc.ini.
Notes:
a. Valid for ISO 8859-1 character set. See Localization and TDS 7.0 for more information.

Overrides

Many settings in freetds.conf can be overridden by environment variables.

The servername can also be decorated adding the port or instance name using port override syntax.

Controlling log details

The logging capability has helped solve innumerable cases, some trivial and some very low-level bugs. Sometimes a developer needs very detailed information about one function, whereas someone else may interested only in whether or not a particular function is called, or even want to see only the SQL that was transmitted to the server.

The log's granularity can be controlled with the debug flags entry. The default value (4FFF hex) gives a level of detail that is useful for resolving problems via the mailing list.

Table 3-3. Valid bitmask values for debug flags entry in freetds.conf

ValueMeaning
0x80function trace and info
0x40information level 2
0x20information level 1
0x10network
0x08warning
0x04error
0x02severe error
0x1000show pid
0x2000show time
0x4000show source level info (source file and line)
0x8000thread id (not implemented)

For more about the wonderful world of FreeTDS logs, see Logging.

Deprecated options

The following options have long been deprecated.

Deprecated freetds.conf settings

  • try server login

  • try domain login

  • nt domain

  • cross domain login

  • debug level

Notes

[1]

In general, the servername 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. Unless you use the ASA Database property, you must use the database's name as your servername. Otherwise, the server will refuse your connection.