TSOCKS.CONF(5)

🎀 tsocks.conf — the config file for tsocks(8) 💅

okay bestie, welcome to TSOCKS.CONF(5), from the File Formats Manual section of your friendly neighbourhood manpages 🦋 this is literally the glow-up guide for your tsocks(8) setup and i'm so excited to walk you through it 💖

---

✨ OVERVIEW ✨

the config for tsocks can be anything — from two little lines to hundreds of lines, depending on what your site actually needs. the vibe is simple: you tell it which networks this machine can reach directly (aka no SOCKS server needed, we're walking, not taking the bus) and then you define one or many SOCKS servers for reaching everything else — including a default server. 👑

local networks get declared with the local keyword in the config file. when an app tries to connect to a machine in a network you've marked as local, tsocks will not try to use a SOCKS server to negotiate the connection. periodt. 🚫

obviously if a connection isn't to a locally accessible network it's gonna need to be proxied over a SOCKS server. but here's the thing — lots of installations have several different SOCKS servers, each used to reach different internal (and external) networks. so for that reason the config file lets you define ´paths´ and a default SOCKS server. 🌈

paths are declared as blocks in the config file. that means they start with a path { line and end with a } line. inside that block you drop directives to declare a SOCKS server (documented further down, don't worry bestie) and you use reaches directives to declare networks — and even destination ports in those networks — that this particular server should be used to reach.

N.B. Each path MUST define a SOCKS server and contain one or more reaches directives. no server, no reaches, no path. that's the rule fr fr 💀

SOCKS server declaration directives that are not inside a path block define the default SOCKS server. so if tsocks needs to connect to a machine via a SOCKS server (i.e. it's not a network declared as local) and no path has declared it can reach that network via a reaches directive, this server is the one used to negotiate the connection. it's the main character fallback 🫶

---

🌸 CONFIGURATION SYNTAX 🌸

the basic structure of every line in the config file is:

<directive> = <parameters>

the exception to this (there's always an exception, iconic) is path blocks, which look like:

path {
       <directive> = <parameters>
}

empty lines are ignored, and all input on a line after a # character is ignored. so go ahead and comment your life away 💜

---

💅 DIRECTIVES

these are the directives used in the tsocks config file:

• server — the IP address of the SOCKS server (e.g. "server = 10.1.4.253"). only one server may be specified per path block, or one outside a path block (to define the default server). unless --disable-hostnames was specified to configure at compile time, the server can also be given as a hostname (e.g. "server = socks.nec.com") ✨
• server_port — the port on which the SOCKS server receives requests. only one server_port may be specified per path block, or one outside a path (for the default server). this directive is not required if the server is on the standard port (1080). lowkey convenient 🎀
• server_type — the SOCKS version used by the server. versions 4 and 5 are supported (but both for only the connect operation). the default is 4. only one server_type may be specified per path block, or one outside a path (for the default server).

you can use the inspectsocks utility to determine the type of server — see the 'UTILITIES' section later in this manual page. i gotchu 👀

• default_user — this specifies the default username to be used for username and password authentication in SOCKS version 5. in order to determine the username to use (if the socks server requires username and password authentication), tsocks first looks for the environment variable TSOCKS_USERNAME, then looks for this configuration option, then tries to get the local username. this option is not valid for SOCKS version 4 servers. only one default_user may be specified per path block, or one outside a path (for the default server) 🔐
• default_pass — this specified the default password to be used for username and password authentication in SOCKS version 5. in order to determine the password to use (if the socks server requires username and password authentication), tsocks first looks for the environment variable TSOCKS_PASSWORD, then looks for this configuration option. this option is not valid for SOCKS version 4 servers. onle one default_pass may be specified per path block, or one outside a path (for the default server) 🙈
• local — an IP/Subnet pair specifying a network which may be accessed directly without proxying through a SOCKS server (e.g. "local = 10.0.0.0/255.0.0.0"). obviously all SOCKS server IP addresses must be in networks specified as local, otherwise tsocks would need a SOCKS server to reach SOCKS servers. and that's a whole chicken-and-egg situation bestie 😭
• reaches — this directive is only valid inside a path block. its parameter is formed as IP[:startport[-endport]]/Subnet and it specifies a network (and a range of ports on that network) that can be accessed by the SOCKS server specified in this path block. for example, in a path block "reaches = 150.0.0.0:80-1024/255.0.0.0" indicates to tsocks that the SOCKS server specified in the current path block should be used to access any IPs in the range 150.0.0.0 to 150.255.255.255 when the connection request is for ports 80-1024. chef's kiss syntax 🍓
• fallback — this directive allows one to fall back to direct connection if no default server present in the configuration and fallback = yes. if fallback = no or not specified and there is no default server, tsocks gives an error message and aborts. this parameter protects the user against accidentally establishing unwanted unsockified (ie. direct) connection.

okay so this one is a safety feature, not a suggestion. if you don't set it, tsocks just dies rather than silently making a raw connection. respect it 💀

---

🦋 CONFIGURATION FILE SEARCH ORDER 🦋

tsocks will search first for $HOME/.tsocks.conf then /etc/tsocks.conf

(your home directory gets first dibs, then the system-wide one. home turf advantage ✨)

---

🧚 UTILITIES 🧚

tsocks comes with two utilities that can be useful in creating and verifying the tsocks configuration file. little helpers, we love them 💖

• inspectsocks — inspectsocks can be used to determine the SOCKS version that a server supports. inspectsocks takes as its arguments the ip address/hostname of the SOCKS server and optionally the port number for socks (e.g. 'inspectsocks socks.nec.com 1080'). it then inspects that server to attempt to determine the version that server supports 👑
• validateconf — validateconf can be used to verify the configuration file. it checks the format of the file and also the contents for errors. having read the file it dumps the configuration to the screen in a formatted, readable manner. this can be extremely useful in debugging problems.

validateconf can read a configuration file from a location other than the location specified at compile time with the -f <filename> command line option.

normally validateconf simply dumps the configuration read to the screen (in a nicely readable format), however it also has a useful 'test' mode. when passed a hostname/ip on the command line like -t <hostname/ip>, validateconf determines which of the SOCKS servers specified in the configuration file would be used by tsocks to access the specified host. it's giving psychic but make it networking 🔮

---

⭐ SEE ALSO ⭐

• tsocks(8)

---

👑 AUTHOR 👑

Shaun Clowes (delius@progsoc.uts.edu.au)

---

🌈 COPYRIGHT 🌈

Copyright 2000 Shaun Clowes

tsocks and its documentation may be freely copied under the terms and conditions of version 2 of the GNU General Public License, as published by the Free Software Foundation (Cambridge, Massachusetts, United States of America).

this documentation is based on the documentation for logwrites, another shared library interceptor. one line of code from it was used in tsocks and a lot of the documentation :) logwrites is by adam@yggdrasil.com (Adam J. Richter) and can be had from ftp.yggdrasil.com pub/dist/pkg

---

okay that's the whole page bestie, and to sign off properly: this little masterpiece was written by Shaun Clowes, living in the TSOCKS.CONF(5) section of the manual 💖 no cap, that's the whole thing — now go configure something and slay 💅✨🦋