FREETDS.CONF(5)

📦
version 1.5.20 · 13 versions
, in arch rolling

🎀 freetds.conf — the config file for FreeTDS (yes, THE one) 🎀

okay bestie, so this is the manual page for freetds.conf, and it's genuinely one of those files where knowing it = power. it's LOCAL manual territory, section 5, and it's the config file for FreeTDS. let's get into it 💅

✨ NAME ✨

freetds.conf — the configuration file for FreeTDS, periodt.

🌸 SYNOPSIS 🌸

So. The freetds.conf file is literally the thing that describes your Sybase and Microsoft database servers to the FreeTDS library. It's giving matchmaker.

It's built out of sections, and each section is headed by a servername, followed by a list of connection properties written as name-value pairs. The defaults live in a [global] section, like the main character of the file.

Fun little lore drop: this file supersedes the interfaces file that Sybase defines for the exact same purpose — but don't worry, the interfaces file is still supported. legacy icon behavior, we respect it 🫶

🦋 DESCRIPTION 🦋

A section begins with a servername — that's the name of the server — wrapped in square brackets. The client picks that servername at its own discretion, so go off, choose freely.

⚠️ One (1) exception, and she matters: with Sybase ASA, the servername must match the database name to be used. no cap.

Sections contain properties, one per line, in the form:

name = value

where name is the connection property you're describing. Here's the vibe check on the rules:

  • Servernames and properties are not case sensitive.
  • Values are case-preserving — meaning they get copied literally. literally literally.
  • Comments begin with either a semicolon (;) or a pound sign (#), and run to the end of the line.
  • Blank lines are ignored. (they get no attention, respectfully)
  • Whitespace surrounding the = is ignored.

💖 PROPERTIES 💖

okay this is the big one, the main event, the runway. every property, all of it:

  • client charset — the encoding of client data; this overrides locale(1) settings.
    • Domain: iconv character set names
    • Default: ISO-8859-1
  • connect timeout — the number of seconds to wait for a response from a connect request.
    • Domain: 0 to MAX_INT
    • Default: none
  • debug flags — the logging granularity, i.e. how spicy your logs get.
    • Domain: 32-bit integer
    • Default: 0x4fff
  • dump file — specifies the location of a logfile AND turns on logging. two jobs, ate.
    • Domain: valid file name
    • Default: none
  • dump file append — log data gets appended to the file instead of being re-written for each connection.
    • Domain: yes/no
    • Default: no
  • emulate little endian — forces big endian machines to act as little endian so they can communicate with Microsoft Servers. she's method acting 💀
    • Domain: yes/no
    • Default: no
  • encryption — three moods:
    • off — disables encryption
    • request — use it if it's available (this is the default when the tds version is greater than 7.0)
    • required — allow encrypted connections only
  • host — the name of the host the server is running on.
    • Domain: host name or IP address
    • Default: SYBASE
  • initial block size — the maximum size of a protocol block.
    • Domain: multiple of 512
    • Default: 512
  • instance — the name of the Microsoft SQL Server instance to connect to (this supersedes port).
    • Domain: instance name
    • Default: none
  • port — the port number that the server is listening to.
    • Domain: any valid port
    • Default: TDS 5.0, 5000; TDS 7.0 and up, 1433
  • tds version — the TDS protocol version to use.
    • Domain: 4.2, 5.0, 7.0, 7.1, 7.2
    • Default: the --with-tdsver value (5.0 if unspecified)
  • text size — the default value of TEXTSIZE, in bytes.
    • Domain: 0 to 4,294,967,295
    • Default: 4,294,967,295
  • timeout — the number of seconds to wait for a response to a query.
    • Domain: 0 to MAX_INT
    • Default: none (wait forever — she's patient, she's loyal, she will literally wait for you 🫶)
🚨 Do not define both port and instance. One implies the other. pick a lane bestie.

Also, Boolean property values may be denoted as on/off, true/false, or 1/0. mix and match, it's your world.

🔥 DEBUG FLAGS 🔥

The log's granularity can be controlled with the debug flags property. Here's the whole menu, no skipping:

  • 0x02 — severe error
  • 0x04 — error
  • 0x08 — warning
  • 0x10 — network
  • 0x20 — information level 1
  • 0x40 — information level 2
  • 0x80 — function trace and info
  • 0x1000 — show pid
  • 0x2000 — show time
  • 0x4000 — show source level info (source file and line)
  • 0x8000 — thread id (not implemented). yeah. she's not implemented. it's giving unfinished business 😭

🧚 NAMES AND LOCATIONS 🧚

The file is normally named /etc/freetds.conf or ${HOME}/.freetds.conf.

That name can be overridden with the FREETDSCONF environment variable. (yes, that's the actual name, all caps, no underscore between FREE and TDS, iykyk)

FreeTDS will search conf files for a servername in this exact order:

  1. a filename set programmatically via dbsetifile() that is in .conf format
  2. a filename in the environment variable FREETDSCONF that is in .conf format
  3. ${HOME}/.freetds.conf if extant
  4. /etc/freetds/freetds.conf

And the search stops with the first file containing the servername. first come, first served, no crumbing.

If no conf file is found, FreeTDS searches for an interfaces file, in this order:

  1. a filename set programmatically via dbsetifile() that is in interfaces format
  2. ${HOME}/.interfaces
  3. $SYBASE/interfaces (where $SYBASE is an environment variable)

If the requested servername is not found in any configuration file, the fallback mechanism kicks in like a backup dancer:

  1. attempt to convert the name to an IP address with inet_addr(3), else
  2. attempt to convert the name to an IP address with gethostbyname(3), else
  3. attempt to look up the literal name SYBASE

she's resilient. she's trying her best. 💜

⭐ ENVIRONMENT ⭐

  • FREETDSCONF — overrides the name and location of the system-wide conf file
  • TDSDUMP — overrides the name and location of the FreeTDS log file
  • TDSDUMPCONFIG — specifies a name and location of a file that logs the search of configuration files
  • TDSHOST — overrides the host property
  • TDSPORT — overrides the port property
  • TDSQUERY — synonym for DSQUERY, the default servername
  • TDSVER — overrides the version specified in the freetds.conf
💡 The environment variables TDSVER, TDSDUMP, TDSPORT, TDSQUERY, and TDSHOST override values set by a .conf or interfaces file. env vars said "i'm the main character now."

🌈 FILES 🌈

/etc/freetds/freetds.conf
${HOME}/.freetds.conf

two paths. that's the whole list. iconic minimalism.

👑 SEE ALSO 👑

FreeTDS User Guide — go read her, she's thorough.

🍓 HISTORY 🍓

.conf files first appeared with version 0.53 of FreeTDS. a little origin story, we love a glow-up ✨

and that's the page, bestie!! this was FreeTDS 1.5.20, dated May 2, 2017, and you can find it filed under FREETDS.CONF(FreeTDS 5). go config your servers, you're gonna slay 💅🎀

📦 where this page comes from