TSOCKS(8)

💖 TSOCKS — the tsocks(8) page, but make it cute 💖

okay bestie, so this is the manual page for tsocks, from the System Manager's Manual section 8. it's a library. it's a vibe. let's go 🦋

---

✨ NAME ✨

tsocks — a library that intercepts your outgoing network connections and redirects them through a SOCKS server. no cap, that's literally what it does 💅

---

🌸 SYNOPSIS 🌸

so the whole move here is: set LD_PRELOAD to load the library, then just... use your apps like normal. iconic behavior honestly.

the syntax to force-preload the library differs by shell, and here's the tea:

Bash, Ksh and Bourne shell —

export LD_PRELOAD=/lib/libtsocks.so

C Shell —

setenv LD_PRELOAD=/lib/libtsocks.so

and listen, you can automate this whole thing (for Bash, Bourne and Korn shell girlies) either for a single command or for all commands in a shell session, by using the tsocks(1) script 🎀

you can also set tsocks up so that all processes automatically use it, which is a genuinely very useful configuration. for the deets on that, go read the CAVEATS section of this very manual page. yes, the one you're reading. scroll down. it's there 👑

---

💜 DESCRIPTION 💜

tsocks is a library that lets you do transparent SOCKS proxying. what it does is it wraps the normal connect() function. so when a connection is attempted, it goes and consults the configuration file — which is defined at configure time, but defaults to ~/.tsocks.conf, and if that file can't be accessed, it falls back to /etc/tsocks.conf — and it figures out whether the IP address you specified is local or not.

if it is not local, the library redirects the connection to a SOCKS server that's specified in the configuration file. then it negotiates that connection with the SOCKS server, and hands the connection back to the calling program. teamwork, bestie 🤝

tsocks is designed for machines that are firewalled from the internet. the whole point is that it avoids the need to recompile applications like lynx or telnet just so they can use SOCKS to reach the internet. it behaves a whole lot like the SOCKSified TCP/IP stacks you see on other platforms. slay 💅

🌈 ARGUMENTS 🌈

most arguments to tsocks are provided in the configuration file (the location of which is defined at configure time by the --with-conf=<file> argument, but it defaults to /etc/tsocks.conf). the structure of that file is documented in tsocks.conf(8), go look 👀

some configuration options can be specified at run time using environment variables, like so:

• TSOCKS_CONF_FILE — this environment variable overrides the default location of the tsocks configuration file. heads up though: this variable is not honored if the program tsocks is embedded in is setuid. also, this environment variable can be compiled out of tsocks entirely with the --disable-envconf argument to configure at build time.
• TSOCKS_DEBUG — this environment variable sets the level of debug output that should be generated by tsocks (and debug output is generated in the form of output to standard error, fyi). if this variable isn't present, then by default the logging level is set to 0, which means only error messages get output. setting it to higher values will cause tsocks to generate more messages describing what it's doing. if you set it to -1, tsocks will output absolutely no error or debugging messages. that's only needed if tsocks output interferes with a program it's embedded in. and message output can be permanently compiled out of tsocks by specifying the --disable-debug option to configure at build time.
• TSOCKS_DEBUG_FILE — this option can be used to redirect the tsocks output (which would normally be sent to standard error) to a file. this variable is not honored if the program tsocks is embedded in is setuid. for programs where tsocks output interferes with normal operation, this option is generally better than disabling messages (with TSOCKS_DEBUG = -1). just saying 💁
• TSOCKS_USERNAME — this environment variable can be used to specify the username to be used when version 5 SOCKS servers request username/password authentication. this overrides the default username that can be specified in the configuration file using 'default_user' — see tsocks.conf(8) for more info. this variable is ignored for version 4 SOCKS servers.
• TSOCKS_PASSWORD — this environment variable can be used to specify the password to be used when version 5 SOCKS servers request username/password authentication. this overrides the default password that can be specified in the configuration file using 'default_pass' — see tsocks.conf(8) for more info. this variable is also ignored for version 4 SOCKS servers.

🧚 DNS ISSUES 🧚

so tsocks will normally not be able to send DNS queries through a SOCKS server, because SOCKS V4 works on TCP and DNS normally uses UDP. it's giving mismatch 😭

Version 1.5 and up do however provide a method to force DNS lookups to use TCP, which then makes them proxyable. this option can only be enabled at compile time, so please consult the INSTALL file for more information.

💀 ERRORS 💀

tsocks will generate error messages and print them to stderr when there are problems with the configuration file, or with the SOCKS negotiation with the server — but only if the TSOCKS_DEBUG environment variable is not set to -1, or if --disable-debug was not specified at compile time.

heads up: this output may cause some problems with programs that redirect standard error. 🙈

🚨 CAVEATS 🚨

okay bestie, sit down for this one, this is the important part.

tsocks will not, in the above configuration, be able to provide SOCKS proxying to setuid applications or to applications that are not run from a shell.

you can force all applications to LD_PRELOAD the library by placing the path to libtsocks in /etc/ld.so.preload. but please, please make sure you correctly enter the full path to the library in that file if you do this.

if you get it wrong, you will be UNABLE TO DO ANYTHING with the machine and will have to boot it with a rescue disk and remove the file (or try the saveme program, see the INSTALL file for more info). THIS IS A *WARNING*, please be careful. 😭

also be sure the library is in the root filesystem, because all hell will break loose if the directory it's in is not available at boot time. not exaggerating. 🔥

👑 BUGS 👑

• tsocks can only proxy outgoing TCP connections.
• tsocks does NOT work correctly with asynchronous sockets (though it does work with non blocking sockets). this bug would be very difficult to fix and there appears to be no demand for it (I know of no major application that uses asynchronous sockets).
• tsocks is NOT fully RFC compliant in its implementation of version 5 of SOCKS — it only supports the 'username and password' or 'no authentication' authentication methods. the RFC specifies GSSAPI must be supported by any compliant implementation. I haven't done this, anyone want to help?
• tsocks can force the libc resolver to use TCP for name queries, and if it does this, it does it regardless of whether or not the DNS to be queried is local or not. this introduces overhead and should only be used when needed.
• tsocks uses ELF dynamic loader features to intercept dynamic function calls from programs in which it is embedded. as a result, it cannot trace the actions of statically linked executables, non-ELF executables, or executables that make system calls directly with the system call trap or through the syscall() routine.

🍓 FILES 🍓

• /etc/tsocks.conf — default tsocks configuration file

🌟 SEE ALSO 🌟

tsocks.conf(5) tsocks(1)

💖 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

---

and that's the whole page bestie 🫶 written by Shaun Clowes, and this version of the TSOCKS(8) manual page is the one that lives in the System Manager's Manual — stay safe, don't break /etc/ld.so.preload, and go proxy something 💅✨