FreeTDS User Guide: A Guide to Installing, Configuring, and Running FreeTDS | ||
---|---|---|
Prev | Chapter 3. Install FreeTDS | Next |
FreeTDS uses a configuration file freetds.conf (the name 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.
![]() | 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. |
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 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 first properly configured (i.e., a readable file with a section for the server) freetds.conf file will be the one used.
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
[global] tds version = 4.2 [myserver] host = ntbox.mydomain.com port = 1433 [myserver2] host = unixbox.mydomain.com 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.
Usually, it is sufficient to state the only server's hostname and TDS protocol. Everything else can be inferred, unless your setup (or your server's) strays from the defaults.
![]() | 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, and you normally should be able to find your server by its name. Beyond that, if you do use a number, FreeTDS will ask DNS for that number's name (a reverse lookup). A properly configured DNS will execute a reverse lookup just as fast as a forward lookup, but not every DNS is properly configured. If yours isn't, you'll wait awhile, unless you take evasive action. |
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
Name | Default | Meaning | Possible Values | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
tds version | --with-tdsver value (5.0 if unspecified)
Overridden by TDSVER.
| The TDS protocol version to use when connecting. | 4.2, 5.0, 7.0, 8.0 | |||||||||||||||
host | none | The host that the dataserver is running on. | host name or IP address | |||||||||||||||
port |
| The port number that the dataserver 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. Overridden by TDSPORT. | any valid port | |||||||||||||||
initial block size | 512 | Specifies the maximum size of a protocol block. Don't mess with unless you know what you are doing. | multiple of 512 | |||||||||||||||
dump file | none Overridden by TDSDUMP. | Specifies the location of a tds dump file and turns on logging | any valid file name | |||||||||||||||
dump file append | no | Appends dump file instead of overwriting it. Useful for debugging when many processes are active. | yes/no | |||||||||||||||
timeout | none | Sets period to wait for response of query before timing out. | 0- | |||||||||||||||
connect timeout | none | Sets period to wait for response from connect before timing out. | 0- | |||||||||||||||
emulate little endian | no | Forces 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 hosts | yes/no | |||||||||||||||
client charset | ISO-8859-1[a] | Makes FreeTDS use iconv to convert to and from the specified character set from UCS-2 in TDS 7.0/8.0. As of 0.62 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. | any valid iconv character set | |||||||||||||||
text size | 4,294,967,295 | default 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. | 0 to 4,294,967,295 | |||||||||||||||
instance | none | Name of Microsoft SQL Server instance to connect to. The port will be detected automatically.
| instance name | |||||||||||||||
debug flags | 0x4fff | Sets granularity of logging. A set of bit that specify levels and informations. See table below for bit specification. | any number even in hex or octal notation | |||||||||||||||
Notes: a. Valid for ISO 8859-1 character set. See TDS 7.0 for Nonwestern Languages for more information. |
The logging capability has helped solve inumerable 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
Value | Meaning |
---|---|
0x80 | function trace and info |
0x40 | information level 2 |
0x20 | information level 1 |
0x10 | network |
0x08 | warning |
0x04 | error |
0x02 | severe error |
0x1000 | show pid |
0x2000 | show time |
0x4000 | show source level info (source file and line) |
0x8000 | thread id (not implemented) |
For more about the wonder world of FreeTDSlogs, see Logging.
As of version 0.62 the following options are deprecated and supported only for backward compatibility.
Table 3-4. Deprecated freetds.conf settings
Name | Default | Meaning | Possible Values |
---|---|---|---|
try server login | yes | Disable use of server logins when domain logins are in use. | yes/no |
try domain login | yes | Attempt 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 domain | none | Specify an explicit domain. | any |
cross domain login | no | (Experimental) If server is member of different domain, attempt to login via that domain. | yes/no |
debug level | 99 | Sets granularity of logging. Higher number catches more. | 0-99 |
Many settings in can be overridden by environment variables
[1] | 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. |