JezK
Edit File: freetdsconf.html
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The freetds.conf file</title><link rel="stylesheet" type="text/css" href="userguide.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="FreeTDS User Guide" /><link rel="up" href="install.html" title="Chapter 3. Install FreeTDS" /><link rel="prev" href="name.lookup.html" title="servername Lookup" /><link rel="next" href="locales.html" title="The locales.conf file" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">The <code class="filename">freetds.conf</code> file</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="name.lookup.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Install <span class="productname">FreeTDS</span></th><td width="20%" align="right"> <a accesskey="n" href="locales.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="freetdsconf"></a>The <code class="filename">freetds.conf</code> file</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="freetdsconfpurpose"></a>What it does</h3></div></div></div><p>Just as DNS defines hostnames for network addresses, <code class="filename">freetds.conf</code> uses a <em class="firstterm">servername</em> to define the properties of your server. <a href="#ftn.idm1033" class="footnote" id="idm1033"><sup class="footnote">[7]</sup></a> In particular, <span class="productname">FreeTDS</span> needs to know: </p><div class="itemizedlist"><p class="title"><strong>Primary Server Properties</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Hostname or IP address of the server </p></li><li class="listitem"><p>Port number or Instance name (not both) </p></li><li class="listitem"><p><acronym class="acronym">TDS</acronym> protocol version </p></li></ul></div><p> </p><p></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.gif" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p> <span class="productname">FreeTDS</span> also supports an older configuration file format, known as the <code class="filename">interfaces</code> file. Use <code class="filename">freetds.conf</code> unless <code class="filename">interfaces</code> is needed for your situation. It is easier to read, and it is where all the new options are being added. <span class="productname">FreeTDS</span> looks for <code class="filename">freetds.conf</code> first, falling back on <code class="filename">interfaces</code> only if <code class="filename">freetds.conf</code> is not found.</p><p>Should you need it, more information about <code class="filename">interfaces</code> can be found in the <a class="link" href="interfacesfile.html" title="Appendix B. The interfaces File">Appendix</a>.</p></td></tr></table></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="freetdsconflocation"></a>Where it goes</h3></div></div></div><p>The default location of <code class="filename">freetds.conf</code> is determined by the <code class="literal">--sysconfdir</code> option of <span class="command"><strong>configure</strong></span>. If you don't specify anything, <span class="command"><strong>configure</strong></span>'s default <code class="literal">sysconfdir</code> is <code class="filename">/usr/local/etc</code>. <span class="command"><strong>tsql -C</strong></span> reports the <code class="literal">sysconfdir</code> to let you confirm it.</p><p>In addition, <span class="productname">FreeTDS</span> will look for a file <code class="filename">.freetds.conf</code> in the user's home directory (<code class="envar">${HOME}</code><code class="filename">/.freetds.conf</code>).</p><p>The actual name and location of <code class="filename">freetds.conf</code> may be specified by the environment variable <code class="envar">FREETDS</code> (or <code class="envar">FREETDSCONF</code>, same effect). See <a class="link" href="envvar.html" title="Environment variables">Environment Variables</a>, below.</p><p><span class="productname">FreeTDS</span> reads the user's <em class="replaceable"><code>${HOME}/</code></em><code class="filename">.freetds.conf</code> before resorting to the system-wide <em class="replaceable"><code>sysconfdir/</code></em><code class="filename">freetds.conf</code>. The file used is the first one that is readable and contains a section for the server.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="freetdsconfformat"></a>What it looks like</h3></div></div></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.gif" /></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p> The following information is also provided in the <code class="filename">freetds.conf</code> manual page, cf. <span class="command"><strong>man freetds.conf</strong></span>.</p></td></tr></table></div><p>The <code class="filename">freetds.conf</code> file format is similar to that of Samba's modified <span class="quote">“<span class="quote"><code class="filename">win.ini</code></span>”</span>. It is composed of two types of sections: one <code class="literal">[global]</code> section, and a <code class="literal">[<em class="replaceable"><code>servername</code></em>]</code> section for each servername. Settings in the <code class="literal">[global]</code> section affect all servernames, but can be overridden in a <code class="literal">[<em class="replaceable"><code>servername</code></em>]</code> section. For example</p><div class="example"><a id="e.g.freetdsconf"></a><p class="title"><strong>Example 3.1. A <code class="filename">freetds.conf</code> file example</strong></p><div class="example-contents"><pre class="programlisting"> [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 </pre></div></div><br class="example-break" /><p>In this example, the default <acronym class="acronym">TDS</acronym> version for all servernames is set to <code class="literal">auto</code>. It is then overridden for <code class="literal">myserver2</code> (a Sybase server) which uses <code class="literal">5.0</code>.</p><p>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. </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.gif" /></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>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.</p></td></tr></table></div><p>It bears mentioning here that prior versions of <span class="productname">FreeTDS</span> were quite fussy about domain logins, forcing users to make explicit per-server entries in <code class="filename">freetds.conf</code>. That is no longer the case. If the username has the form <em class="parameter"><code>DOMAIN\username</code></em>, <span class="productname">FreeTDS</span> will automatically use a domain login.</p><div class="table"><a id="tab.freetds.conf"></a><p class="title"><strong>Table 3.3. <code class="filename">freetds.conf</code> settings</strong></p><div class="table-contents"><table class="table" summary="freetds.conf settings" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Possible Values</th><th>Default</th><th>Meaning</th></tr></thead><tbody><tr><td><code class="literal">tds version</code></td><td>4.2, 5.0, 7.0, 7.1, 7.2, 7.3, 7.4, <code class="literal">auto</code></td><td><em class="parameter"><code>--with-tdsver</code></em> value (<code class="literal">auto</code> if unspecified) Overridden by <a class="link" href="envvar.html#TDSVER">TDSVER</a>.</td><td>The <acronym class="acronym">TDS</acronym> protocol version to use when connecting. <span class="quote">“<span class="quote"><code class="literal">auto</code></span>”</span> tells <span class="productname">FreeTDS</span> to use an autodetection (trial-and-error) algorithm to choose the protocol version. </td></tr><tr><td><code class="literal">host</code></td><td>host name or IP address</td><td>none</td><td>The host that the servername is running on.</td></tr><tr><td><code class="literal">port</code></td><td>any valid port</td><td><table class="row" width="100%" border="0"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Product</th><th>Version</th><th>Default Port</th></tr></thead><tbody><tr><td>Sybase <span class="productname">SQL Server</span></td><td>prior to System 10</td><td>1433</td></tr><tr><td>Sybase <span class="productname">SQL Server</span></td><td>10 and up</td><td>5000</td></tr><tr><td>Sybase <span class="productname">SQL Anywhere</span></td><td>7</td><td>2638</td></tr><tr><td>Microsoft <span class="productname">SQL Server</span></td><td>all</td><td>1433</td></tr></tbody></table></td><td> The port number that the servername is listening to. <span class="emphasis"><em>Please note:</em></span> The "defaults" to the left are the server's default settings. <span class="productname">FreeTDS</span> chooses its default port based on the TDS protocol version: <code class="literal">5000</code> for <acronym class="acronym">TDS</acronym> <code class="literal">5.0</code>, and <code class="literal">1433</code> for everything else. Mutually exclusive with <span class="emphasis"><em>instance</em></span>, below. Overridden by <a class="link" href="envvar.html#TDSPORT">TDSPORT</a>. </td></tr><tr><td><code class="literal">instance</code></td><td>instance name</td><td>none</td><td><p>Name of Microsoft SQL Server <span class="emphasis"><em>instance</em></span> to connect to. The port will be detected automatically. Mutually exclusive with <span class="emphasis"><em>port</em></span>, above. Requires UDP connection to port 1434 on the server.</p></td></tr><tr><td><a id="asa.database"></a><code class="literal">ASA database</code></td><td>valid database name</td><td>servername [<em class="replaceable"><code>section</code></em>] name</td><td>Specifies the name of the default database when connecting to an ASA server. A TDS 5.0 login packet has a field called <code class="literal">lservname</code>. For most TDS servers, <code class="literal">lservname</code> is a user-defined string with no inherent meaning. ASA servers, however, requires that <code class="literal">lservname</code> contain a valid database name, and sets that as the default database for the connection. <span class="productname">FreeTDS</span> normally fills <code class="literal">lservname</code> with the [<em class="replaceable"><code>section</code></em>] text.. This entry instead sets the database name independently of the [<em class="replaceable"><code>section</code></em>] name. </td></tr><tr><td><code class="literal">database</code></td><td>valid database name</td><td>none</td><td>Specifies the name of the default database. This is the name of the database container in the server you are connecting to.</td></tr><tr><td><code class="literal">initial block size</code></td><td>multiple of 512</td><td>512</td><td>Specifies the maximum size of a protocol block. Don't mess with unless you know what you are doing.</td></tr><tr><td><code class="literal">dump file</code></td><td>any valid file name</td><td>none Overridden by <a class="link" href="logging.html#TDSDUMP">TDSDUMP</a>. </td><td>Specifies the location of a tds dump file and turns on logging</td></tr><tr><td><code class="literal">dump file append</code></td><td>yes/no</td><td>no</td><td>Appends dump file instead of overwriting it. Useful for debugging when many processes are active.</td></tr><tr><td><code class="literal">timeout</code></td><td>0-</td><td>none</td><td>Sets period to wait for response of query before timing out.</td></tr><tr><td><code class="literal">connect timeout</code></td><td>0-</td><td>none</td><td>Sets period to wait for response from connect before timing out.</td></tr><tr><td><code class="literal">emulate little endian</code></td><td>yes/no</td><td>yes</td><td>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.</td></tr><tr><td><a id="clientcharset"></a><code class="literal">client charset</code></td><td>any valid iconv character set</td><td>ISO-8859-1<a href="#ftn.idm1270" class="footnote" id="idm1270"><sup class="footnote">[a]</sup></a></td><td>Makes <span class="productname">FreeTDS</span> use iconv to convert to and from the specified character set from UCS-2 in <acronym class="acronym">TDS</acronym> 7.0 or above. <span class="productname">FreeTDS</span> 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.</td></tr><tr><td><code class="literal">text size</code></td><td>0 to 4,294,967,295</td><td>4,294,967,295</td><td>default value of TEXTSIZE, in bytes. For <span class="type">text</span> and <span class="type">image</span> datatypes, sets the maximum width of any returned column. Cf. <span class="command"><strong>set TEXTSIZE</strong></span> in the <acronym class="acronym">T-SQL</acronym> documentation for your server. </td></tr><tr><td><code class="literal">debug flags</code></td><td>Any number even in hex or octal notation</td><td>0x4fff</td><td>Sets granularity of logging. A bitmask. See table below for specification.</td></tr><tr><td><code class="literal">encryption</code></td><td>off/request/require</td><td>request (if tds version > 7.1 otherwise off)</td><td>Specify if encryption is desired. Supported for Microsoft servers. <span class="symbol">off</span> disables encryption; <span class="symbol">request</span> means use if available; <span class="symbol">require</span> means create and allow encrypted connections only.</td></tr><tr><td><code class="literal">enable gssapi delegation</code></td><td>on/off</td><td>off</td><td>Enable delegation flag using Kerberos.</td></tr><tr><td><code class="literal">realm</code></td><td>any</td><td>default Kerberos realm</td><td>Specify Kerberos realm.</td></tr><tr><td><code class="literal">SPN</code></td><td>any</td><td>MSSQLSvc/fqdn:port</td><td>Specify Kerberos SPN.</td></tr><tr><td><code class="literal">mutual authentication</code></td><td>on/off</td><td>off</td><td>Enable mutual authentication flag using Kerberos. Always enabled for TDS 7.0 or above.</td></tr><tr><td><code class="literal">use ntlmv2</code></td><td>yes/no</td><td>yes</td><td>Use NTLMv2. An alternative to the <code class="literal">UseNTLMv2</code> option in <code class="filename">odbc.ini</code>. </td></tr><tr><td><code class="literal">use lanman</code></td><td>yes/no</td><td>no</td><td>Use LAN MANAGER for NTLM. This is a very old encryption. Should not be enabled unless you have a really old server.</td></tr><tr><td><code class="literal">use utf-16</code></td><td>yes/no</td><td>no</td><td>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.</td></tr><tr><td><code class="literal">ca file</code></td><td>any filename or <code class="literal">system</code></td><td>none</td><td>File that hold 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 <code class="literal">system</code> <span class="productname">FreeTDS</span> 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. </td></tr><tr><td><code class="literal">crl file</code></td><td>any filename</td><td>none</td><td>File that hold certificate revocation list. Only used if <code class="literal">ca file</code> is also specified. </td></tr><tr><td><code class="literal">check certificate hostname</code></td><td>yes/no</td><td>yes</td><td>Check is the hostname is valid in the certificate. Only used if <code class="literal">ca file</code> is also specified. </td></tr><tr><td><code class="literal">read-only intent</code></td><td>yes/no</td><td>no</td><td>Tell server we only intent to do read-only queries. This is supported from MSSQL 2012. </td></tr><tr><td><code class="literal">enable tls v1</code></td><td>yes/no</td><td>yes</td><td>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.</td></tr></tbody><tbody class="footnotes"><tr><td colspan="4"><div id="ftn.idm1270" class="footnote"><p><a href="#idm1270" class="para"><sup class="para">[a] </sup></a>Valid for ISO 8859-1 character set. See <a class="link" href="Localization.html" title="Localization and TDS 7.0">Localization and <acronym class="acronym">TDS</acronym> 7.0</a> for more information.</p></div></td></tr></tbody></table></div></div><br class="table-break" /><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idm1382"></a>Overrides</h4></div></div></div><p>Many settings in <code class="filename">freetds.conf</code> can be overridden by <a class="link" href="envvar.html" title="Environment variables">environment variables</a>.</p><p>The servername can also be decorated adding the port or instance name using <a class="link" href="PortOverride.html" title="Port/instance override syntax">port override syntax</a>.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idm1389"></a>Controlling log details</h4></div></div></div><div class="abstract"><p class="title"><strong>Abstract</strong></p><p>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.</p></div><p>The log's granularity can be controlled with the <code class="literal">debug flags</code> entry. The default value (<code class="literal">4FFF</code> hex) gives a level of detail that is useful for resolving problems via the mailing list.</p><div class="table"><a id="tab.freetds.conf.debugflags"></a><p class="title"><strong>Table 3.4. Valid bitmask values for <code class="literal">debug flags</code> entry in <code class="filename">freetds.conf</code></strong></p><div class="table-contents"><table class="table" summary="Valid bitmask values for debug flags entry in freetds.conf" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Value</th><th>Meaning</th></tr></thead><tbody><tr><td>0x80</td><td>function trace and info</td></tr><tr><td>0x40</td><td>information level 2</td></tr><tr><td>0x20</td><td>information level 1</td></tr><tr><td>0x10</td><td>network</td></tr><tr><td>0x08</td><td>warning</td></tr><tr><td>0x04</td><td>error</td></tr><tr><td>0x02</td><td>severe error</td></tr><tr><td>0x1000</td><td>show pid</td></tr><tr><td>0x2000</td><td>show time</td></tr><tr><td>0x4000</td><td>show source level info (source file and line)</td></tr><tr><td>0x8000</td><td>thread id (not implemented)</td></tr></tbody></table></div></div><br class="table-break" /><p>For more about the wonderful world of <span class="productname">FreeTDS</span> logs, see <a class="link" href="logging.html" title="Logging">Logging</a>.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idm1442"></a>Deprecated options</h4></div></div></div><p>The following options have long been deprecated.</p><div class="itemizedlist"><a id="lst.freetds.conf.deprecated"></a><p class="title"><strong>Deprecated <code class="filename">freetds.conf</code> settings</strong></p><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p><span class="symbol">try server login</span></p></li><li class="listitem"><p><span class="symbol">try domain login </span></p></li><li class="listitem"><p><span class="symbol">nt domain </span></p></li><li class="listitem"><p><span class="symbol">cross domain login </span></p></li><li class="listitem"><p><span class="symbol">debug level </span></p></li></ul></div></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm1033" class="footnote"><p><a href="#idm1033" class="para"><sup class="para">[7] </sup></a>In general, the servername is arbitrary and local; it's used only by your client programs to tell <span class="productname">FreeTDS</span> which server to connect to. You can choose any name you like.</p><p><span class="productname">Sybase SQL Anywhere</span> (a/k/a Sybase ASA), however, is fussy. Unless you use the <a class="link" href="freetdsconf.html#asa.database">ASA Database</a> property, you must use the database's name as your servername. Otherwise, the server will refuse your connection.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="name.lookup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="install.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="locales.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><em class="replaceable"><code>servername</code></em> Lookup </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> The <code class="filename">locales.conf</code> file</td></tr></table></div></body></html>