commit 6e60a47a29a790c361e5402e0bc909904ed9a636 Author: David Goulet dgoulet@ev0ke.net Date: Sat Aug 24 15:19:03 2013 -0400

Update torsocks.8 man page

Signed-off-by: David Goulet dgoulet@ev0ke.net --- doc/torsocks.8 | 268 +++++++++++++++++++++----------------------------------- 1 file changed, 100 insertions(+), 168 deletions(-)

diff --git a/doc/torsocks.8 b/doc/torsocks.8 index 58672e5..1820465 100644 --- a/doc/torsocks.8 +++ b/doc/torsocks.8 @@ -1,189 +1,121 @@ -.TH TORSOCKS 8 "" "Shaun Clowes" " -*- - " nroff -* +.TH "TORSOCKS" "8" "August 24th, 2013" "" ""

.SH NAME -.BR torsocks -- Library for intercepting outgoing network connections and -redirecting them through a SOCKS server.

-.SH SYNOPSIS +torsocks (em Library for intercepting outgoing network connections and +redirecting them through the Tor SOCKS proxy.

-Set LD_PRELOAD to load the library then use applications as normal +.SH DESCRIPTION

-The syntax to force preload of the library for different shells is -specified below: - -Bash, Ksh and Bourne shell - +Torsocks library overloads the libc symbols use for Internet communication such +as \fBconnect(2)\fP system call. Using that technique, the library sends +everything through the Tor network including DNS resolution done by the +application.

-export LD_PRELOAD=/lib/libtorsocks.so +For DNS, \fBgethostbyname(3)\fP family functions are rerouted through Tor. +Please note that the ISC res_* API is currently not supported.

-C Shell - +Here is an example on how to use torsocks library with \fBssh(1)\fP: +.br

-setenv LD_PRELOAD=/lib/libtorsocks.so +$ @LDPRELOAD@=/path/to/libtorsocks.so ssh -l kalexander -p 1234 prism.nsa.gov +[...]

-This process can be automated (for Bash, Bourne and Korn shell -users) for a single command or for all commands in a shell session -by using the torsocks(1) script +.SH SHELL USAGE

-You can also setup torsocks in such a way that all processes -automatically use it, a very useful configuration. For more -information on this configuration see the CAVEATS section of this -manual page. +Set @LDPRELOAD@ to load the library then use applications as normal. The syntax +to force preload of the library for different shells is specified below:

-.SH DESCRIPTION +Bash, Ksh and Bourne shell:

-.BR torsocks -is a library to allow transparent SOCKS proxying. It wraps the normal -connect() function. When a connection is attempted, it consults the -configuration file (which is defined at configure time but defaults to -/etc/torsocks.conf) and determines if the IP address specified is local. If -it is not, the library redirects the connection to a SOCKS server -specified in the configuration file. It then negotiates that connection -with the SOCKS server and passes the connection back to the calling -program. - -.BR torsocks -is designed for use in machines which are firewalled from the -Internet. It avoids the need to recompile applications like lynx or -telnet so they can use SOCKS to reach the Internet. It behaves much like -the SOCKSified TCP/IP stacks seen on other platforms. - -.SS ARGUMENTS -Most arguments to -.BR torsocks -are provided in the configuration file (the location of which is defined -at configure time by the --with-conf=<file> argument but defaults to -/etc/torsocks.conf). The structure of this file is documented in torsocks.conf(8) - -Some configuration options can be specified at run time using environment -variables as follows: - -.TP -.I TORSOCKS_CONFFILE -This environment variable overrides the default location of the torsocks -configuration file. This variable is not honored if the program torsocks -is embedded in is setuid. In addition this environment variable can -be compiled out of torsocks with the --disable-envconf argument to -configure at build time - -.TP -.I TORSOCKS_DEBUG -This environment variable sets the level of debug output that should be -generated by torsocks (debug output is generated in the form of output to -standard error). If this variable is not present by default the logging -level is set to 0 which indicates that only error messages should be output. -Setting it to higher values will cause torsocks to generate more messages -describing what it is doing. If set to -1 torsocks will output absolutely no -error or debugging messages. This is only needed if torsocks output interferes -with a program it is embedded in. Message output can be permanently compiled -out of torsocks by specifying the --disable-debug option to configure at -build time - -.TP -.I TORSOCKS_DEBUG_FILE -This option can be used to redirect the torsocks output (which would normally -be sent to standard error) to a file. This variable is not honored if the -program torsocks is embedded in is setuid. For programs where torsocks output -interferes with normal operation this option is generally better than -disabling messages (with TORSOCKS_DEBUG = -1) - -.TP -.I TORSOCKS_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 torsocks.conf(8) for more information. This -variable is ignored for version 4 SOCKS servers. - -.TP -.I TORSOCKS_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 torsocks.conf(8) for more information. This -variable is ignored for version 4 SOCKS servers. - -.SS DNS ISSUES -.BR torsocks -will normally not be able to send DNS queries through a SOCKS server since -SOCKS V4 works on TCP and DNS normally uses UDP. 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 enabled at compile time, please -consult the INSTALL file for more information. +$ export LD_PRELOAD=/path/to/libtorsocks.so + +C Shell: + +$ setenv LD_PRELOAD=/path/to/libtorsocks.so + +This process can be automated (for Bash, Bourne and Korn shell users) for a +single command or for all commands in a shell session by using the +\fBtorsocks(1)\fP script. + +You can also setup \fBtorsocks(1)\fP in such a way that all processes +automatically use it, a very useful configuration. Please refer to the torsocks +script documentation for more information. + +.SH "ENVIRONMENT VARIABLES"

+.PP +.IP TORSOCKS_CONF_FILE +This environment variable overrides the default location of the torsocks +configuration file. This variable is not honored if the program torsocks is +embedded in is setuid. + +.PP +.IP TORSOCKS_LOG_LEVEL +Enable logging level of torsocks library. By default, warnings and errors are +printed (level 3). Note that each level includes the lower ones except the 1 +which disables any possible logging. (default: 3) + +.TS +tab (@); +l lx. +1@T{ +No log at all. +T} +2@T{ +Error messages. +T} +3@T{ +Warning messages. +T} +4@T{ +Notice messages. +T} +5@T{ +Debug messages. +T} +.TE + +.PP +.IP TORSOCKS_LOG_TIME +Control whether or not the time is added to each logging line. (default: 1) + +.PP +.IP TORSOCKS_LOG_FILE_PATH +If set, torsocks will log in the file set by this variable. (default: stderr) + +.SH KNOWN ISSUES + +.SS DNS +Torsocks is not able to send DNS queries through Tor since UDP is not +supported. Thus, any UDP socket is denied. However, DNS queries that can be +intercept are sent to Tor and sent back to the caller. .SS ERRORS -.BR torsocks -will generate error messages and print them to stderr when there are -problems with the configuration file or the SOCKS negotiation with the -server if the TORSOCKS_DEBUG environment variable is not set to -1 or and ---disable-debug was not specified at compile time. This output may cause -some problems with programs that redirect standard error. - -.SS CAVEATS -.BR torsocks -will not in the above configuration be able to provide SOCKS proxying to -setuid applications or applications that are not run from a shell. You can -force all applications to LD_PRELOAD the library by placing the path to -libtorsocks in /etc/ld.so.preload. Please make sure you correctly enter the -full path to the library in this 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 as all hell -will break loose if the directory it is in is not available at boot time. - -.SH BUGS - -.BR torsocks -can only proxy outgoing TCP connections - -.BR torsocks -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) - -.BR torsocks -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? - -.BR torsocks -can force the libc resolver to use TCP for name queries, 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. - -.BR torsocks -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. +Torsocks might generate error messages and print them to stderr when there are +problems with the configuration file or the SOCKS negotiation with the Tor +daemon. The TORSOCKS_LOG_LEVEL environment variable controls that behavior as +well as the log file option. Keep in mind that this library can output on the +stderr of the application.

-.SH FILES -@CONFDIR@/torsocks.conf - default torsocks configuration file +.SH LIMITATIONS

-.SH SEE ALSO -torsocks.conf(5) -torsocks(1) -usewithtor(1) +Outgoing TCP connections can only be proxified through the Tor network.

-.SH AUTHOR -Shaun Clowes (delius@progsoc.uts.edu.au) +Torsocks forces the libc resolver to use TCP for name queries, 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.

-.SH COPYRIGHT -Copyright 2000 Shaun Clowes +Torsocks uses ELF dynamic loader features to intercept dynamic function calls +from programs in which it is embedded. As a result, non-ELF executables, or +executables that make system calls directly with the system call trap (int +0x80).

-Renamed for use by torsocks to avoid conflict with tsocks by Robert Hogan. +.SH FILES +@CONFDIR@/tor/torsocks.conf - default torsocks configuration file

-torsocks 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). +.SH SEE ALSO +.BR torsocks.conf(5), +.BR torsocks(1)

-This documentation is based on the documentation for logwrites, another -shared library interceptor. One line of code from it was used in -torsocks 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 +.SH AUTHOR +David Goulet dgoulet@ev0ke.net