Just as DNS defines hostnames for network addresses, freetds.conf uses a servername to define the properties of your server. [7]
In particular, FreeTDS™ needs to know:
Primary Server Properties
Hostname or IP address of the server
Port number or Instance name (not both)
TDS protocol version
![[Note]](../images/note.gif) | Note |
|---|---|
FreeTDS™ also supports an older configuration file format, known as the Should you need it, more information about |
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.
![[Tip]](../images/tip.gif) | Tip |
|---|---|
The following information is also provided in the |
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 [ section for each servername. Settings in the servername][global] section affect all servernames, but can be overridden in a [ section. For exampleservername]
Example 3.1. A freetds.conf file example
[global] tds version = auto [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
In this example, the default TDS version for all servernames is set to auto. It is then overridden for myserver2 (a Sybase server) which uses 5.0.
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.3. freetds.conf settings
| Name | Possible Values | Default | Meaning | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
tds version | 4.2, 5.0, 7.0, 7.1, 7.2, 7.3, 7.4, auto | --with-tdsver value (auto 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. | |||||||||||||||
host | host name or IP address | none | The host that the servername is running on. | |||||||||||||||
port | any valid port |
| 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. | |||||||||||||||
instance | instance name | none | 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 database | valid database name | servername [section] name | Specifies 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. | |||||||||||||||
database | valid database name | none | Specifies the name of the default database. This is the name of the database container in the server you are connecting to. | |||||||||||||||
initial block size | multiple of 512 | 512 | Specifies the maximum size of a protocol block. Don't mess with unless you know what you are doing. | |||||||||||||||
dump file | any valid file name | none Overridden by TDSDUMP. | Specifies the location of a tds dump file and turns on logging | |||||||||||||||
dump file append | yes/no | no | Appends dump file instead of overwriting it. Useful for debugging when many processes are active. | |||||||||||||||
timeout | 0- | none | Sets period to wait for response of query before timing out. | |||||||||||||||
connect timeout | 0- | none | Sets period to wait for response from connect before timing out. | |||||||||||||||
emulate little endian | yes/no | yes | Forces big endian machines (Sparc, PPC, PARISC, MIPS) to act as little endian to communicate with server. Ignored, always use little endian at protocol level. | |||||||||||||||
client charset | any valid iconv character set | ISO-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 size | 0 to 4,294,967,295 | 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. | |||||||||||||||
debug flags | Any number even in hex or octal notation | 0x4fff | Sets granularity of logging. A bitmask. See table below for specification. | |||||||||||||||
encryption | off/request/require | request (if tds version > 7.1 otherwise off) | Specify if encryption is desired. Supported for Microsoft servers. off disables encryption; request means use if available; require means create and allow encrypted connections only. | |||||||||||||||
enable gssapi delegation | on/off | off | Enable delegation flag using Kerberos. | |||||||||||||||
realm | any | default Kerberos realm | Specify Kerberos realm. | |||||||||||||||
SPN | any | MSSQLSvc/fqdn:port | Specify Kerberos SPN. | |||||||||||||||
mutual authentication | on/off | off | Enable mutual authentication flag using Kerberos. Always enabled for TDS 7.0 or above. | |||||||||||||||
use ntlmv2 | yes/no | yes | Use NTLMv2. An alternative to the UseNTLMv2 option in odbc.ini. | |||||||||||||||
use lanman | yes/no | no | Use LAN MANAGER for NTLM. This is a very old encryption. Should not be enabled unless you have a really old server. | |||||||||||||||
use utf-16 | yes/no | yes | Instead of using UCS-2 for database wide character encoding use UTF-16. Newer Windows versions use this encoding instead of UCS-2. This could result in some issues if clients assume that a character is always 2 bytes. | |||||||||||||||
ca file | any filename or system | none | File that holds root certificates (in PEM format) to verify server certificate, used during an encrypted connection.
If not specify or empty any certificate will be accepted from server.
If you specify system FreeTDS™ will use system wide certificate list.
If a certiticate is not installed server can generate a self signed certificate, in this case is useful to disable certificate validation (which is the default).
Note that is not possible to specify a directory as usually database servers does not use a certificate signed by a public global certification authority.
| |||||||||||||||
crl file | any filename | none | File that hold certificate revocation list. Only used if ca file is also specified.
| |||||||||||||||
check certificate hostname | yes/no | yes | Check is the hostname is valid in the certificate. Only used if ca file is also specified.
| |||||||||||||||
read-only intent | yes/no | no | Tell server we only intent to do read-only queries. This is supported from MSSQL 2012. | |||||||||||||||
enable tls v1 | yes/no | no | Enable or disable TLS version 1.0. Useful to increase security. Not too recent Windows version (like Windows 2008) does not enable higher versions by default so be aware. | |||||||||||||||
[a] Valid for ISO 8859-1 character set. See Localization and TDS 7.0 for more information. | ||||||||||||||||||
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.
Abstract
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.4. 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 wonderful world of FreeTDS™ logs, see Logging.
[7] 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.