[tor-commits] [torsocks/master] Update torsocks.8 man page

Fri Apr 4 22:40:26 UTC 2014

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

    Update torsocks.8 man page
    
    Signed-off-by: David Goulet <dgoulet at 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 at T{
+No log at all.
+T}
+2 at T{
+Error messages.
+T}
+3 at T{
+Warning messages.
+T}
+4 at T{
+Notice messages.
+T}
+5 at 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
- at 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 at 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
+ at 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 at yggdrasil.com (Adam J. Richter) and can be had from ftp.yggdrasil.com
-pub/dist/pkg
+.SH AUTHOR
+David Goulet <dgoulet at ev0ke.net>



