commit ac681d8428a08d030ab3ab4608eddf9529159f6e Author: Robert Hogan <robert@roberthogan.net> Date: Sun Feb 27 12:39:21 2011 +0000 Move man pages and configuration files to docs folder --- Makefile.am | 2 +- configure.in | 4 +- doc/SOCKS4.protocol | 150 --------------------------- doc/SOCKS5 | 2 - doc/socks-extensions.txt | 79 -------------- doc/socks/SOCKS4.protocol | 150 +++++++++++++++++++++++++++ doc/socks/SOCKS5 | 2 + doc/socks/socks-extensions.txt | 79 ++++++++++++++ doc/torsocks.1.in | 63 ++++++++++++ doc/torsocks.8.in | 189 ++++++++++++++++++++++++++++++++++ doc/torsocks.conf | 56 ++++++++++ doc/torsocks.conf.5.in | 214 +++++++++++++++++++++++++++++++++++++++ doc/tsocks.conf.complex.example | 47 +++++++++ doc/tsocks.conf.simple.example | 16 +++ doc/usewithtor.1.in | 57 ++++++++++ src/Makefile.am | 17 --- src/torsocks.1.in | 63 ------------ src/torsocks.8.in | 189 ---------------------------------- src/torsocks.conf | 56 ---------- src/torsocks.conf.5.in | 214 --------------------------------------- src/tsocks.conf.complex.example | 47 --------- src/tsocks.conf.simple.example | 16 --- src/usewithtor.1.in | 57 ---------- 23 files changed, 876 insertions(+), 893 deletions(-) diff --git a/Makefile.am b/Makefile.am index 44a7fbd..0ef8147 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2,4 +2,4 @@ # have all needed files, that a GNU package needs AUTOMAKE_OPTIONS = foreign 1.4 -SUBDIRS = src test +SUBDIRS = src doc test diff --git a/configure.in b/configure.in index f74a3fd..a89fa0e 100644 --- a/configure.in +++ b/configure.in @@ -634,10 +634,10 @@ AC_SUBST(LIBTOOL_DEPS) AC_ENABLE_SHARED AC_ENABLE_STATIC -AC_CONFIG_FILES([src/usewithtor src/torsocks src/torsocks.conf.5 src/torsocks.8 src/usewithtor.1 src/torsocks.1]) +AC_CONFIG_FILES([src/usewithtor src/torsocks doc/torsocks.conf.5 doc/torsocks.8 doc/usewithtor.1 doc/torsocks.1]) dnl Output the Makefile for libtorsocks -AC_OUTPUT(Makefile src/Makefile) +AC_OUTPUT(Makefile src/Makefile doc/Makefile) dnl Output the Makefile for test/test_torsocks. dnl Dump any LDFLAGS that were only required for linking libtorsocks, such as -dynamiclib on OSX. diff --git a/doc/SOCKS4.protocol b/doc/SOCKS4.protocol deleted file mode 100644 index 50fa5a7..0000000 --- a/doc/SOCKS4.protocol +++ /dev/null @@ -1,150 +0,0 @@ - SOCKS: A protocol for TCP proxy across firewalls - - Ying-Da Lee - yingda@best.com or yingda@esd.sgi.com - -SOCKS was originally developed by David Koblas and subsequently modified -and extended by me to its current running version -- version 4. It is a -protocol that relays TCP sessions at a firewall host to allow application -users transparent access across the firewall. Because the protocol is -independent of application protocols, it can be (and has been) used for -many different services, such as telnet, ftp, finger, whois, gopher, WWW, -etc. Access control can be applied at the beginning of each TCP session; -thereafter the server simply relays the data between the client and the -application server, incurring minimum processing overhead. Since SOCKS -never has to know anything about the application protocol, it should also -be easy for it to accommodate applications which use encryption to protect -their traffic from nosey snoopers. - -Two operations are defined: CONNECT and BIND. - -1) CONNECT - -The client connects to the SOCKS server and sends a CONNECT request when -it wants to establish a connection to an application server. The client -includes in the request packet the IP address and the port number of the -destination host, and userid, in the following format. - - +----+----+----+----+----+----+----+----+----+----+....+----+ - | VN | CD | DSTPORT | DSTIP | USERID |NULL| - +----+----+----+----+----+----+----+----+----+----+....+----+ - # of bytes: 1 1 2 4 variable 1 - -VN is the SOCKS protocol version number and should be 4. CD is the -SOCKS command code and should be 1 for CONNECT request. NULL is a byte -of all zero bits. - -The SOCKS server checks to see whether such a request should be granted -based on any combination of source IP address, destination IP address, -destination port number, the userid, and information it may obtain by -consulting IDENT, cf. RFC 1413. If the request is granted, the SOCKS -server makes a connection to the specified port of the destination host. -A reply packet is sent to the client when this connection is established, -or when the request is rejected or the operation fails. - - +----+----+----+----+----+----+----+----+ - | VN | CD | DSTPORT | DSTIP | - +----+----+----+----+----+----+----+----+ - # of bytes: 1 1 2 4 - -VN is the version of the reply code and should be 0. CD is the result -code with one of the following values: - - 90: request granted - 91: request rejected or failed - 92: request rejected becasue SOCKS server cannot connect to - identd on the client - 93: request rejected because the client program and identd - report different user-ids - -The remaining fields are ignored. - -The SOCKS server closes its connection immediately after notifying -the client of a failed or rejected request. For a successful request, -the SOCKS server gets ready to relay traffic on both directions. This -enables the client to do I/O on its connection as if it were directly -connected to the application server. - - -2) BIND - -The client connects to the SOCKS server and sends a BIND request when -it wants to prepare for an inbound connection from an application server. -This should only happen after a primary connection to the application -server has been established with a CONNECT. Typically, this is part of -the sequence of actions: - --bind(): obtain a socket --getsockname(): get the IP address and port number of the socket --listen(): ready to accept call from the application server --use the primary connection to inform the application server of - the IP address and the port number that it should connect to. --accept(): accept a connection from the application server - -The purpose of SOCKS BIND operation is to support such a sequence -but using a socket on the SOCKS server rather than on the client. - -The client includes in the request packet the IP address of the -application server, the destination port used in the primary connection, -and the userid. - - +----+----+----+----+----+----+----+----+----+----+....+----+ - | VN | CD | DSTPORT | DSTIP | USERID |NULL| - +----+----+----+----+----+----+----+----+----+----+....+----+ - # of bytes: 1 1 2 4 variable 1 - -VN is again 4 for the SOCKS protocol version number. CD must be 2 to -indicate BIND request. - -The SOCKS server uses the client information to decide whether the -request is to be granted. The reply it sends back to the client has -the same format as the reply for CONNECT request, i.e., - - +----+----+----+----+----+----+----+----+ - | VN | CD | DSTPORT | DSTIP | - +----+----+----+----+----+----+----+----+ - # of bytes: 1 1 2 4 - -VN is the version of the reply code and should be 0. CD is the result -code with one of the following values: - - 90: request granted - 91: request rejected or failed - 92: request rejected becasue SOCKS server cannot connect to - identd on the client - 93: request rejected because the client program and identd - report different user-ids. - -However, for a granted request (CD is 90), the DSTPORT and DSTIP fields -are meaningful. In that case, the SOCKS server obtains a socket to wait -for an incoming connection and sends the port number and the IP address -of that socket to the client in DSTPORT and DSTIP, respectively. If the -DSTIP in the reply is 0 (the value of constant INADDR_ANY), then the -client should replace it with the IP address of the SOCKS server to which -the cleint is connected. (This happens if the SOCKS server is not a -multi-homed host.) In the typical scenario, these two numbers are -made available to the application client prgram via the result of the -subsequent getsockname() call. The application protocol must provide a -way for these two pieces of information to be sent from the client to -the application server so that it can initiate the connection, which -connects it to the SOCKS server rather than directly to the application -client as it normally would. - -The SOCKS server sends a second reply packet to the client when the -anticipated connection from the application server is established. -The SOCKS server checks the IP address of the originating host against -the value of DSTIP specified in the client's BIND request. If a mismatch -is found, the CD field in the second reply is set to 91 and the SOCKS -server closes both connections. If the two match, CD in the second -reply is set to 90 and the SOCKS server gets ready to relay the traffic -on its two connections. From then on the client does I/O on its connection -to the SOCKS server as if it were directly connected to the application -server. - - - -For both CONNECT and BIND operations, the server sets a time limit -(2 minutes in current CSTC implementation) for the establishment of its -connection with the application server. If the connection is still not -establiched when the time limit expires, the server closes its connection -to the client and gives up. diff --git a/doc/SOCKS5 b/doc/SOCKS5 deleted file mode 100644 index 40dfcbd..0000000 --- a/doc/SOCKS5 +++ /dev/null @@ -1,2 +0,0 @@ -http://www.ietf.org/rfc/rfc1928.txt - diff --git a/doc/socks-extensions.txt b/doc/socks-extensions.txt deleted file mode 100644 index 99e2b51..0000000 --- a/doc/socks-extensions.txt +++ /dev/null @@ -1,79 +0,0 @@ -$Id: socks-extensions.txt,v 1.1 2008-06-18 21:17:02 hoganrobert Exp $ -Tor's extensions to the SOCKS protocol - -1. Overview - - The SOCKS protocol provides a generic interface for TCP proxies. Client - software connects to a SOCKS server via TCP, and requests a TCP connection - to another address and port. The SOCKS server establishes the connection, - and reports success or failure to the client. After the connection has - been established, the client application uses the TCP stream as usual. - - Tor supports SOCKS4 as defined in [1], SOCKS4A as defined in [2], and - SOCKS5 as defined in [3]. - - The stickiest issue for Tor in supporting clients, in practice, is forcing - DNS lookups to occur at the OR side: if clients do their own DNS lookup, - the DNS server can learn which addresses the client wants to reach. - SOCKS4 supports addressing by IPv4 address; SOCKS4A is a kludge on top of - SOCKS4 to allow addressing by hostname; SOCKS5 supports IPv4, IPv6, and - hostnames. - -1.1. Extent of support - - Tor supports the SOCKS4, SOCKS4A, and SOCKS5 standards, except as follows: - - BOTH: - - The BIND command is not supported. - - SOCKS4,4A: - - SOCKS4 usernames are ignored. - - SOCKS5: - - The (SOCKS5) "UDP ASSOCIATE" command is not supported. - - IPv6 is not supported in CONNECT commands. - - Only the "NO AUTHENTICATION" (SOCKS5) authentication method [00] is - supported. - -2. Name lookup - - As an extension to SOCKS4A and SOCKS5, Tor implements a new command value, - "RESOLVE" [F0]. When Tor receives a "RESOLVE" SOCKS command, it initiates - a remote lookup of the hostname provided as the target address in the SOCKS - request. The reply is either an error (if the address couldn't be - resolved) or a success response. In the case of success, the address is - stored in the portion of the SOCKS response reserved for remote IP address. - - (We support RESOLVE in SOCKS4 too, even though it is unnecessary.) - - For SOCKS5 only, we support reverse resolution with a new command value, - "RESOLVE_PTR" [F1]. In response to a "RESOLVE_PTR" SOCKS5 command with - an IPv4 address as its target, Tor attempts to find the canonical - hostname for that IPv4 record, and returns it in the "server bound - address" portion of the reply. - (This command was not supported before Tor 0.1.2.2-alpha.) - -3. Other command extensions. - - Tor 0.1.2.4-alpha added a new command value: "CONNECT_DIR" [F2]. - In this case, Tor will open an encrypted direct TCP connection to the - directory port of the Tor server specified by address:port (the port - specified should be the ORPort of the server). It uses a one-hop tunnel - and a "BEGIN_DIR" relay cell to accomplish this secure connection. - - The F2 command value was removed in Tor 0.2.0.10-alpha in favor of a - new use_begindir flag in edge_connection_t. - -4. HTTP-resistance - - Tor checks the first byte of each SOCKS request to see whether it looks - more like an HTTP request (that is, it starts with a "G", "H", or "P"). If - so, Tor returns a small webpage, telling the user that his/her browser is - misconfigured. This is helpful for the many users who mistakenly try to - use Tor as an HTTP proxy instead of a SOCKS proxy. - -References: - [1] http://archive.socks.permeo.com/protocol/socks4.protocol - [2] http://archive.socks.permeo.com/protocol/socks4a.protocol - [3] SOCKS5: RFC1928 - diff --git a/doc/socks/SOCKS4.protocol b/doc/socks/SOCKS4.protocol new file mode 100644 index 0000000..50fa5a7 --- /dev/null +++ b/doc/socks/SOCKS4.protocol @@ -0,0 +1,150 @@ + SOCKS: A protocol for TCP proxy across firewalls + + Ying-Da Lee + yingda@best.com or yingda@esd.sgi.com + +SOCKS was originally developed by David Koblas and subsequently modified +and extended by me to its current running version -- version 4. It is a +protocol that relays TCP sessions at a firewall host to allow application +users transparent access across the firewall. Because the protocol is +independent of application protocols, it can be (and has been) used for +many different services, such as telnet, ftp, finger, whois, gopher, WWW, +etc. Access control can be applied at the beginning of each TCP session; +thereafter the server simply relays the data between the client and the +application server, incurring minimum processing overhead. Since SOCKS +never has to know anything about the application protocol, it should also +be easy for it to accommodate applications which use encryption to protect +their traffic from nosey snoopers. + +Two operations are defined: CONNECT and BIND. + +1) CONNECT + +The client connects to the SOCKS server and sends a CONNECT request when +it wants to establish a connection to an application server. The client +includes in the request packet the IP address and the port number of the +destination host, and userid, in the following format. + + +----+----+----+----+----+----+----+----+----+----+....+----+ + | VN | CD | DSTPORT | DSTIP | USERID |NULL| + +----+----+----+----+----+----+----+----+----+----+....+----+ + # of bytes: 1 1 2 4 variable 1 + +VN is the SOCKS protocol version number and should be 4. CD is the +SOCKS command code and should be 1 for CONNECT request. NULL is a byte +of all zero bits. + +The SOCKS server checks to see whether such a request should be granted +based on any combination of source IP address, destination IP address, +destination port number, the userid, and information it may obtain by +consulting IDENT, cf. RFC 1413. If the request is granted, the SOCKS +server makes a connection to the specified port of the destination host. +A reply packet is sent to the client when this connection is established, +or when the request is rejected or the operation fails. + + +----+----+----+----+----+----+----+----+ + | VN | CD | DSTPORT | DSTIP | + +----+----+----+----+----+----+----+----+ + # of bytes: 1 1 2 4 + +VN is the version of the reply code and should be 0. CD is the result +code with one of the following values: + + 90: request granted + 91: request rejected or failed + 92: request rejected becasue SOCKS server cannot connect to + identd on the client + 93: request rejected because the client program and identd + report different user-ids + +The remaining fields are ignored. + +The SOCKS server closes its connection immediately after notifying +the client of a failed or rejected request. For a successful request, +the SOCKS server gets ready to relay traffic on both directions. This +enables the client to do I/O on its connection as if it were directly +connected to the application server. + + +2) BIND + +The client connects to the SOCKS server and sends a BIND request when +it wants to prepare for an inbound connection from an application server. +This should only happen after a primary connection to the application +server has been established with a CONNECT. Typically, this is part of +the sequence of actions: + +-bind(): obtain a socket +-getsockname(): get the IP address and port number of the socket +-listen(): ready to accept call from the application server +-use the primary connection to inform the application server of + the IP address and the port number that it should connect to. +-accept(): accept a connection from the application server + +The purpose of SOCKS BIND operation is to support such a sequence +but using a socket on the SOCKS server rather than on the client. + +The client includes in the request packet the IP address of the +application server, the destination port used in the primary connection, +and the userid. + + +----+----+----+----+----+----+----+----+----+----+....+----+ + | VN | CD | DSTPORT | DSTIP | USERID |NULL| + +----+----+----+----+----+----+----+----+----+----+....+----+ + # of bytes: 1 1 2 4 variable 1 + +VN is again 4 for the SOCKS protocol version number. CD must be 2 to +indicate BIND request. + +The SOCKS server uses the client information to decide whether the +request is to be granted. The reply it sends back to the client has +the same format as the reply for CONNECT request, i.e., + + +----+----+----+----+----+----+----+----+ + | VN | CD | DSTPORT | DSTIP | + +----+----+----+----+----+----+----+----+ + # of bytes: 1 1 2 4 + +VN is the version of the reply code and should be 0. CD is the result +code with one of the following values: + + 90: request granted + 91: request rejected or failed + 92: request rejected becasue SOCKS server cannot connect to + identd on the client + 93: request rejected because the client program and identd + report different user-ids. + +However, for a granted request (CD is 90), the DSTPORT and DSTIP fields +are meaningful. In that case, the SOCKS server obtains a socket to wait +for an incoming connection and sends the port number and the IP address +of that socket to the client in DSTPORT and DSTIP, respectively. If the +DSTIP in the reply is 0 (the value of constant INADDR_ANY), then the +client should replace it with the IP address of the SOCKS server to which +the cleint is connected. (This happens if the SOCKS server is not a +multi-homed host.) In the typical scenario, these two numbers are +made available to the application client prgram via the result of the +subsequent getsockname() call. The application protocol must provide a +way for these two pieces of information to be sent from the client to +the application server so that it can initiate the connection, which +connects it to the SOCKS server rather than directly to the application +client as it normally would. + +The SOCKS server sends a second reply packet to the client when the +anticipated connection from the application server is established. +The SOCKS server checks the IP address of the originating host against +the value of DSTIP specified in the client's BIND request. If a mismatch +is found, the CD field in the second reply is set to 91 and the SOCKS +server closes both connections. If the two match, CD in the second +reply is set to 90 and the SOCKS server gets ready to relay the traffic +on its two connections. From then on the client does I/O on its connection +to the SOCKS server as if it were directly connected to the application +server. + + + +For both CONNECT and BIND operations, the server sets a time limit +(2 minutes in current CSTC implementation) for the establishment of its +connection with the application server. If the connection is still not +establiched when the time limit expires, the server closes its connection +to the client and gives up. diff --git a/doc/socks/SOCKS5 b/doc/socks/SOCKS5 new file mode 100644 index 0000000..40dfcbd --- /dev/null +++ b/doc/socks/SOCKS5 @@ -0,0 +1,2 @@ +http://www.ietf.org/rfc/rfc1928.txt + diff --git a/doc/socks/socks-extensions.txt b/doc/socks/socks-extensions.txt new file mode 100644 index 0000000..99e2b51 --- /dev/null +++ b/doc/socks/socks-extensions.txt @@ -0,0 +1,79 @@ +$Id: socks-extensions.txt,v 1.1 2008-06-18 21:17:02 hoganrobert Exp $ +Tor's extensions to the SOCKS protocol + +1. Overview + + The SOCKS protocol provides a generic interface for TCP proxies. Client + software connects to a SOCKS server via TCP, and requests a TCP connection + to another address and port. The SOCKS server establishes the connection, + and reports success or failure to the client. After the connection has + been established, the client application uses the TCP stream as usual. + + Tor supports SOCKS4 as defined in [1], SOCKS4A as defined in [2], and + SOCKS5 as defined in [3]. + + The stickiest issue for Tor in supporting clients, in practice, is forcing + DNS lookups to occur at the OR side: if clients do their own DNS lookup, + the DNS server can learn which addresses the client wants to reach. + SOCKS4 supports addressing by IPv4 address; SOCKS4A is a kludge on top of + SOCKS4 to allow addressing by hostname; SOCKS5 supports IPv4, IPv6, and + hostnames. + +1.1. Extent of support + + Tor supports the SOCKS4, SOCKS4A, and SOCKS5 standards, except as follows: + + BOTH: + - The BIND command is not supported. + + SOCKS4,4A: + - SOCKS4 usernames are ignored. + + SOCKS5: + - The (SOCKS5) "UDP ASSOCIATE" command is not supported. + - IPv6 is not supported in CONNECT commands. + - Only the "NO AUTHENTICATION" (SOCKS5) authentication method [00] is + supported. + +2. Name lookup + + As an extension to SOCKS4A and SOCKS5, Tor implements a new command value, + "RESOLVE" [F0]. When Tor receives a "RESOLVE" SOCKS command, it initiates + a remote lookup of the hostname provided as the target address in the SOCKS + request. The reply is either an error (if the address couldn't be + resolved) or a success response. In the case of success, the address is + stored in the portion of the SOCKS response reserved for remote IP address. + + (We support RESOLVE in SOCKS4 too, even though it is unnecessary.) + + For SOCKS5 only, we support reverse resolution with a new command value, + "RESOLVE_PTR" [F1]. In response to a "RESOLVE_PTR" SOCKS5 command with + an IPv4 address as its target, Tor attempts to find the canonical + hostname for that IPv4 record, and returns it in the "server bound + address" portion of the reply. + (This command was not supported before Tor 0.1.2.2-alpha.) + +3. Other command extensions. + + Tor 0.1.2.4-alpha added a new command value: "CONNECT_DIR" [F2]. + In this case, Tor will open an encrypted direct TCP connection to the + directory port of the Tor server specified by address:port (the port + specified should be the ORPort of the server). It uses a one-hop tunnel + and a "BEGIN_DIR" relay cell to accomplish this secure connection. + + The F2 command value was removed in Tor 0.2.0.10-alpha in favor of a + new use_begindir flag in edge_connection_t. + +4. HTTP-resistance + + Tor checks the first byte of each SOCKS request to see whether it looks + more like an HTTP request (that is, it starts with a "G", "H", or "P"). If + so, Tor returns a small webpage, telling the user that his/her browser is + misconfigured. This is helpful for the many users who mistakenly try to + use Tor as an HTTP proxy instead of a SOCKS proxy. + +References: + [1] http://archive.socks.permeo.com/protocol/socks4.protocol + [2] http://archive.socks.permeo.com/protocol/socks4a.protocol + [3] SOCKS5: RFC1928 + diff --git a/doc/torsocks.1.in b/doc/torsocks.1.in new file mode 100644 index 0000000..b383859 --- /dev/null +++ b/doc/torsocks.1.in @@ -0,0 +1,63 @@ +.TH TORSOCKS 1 "" "TORSOCKS" + +.SH NAME +.BR torsocks +\- Shell wrapper to simplify the use of the torsocks(8) library to +transparently allow an application to use a SOCKS proxy. Basically a renamed, patched tsocks. +.SH SYNOPSIS +.B torsocks +.RB [application\ [application's\ arguments]] +.br +or +.B torsocks +.RB [on|off] +.br +or +.B torsocks +.SH DESCRIPTION +.B torsocks +is a wrapper between the torsocks library and the application what you +would like to run socksified. +.SH SUMMARY + +By default, torsocks will assume that it should connect to the SOCKS proxy +running at 127.0.0.1 on port 9050. This is the default address and port for +Tor's socks server on most installations. + +In order to use a configuration file, you must set the environment variable +TORSOCKS_CONF_FILE with the location of the file. + +If TORSOCKS_CONF_FILE is not set, torsocks will attempt to read the configuration +file at @CONFDIR@/torsocks.conf. If that file cannot be read, torsocks will +use sensible defaults for most Tor installations, i.e. it will assume that +you want to use a SOCKS proxy running at 127.0.0.1 (localhost) on port 9050. + +For further information on configuration, see +.B torsocks.conf(5). + +.SH OPTIONS +.IP \fB[application\ \fB[application's\ arguments]] +run the application as specified with the environment (LD_PRELOAD) set +such that torsocks(8) will transparently proxy SOCKS connections in +that program +.IP \fB[on|off] +this option adds or removes torsocks(8) from the LD_PRELOAD environment +variable. When torsocks(8) is in this variable all executed +applications are automatically socksified. If you want to +use this function, you HAVE to source the shell script from yours, +like this: "source /usr/bin/torsocks" or ". /usr/bin/torsocks" +.br +Example: +.br +". torsocks on" -- add the torsocks lib to LD_PRELOAD +.br +". torsocks off" -- remove the torsocks lib from LD_PRELOAD +.IP \fB[show|sh] +show the current value of the LD_PRELOAD variable +.IP \fB<without\ any\ argument> +create a new shell with LD_PRELOAD including torsocks(8). +.PP +.SH AUTHOR +This script was created by Tamas SZERB <toma@rulez.org> for the debian +package of tsocks. It (along with this manual page) have since been +adapted into the torsocks project and modified. diff --git a/doc/torsocks.8.in b/doc/torsocks.8.in new file mode 100644 index 0000000..0cda513 --- /dev/null +++ b/doc/torsocks.8.in @@ -0,0 +1,189 @@ +.TH TORSOCKS 8 "" "Shaun Clowes" \" -*- + \" nroff -* + +.SH NAME +.BR torsocks +\- Library for intercepting outgoing network connections and +redirecting them through a SOCKS server. + +.SH SYNOPSIS + +Set LD_PRELOAD to load the library then use applications as normal + +The syntax to force preload of the library for different shells is +specified below: + +Bash, Ksh and Bourne shell - + +export LD_PRELOAD=/lib/libtorsocks.so + +C Shell - + +setenv LD_PRELOAD=/lib/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 torsocks(1) script + +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. + +.SH DESCRIPTION + +.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 then +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. + +.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. + +.SH FILES +@CONFDIR@/torsocks.conf - default torsocks configuration file + +.SH SEE ALSO +torsocks.conf(5) +torsocks(1) +usewithtor(1) + +.SH AUTHOR +Shaun Clowes (delius@progsoc.uts.edu.au) + +.SH COPYRIGHT +Copyright 2000 Shaun Clowes + +Renamed for use by torsocks to avoid conflict with tsocks by Robert Hogan. + +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). + +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 diff --git a/doc/torsocks.conf b/doc/torsocks.conf new file mode 100644 index 0000000..8cc1b2c --- /dev/null +++ b/doc/torsocks.conf @@ -0,0 +1,56 @@ +# This is the configuration for libtorsocks (transparent socks) for use +# with tor, which is providing a socks server on port 9050 by default. +# +# Lines beginning with # and blank lines are ignored +# +# The basic idea is to specify: +# - Local subnets - Networks that can be accessed directly without +# assistance from a socks server +# - Paths - Paths are basically lists of networks and a socks server +# which can be used to reach these networks +# - Default server - A socks server which should be used to access +# networks for which no path is available +# Much more documentation than provided in these comments can be found in +# torsocks.conf(5) and usewithtor(1) manpages. + +# We specify local as 127.0.0.0 - 127.191.255.255 because the +# Tor MAPADDRESS virtual IP range is the rest of net 127. +# Torsocks also treats as local all the subnets that Tor does. +local = 127.0.0.0/255.128.0.0 +local = 127.128.0.0/255.192.0.0 +local = 169.254.0.0/255.255.0.0 +local = 172.16.0.0/255.240.0.0 +local = 192.168.0.0/255.255.0.0 + +# Default server +# For connections that aren't to the local subnets +# the server at 127.0.0.1 should be used (again, hostnames could be used +# too, see note above) +server = 127.0.0.1 + +# SOCKS server type defaults to 4 +#server_type = 5 + +# The port defaults to 1080 but I've stated it here for clarity +server_port = 9050 + +# Username and password (if required on a SOCKSv5 server) +#default_user = +#default_pass = + +# Paths +# For this example this machine needs to access 150.0.0.0/255.255.0.0 as +# well as port 80 on the network 150.1.0.0/255.255.0.0 through +# the socks 5 server at 10.1.7.25 (if this machines hostname was +# "socks.hello.com" we could also specify that, unless --disable-hostnames +# was specified to ./configure). + +#path { +# reaches = 150.0.0.0/255.255.0.0 +# reaches = 150.1.0.0:80/255.255.0.0 +# server = 10.1.7.25 +# server_type = 5 +# default_user = delius +# default_pass = hello +#} +# diff --git a/doc/torsocks.conf.5.in b/doc/torsocks.conf.5.in new file mode 100644 index 0000000..7cd22d8 --- /dev/null +++ b/doc/torsocks.conf.5.in @@ -0,0 +1,214 @@ +.TH TORSOCKS.CONF 5 "" "Robert Hogan" \" -*- + \" nroff -* + +.SH NAME +.BR torsocks.conf +\- configuration file for torsocks(8) + +.SH SUMMARY + +By default, torsocks will assume that it should connect to the SOCKS proxy +running at 127.0.0.1 on port 9050. This is the default address and port for +Tor's socks server on most installations. If you are running a normal Tor +installation and have no special requirements, then you should not need to +create, edit or invoke a configuration file when using torsocks. + +Your installation of torsocks includes a default configuration file +that contains values sensible for use with most Tor installations. The +installation location for your default configuration file is: + + @CONFDIR@/torsocks.conf + +In order to use a configuration file, you must set the environment variable +TORSOCKS_CONF_FILE with the location of the file. + +If TORSOCKS_CONF_FILE is not set, torsocks will attempt to read the configuration +file at @CONFDIR@/torsocks.conf. If that file cannot be read, torsocks will +use sensible defaults for most Tor installations, i.e. it will assume that +you want to use a SOCKS proxy running at 127.0.0.1 (localhost) on port 9050. + +An example of typical usage is provided under the 'example' heading at the +end of this manual page. The script 'usewithtor' provided with your torsocks +installation will set this environment variable for you, and load the +configuration file provided with your installation. + +If you want to use a custom file in a different location, you should set the +environment variable yourself and then use the torsocks command, rather than +usewithtor. + +.SH OVERVIEW + +The configuration for torsocks can be anything from two lines to hundreds of +lines based on the needs at any particular site. The basic idea is to define +any networks the machine can access directly (i.e without the use of a +SOCKS server) and define one or many SOCKS servers to be used to access +other networks (including a 'default' server). + +Local networks are declared using the 'local' keyword in the configuration +file. When applications attempt to connect to machines in networks marked +as local torsocks will not attempt to use a SOCKS server to negotiate the +connection. + +Obviously if a connection is not to a locally accessible network it will need +to be proxied over a SOCKS server. However, many installations have several +different SOCKS servers to be used to access different internal (and external) +networks. For this reason the configuration file allows the definition of +`paths' as well as a default SOCKS server. + +Paths are declared as blocks in the configuration file. That is, they begin +with a 'path {' line in the configuration file and end with a '}' line. Inside +this block directives should be used to declare a SOCKS server (as documented +later in this manual page) and 'reaches' directives should be used to declare +networks and even destination ports in those networks that this server should +be used to reach. N.B Each path MUST define a SOCKS server and contain one or +more 'reaches' directives. + +SOCKS server declaration directives that are not contained within a 'path' +block define the default SOCKS server. If torsocks needs to connect to a machine +via a SOCKS server (i.e it isn't a network declared as 'local') and no 'path' +has declared it can reach that network via a 'reaches' directive this server +is used to negotiate the connection. + +.SH CONFIGURATION SYNTAX + +The basic structure of all lines in the configuration file is: + +.RS +<directive> = <parameters> +.RE + +The exception to this is 'path' blocks which look like: + +.RS +path { +.RS +<directive> = <parameters> +.RE +} +.RE + +Empty lines are ignored and all input on a line after a '#' character is +ignored. + +.SS DIRECTIVES +The following directives are used in the torsocks configuration file: + +.TP +.I 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 be specified as +a hostname (e.g "server = socks.nec.com") + +.TP +.I 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). + +.TP +.I server_type +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 inspectorsocks utility to determine the type of server, see +the 'UTILITIES' section later in this manual page. + +.TP +.I 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) +torsocks 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) + +.TP +.I 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) +torsocks 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) + +.TP +.I 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 torsocks would need a SOCKS server to reach SOCKS servers. + +.TP +.I 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 torsocks 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. + +.TP +.I tordns_enable +This enables the use of the 'tordns' feature in torsocks, which overrides the +standard C library name resolution calls to use SOCKS. The default value is +`true'. + +.TP +.I tordns_deadpool_range +Tor hidden sites do not have real IP addresses. This specifies what range of +IP addresses will be handed to the application as "cookies" for .onion names. +Of course, you should pick a block of addresses which you aren't going to ever +need to actually connect to. The default value is '127.0.69.0/255.255.255.0'. + +.TP +.I tordns_cache_size +This specifies the number of IP addresses looked up through SOCKS to cache. +The default value is 256. Each entry consumes 260 bytes of memory, so the +default adds 66,560 bytes of overhead to each 'torified' process. NOTE: if +the number of IP addresses in tordns_deadpool_range is less than the value +specified for tordns_cache_size, then the cache will be shrunk to fit the +deadpool range. This is to prevent duplicate deadpool addresses from ever +appearing in the cache. + +.SH UTILITIES +torsocks comes with two utilities that can be useful in creating and verifying +the torsocks configuration file. + +.SH EXAMPLE + + export TORSOCKS_CONF_FILE=$PWD/torsocks.conf + torsocks ssh account@sshserver.com + +.SH SEE ALSO +torsocks(8) + +.SH AUTHOR +Robert Hogan (robert@roberthogan.net) +Shaun Clowes (delius@progsoc.uts.edu.au) + +.SH COPYRIGHT +Copyright 2009 Robert Hogan +Copyright 2000 Shaun Clowes + +Renamed for use by torsocks to avoid conflict with torsocks by Robert Hogan. + +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). + +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 diff --git a/doc/tsocks.conf.complex.example b/doc/tsocks.conf.complex.example new file mode 100644 index 0000000..bdeea24 --- /dev/null +++ b/doc/tsocks.conf.complex.example @@ -0,0 +1,47 @@ +# This is the configuration for libtsocks (transparent socks) +# Lines beginning with # and blank lines are ignored +# +# The basic idea is to specify: +# - Local subnets - Networks that can be accessed directly without +# assistance from a socks server +# - Paths - Paths are basically lists of networks and a socks server +# which can be used to reach these networks +# - Default server - A socks server which should be used to access +# networks for which no path is available +# Much more documentation than provided in these comments can be found in +# the man pages, tsocks(8) and tsocks.conf(8) + +# Local networks +# For this example this machine can directly access 192.168.0.0/255.255.255.0 +# (192.168.0.*) and 10.0.0.0/255.0.0.0 (10.*) + +local = 192.168.0.0/255.255.255.0 +local = 10.0.0.0/255.0.0.0 + +# Paths +# For this example this machine needs to access 150.0.0.0/255.255.0.0 as +# well as port 80 on the network 150.1.0.0/255.255.0.0 through +# the socks 5 server at 10.1.7.25 (if this machines hostname was +# "socks.hello.com" we could also specify that, unless --disable-hostnames +# was specified to ./configure). + +path { + reaches = 150.0.0.0/255.255.0.0 + reaches = 150.1.0.0:80/255.255.0.0 + server = 10.1.7.25 + server_type = 5 + default_user = delius + default_pass = hello +} + +# Default server +# For connections that aren't to the local subnets or to 150.0.0.0/255.255.0.0 +# the server at 192.168.0.1 should be used (again, hostnames could be used +# too, see note above) + +server = 192.168.0.1 +# Server type defaults to 4 so we need to specify it as 5 for this one +server_type = 5 +# The port defaults to 1080 but I've stated it here for clarity +server_port = 1080 + diff --git a/doc/tsocks.conf.simple.example b/doc/tsocks.conf.simple.example new file mode 100644 index 0000000..bf2a695 --- /dev/null +++ b/doc/tsocks.conf.simple.example @@ -0,0 +1,16 @@ +# This is the configuration for libtsocks (transparent socks) +# Lines beginning with # and blank lines are ignored +# +# This sample configuration shows the simplest (and most common) use of +# tsocks. This is a basic LAN, this machine can access anything on the +# local ethernet (192.168.0.*) but anything else has to use the SOCKS version +# 4 server on the firewall. Further details can be found in the man pages, +# tsocks(8) and tsocks.conf(5) and a more complex example is presented in +# tsocks.conf.complex.example + +# We can access 192.168.0.* directly +local = 192.168.0.0/255.255.255.0 + +# Otherwise we use the server +server = 192.168.0.1 + diff --git a/doc/usewithtor.1.in b/doc/usewithtor.1.in new file mode 100644 index 0000000..c7500cb --- /dev/null +++ b/doc/usewithtor.1.in @@ -0,0 +1,57 @@ +.TH USEWITHTOR 1 "" "USEWITHTOR" + +.SH NAME +.BR usewithtor +\- Shell wrapper to simplify the use of the torsocks(8) library to +transparently allow an application to use a SOCKS proxy. + +.SH SYNOPSIS +.B usewithtor +.RB [application\ [application's\ arguments]] +.br +.SH DESCRIPTION +.B usewithtor +is a wrapper between the torsocks library and the application what you +would like to run socksified. + +.SH OPTIONS +.IP \fB[application\ \fB[application's\ arguments]] +run the application as specified with the environment (LD_PRELOAD) set +such that torsocks(8) will transparently proxy SOCKS connections in +that program. + +.SH USEWITHTOR VERSUS TORSOCKS +.B usewithtor +runs +.B torsocks(1) +with the default configuration file, +located at +.B @CONFDIR@/torsocks.conf. +Running torsocks(1) directly means +that no configuration file will be used (unless you manually set the +TORSOCKS_CONF_FILE or TSOCKS_CONF_FILE environment variable), instead +.B torsocks(8) +will +use defaults that are sensible for most Tor installations. + +.SH USEWITHTOR VERSUS TORIFY +.B usewithtor(1) +and +.B torify(1) +intend to achieve the same ends for most +practical purposes. However +.B torify(1) +will use a default tsocks installation if one exists. +.B Usewithtor(1) +will only ever use a +.B torsocks(8) +installation. + +.SH SEE ALSO +torsocks.conf(5) +torsocks(1) +usewithtor(1) + +.SH AUTHOR +Robert Hogan (robert@roberthogan.net).This script is very similar to torify(1), +provided by the Tor project. \ No newline at end of file diff --git a/src/Makefile.am b/src/Makefile.am index cb69714..d6da8f3 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -2,27 +2,10 @@ libdir = @libdir@/torsocks -# Install configuration file -usewithtorconfdir = $(CONFDIR)/ -usewithtorconf_DATA = torsocks.conf - # Install invocation scripts bin_SCRIPTS = torsocks usewithtor INSTALL_SCRIPT = $(install_sh) -c -m 755 -# Install man pages -torsocksmanpagedir = $(mandir)/man1 -torsocksmanpage_DATA = torsocks.1 - -torsocks8manpagedir = $(mandir)/man8 -torsocks8manpage_DATA = torsocks.8 - -usewithtormanpagedir = $(mandir)/man1 -usewithtormanpage_DATA = usewithtor.1 - -torsocksconfmanpagedir = $(mandir)/man5 -torsocksconfmanpage_DATA = torsocks.conf.5 - # Install main library to $(prefix)/lib/tor (must match torsocks.in) lib_LTLIBRARIES = libtorsocks.la libtorsocks_la_SOURCES = torsocks.c common.c parser.c dead_pool.c darwin_warts.c socks.c diff --git a/src/torsocks.1.in b/src/torsocks.1.in deleted file mode 100644 index b383859..0000000 --- a/src/torsocks.1.in +++ /dev/null @@ -1,63 +0,0 @@ -.TH TORSOCKS 1 "" "TORSOCKS" - -.SH NAME -.BR torsocks -\- Shell wrapper to simplify the use of the torsocks(8) library to -transparently allow an application to use a SOCKS proxy. Basically a renamed, patched tsocks. -.SH SYNOPSIS -.B torsocks -.RB [application\ [application's\ arguments]] -.br -or -.B torsocks -.RB [on|off] -.br -or -.B torsocks -.SH DESCRIPTION -.B torsocks -is a wrapper between the torsocks library and the application what you -would like to run socksified. -.SH SUMMARY - -By default, torsocks will assume that it should connect to the SOCKS proxy -running at 127.0.0.1 on port 9050. This is the default address and port for -Tor's socks server on most installations. - -In order to use a configuration file, you must set the environment variable -TORSOCKS_CONF_FILE with the location of the file. - -If TORSOCKS_CONF_FILE is not set, torsocks will attempt to read the configuration -file at @CONFDIR@/torsocks.conf. If that file cannot be read, torsocks will -use sensible defaults for most Tor installations, i.e. it will assume that -you want to use a SOCKS proxy running at 127.0.0.1 (localhost) on port 9050. - -For further information on configuration, see -.B torsocks.conf(5). - -.SH OPTIONS -.IP \fB[application\ \fB[application's\ arguments]] -run the application as specified with the environment (LD_PRELOAD) set -such that torsocks(8) will transparently proxy SOCKS connections in -that program -.IP \fB[on|off] -this option adds or removes torsocks(8) from the LD_PRELOAD environment -variable. When torsocks(8) is in this variable all executed -applications are automatically socksified. If you want to -use this function, you HAVE to source the shell script from yours, -like this: "source /usr/bin/torsocks" or ". /usr/bin/torsocks" -.br -Example: -.br -". torsocks on" -- add the torsocks lib to LD_PRELOAD -.br -". torsocks off" -- remove the torsocks lib from LD_PRELOAD -.IP \fB[show|sh] -show the current value of the LD_PRELOAD variable -.IP \fB<without\ any\ argument> -create a new shell with LD_PRELOAD including torsocks(8). -.PP -.SH AUTHOR -This script was created by Tamas SZERB <toma@rulez.org> for the debian -package of tsocks. It (along with this manual page) have since been -adapted into the torsocks project and modified. diff --git a/src/torsocks.8.in b/src/torsocks.8.in deleted file mode 100644 index 0cda513..0000000 --- a/src/torsocks.8.in +++ /dev/null @@ -1,189 +0,0 @@ -.TH TORSOCKS 8 "" "Shaun Clowes" \" -*- - \" nroff -* - -.SH NAME -.BR torsocks -\- Library for intercepting outgoing network connections and -redirecting them through a SOCKS server. - -.SH SYNOPSIS - -Set LD_PRELOAD to load the library then use applications as normal - -The syntax to force preload of the library for different shells is -specified below: - -Bash, Ksh and Bourne shell - - -export LD_PRELOAD=/lib/libtorsocks.so - -C Shell - - -setenv LD_PRELOAD=/lib/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 torsocks(1) script - -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. - -.SH DESCRIPTION - -.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 then -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. - -.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. - -.SH FILES -@CONFDIR@/torsocks.conf - default torsocks configuration file - -.SH SEE ALSO -torsocks.conf(5) -torsocks(1) -usewithtor(1) - -.SH AUTHOR -Shaun Clowes (delius@progsoc.uts.edu.au) - -.SH COPYRIGHT -Copyright 2000 Shaun Clowes - -Renamed for use by torsocks to avoid conflict with tsocks by Robert Hogan. - -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). - -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 diff --git a/src/torsocks.conf b/src/torsocks.conf deleted file mode 100644 index 8cc1b2c..0000000 --- a/src/torsocks.conf +++ /dev/null @@ -1,56 +0,0 @@ -# This is the configuration for libtorsocks (transparent socks) for use -# with tor, which is providing a socks server on port 9050 by default. -# -# Lines beginning with # and blank lines are ignored -# -# The basic idea is to specify: -# - Local subnets - Networks that can be accessed directly without -# assistance from a socks server -# - Paths - Paths are basically lists of networks and a socks server -# which can be used to reach these networks -# - Default server - A socks server which should be used to access -# networks for which no path is available -# Much more documentation than provided in these comments can be found in -# torsocks.conf(5) and usewithtor(1) manpages. - -# We specify local as 127.0.0.0 - 127.191.255.255 because the -# Tor MAPADDRESS virtual IP range is the rest of net 127. -# Torsocks also treats as local all the subnets that Tor does. -local = 127.0.0.0/255.128.0.0 -local = 127.128.0.0/255.192.0.0 -local = 169.254.0.0/255.255.0.0 -local = 172.16.0.0/255.240.0.0 -local = 192.168.0.0/255.255.0.0 - -# Default server -# For connections that aren't to the local subnets -# the server at 127.0.0.1 should be used (again, hostnames could be used -# too, see note above) -server = 127.0.0.1 - -# SOCKS server type defaults to 4 -#server_type = 5 - -# The port defaults to 1080 but I've stated it here for clarity -server_port = 9050 - -# Username and password (if required on a SOCKSv5 server) -#default_user = -#default_pass = - -# Paths -# For this example this machine needs to access 150.0.0.0/255.255.0.0 as -# well as port 80 on the network 150.1.0.0/255.255.0.0 through -# the socks 5 server at 10.1.7.25 (if this machines hostname was -# "socks.hello.com" we could also specify that, unless --disable-hostnames -# was specified to ./configure). - -#path { -# reaches = 150.0.0.0/255.255.0.0 -# reaches = 150.1.0.0:80/255.255.0.0 -# server = 10.1.7.25 -# server_type = 5 -# default_user = delius -# default_pass = hello -#} -# diff --git a/src/torsocks.conf.5.in b/src/torsocks.conf.5.in deleted file mode 100644 index 7cd22d8..0000000 --- a/src/torsocks.conf.5.in +++ /dev/null @@ -1,214 +0,0 @@ -.TH TORSOCKS.CONF 5 "" "Robert Hogan" \" -*- - \" nroff -* - -.SH NAME -.BR torsocks.conf -\- configuration file for torsocks(8) - -.SH SUMMARY - -By default, torsocks will assume that it should connect to the SOCKS proxy -running at 127.0.0.1 on port 9050. This is the default address and port for -Tor's socks server on most installations. If you are running a normal Tor -installation and have no special requirements, then you should not need to -create, edit or invoke a configuration file when using torsocks. - -Your installation of torsocks includes a default configuration file -that contains values sensible for use with most Tor installations. The -installation location for your default configuration file is: - - @CONFDIR@/torsocks.conf - -In order to use a configuration file, you must set the environment variable -TORSOCKS_CONF_FILE with the location of the file. - -If TORSOCKS_CONF_FILE is not set, torsocks will attempt to read the configuration -file at @CONFDIR@/torsocks.conf. If that file cannot be read, torsocks will -use sensible defaults for most Tor installations, i.e. it will assume that -you want to use a SOCKS proxy running at 127.0.0.1 (localhost) on port 9050. - -An example of typical usage is provided under the 'example' heading at the -end of this manual page. The script 'usewithtor' provided with your torsocks -installation will set this environment variable for you, and load the -configuration file provided with your installation. - -If you want to use a custom file in a different location, you should set the -environment variable yourself and then use the torsocks command, rather than -usewithtor. - -.SH OVERVIEW - -The configuration for torsocks can be anything from two lines to hundreds of -lines based on the needs at any particular site. The basic idea is to define -any networks the machine can access directly (i.e without the use of a -SOCKS server) and define one or many SOCKS servers to be used to access -other networks (including a 'default' server). - -Local networks are declared using the 'local' keyword in the configuration -file. When applications attempt to connect to machines in networks marked -as local torsocks will not attempt to use a SOCKS server to negotiate the -connection. - -Obviously if a connection is not to a locally accessible network it will need -to be proxied over a SOCKS server. However, many installations have several -different SOCKS servers to be used to access different internal (and external) -networks. For this reason the configuration file allows the definition of -`paths' as well as a default SOCKS server. - -Paths are declared as blocks in the configuration file. That is, they begin -with a 'path {' line in the configuration file and end with a '}' line. Inside -this block directives should be used to declare a SOCKS server (as documented -later in this manual page) and 'reaches' directives should be used to declare -networks and even destination ports in those networks that this server should -be used to reach. N.B Each path MUST define a SOCKS server and contain one or -more 'reaches' directives. - -SOCKS server declaration directives that are not contained within a 'path' -block define the default SOCKS server. If torsocks needs to connect to a machine -via a SOCKS server (i.e it isn't a network declared as 'local') and no 'path' -has declared it can reach that network via a 'reaches' directive this server -is used to negotiate the connection. - -.SH CONFIGURATION SYNTAX - -The basic structure of all lines in the configuration file is: - -.RS -<directive> = <parameters> -.RE - -The exception to this is 'path' blocks which look like: - -.RS -path { -.RS -<directive> = <parameters> -.RE -} -.RE - -Empty lines are ignored and all input on a line after a '#' character is -ignored. - -.SS DIRECTIVES -The following directives are used in the torsocks configuration file: - -.TP -.I 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 be specified as -a hostname (e.g "server = socks.nec.com") - -.TP -.I 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). - -.TP -.I server_type -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 inspectorsocks utility to determine the type of server, see -the 'UTILITIES' section later in this manual page. - -.TP -.I 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) -torsocks 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) - -.TP -.I 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) -torsocks 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) - -.TP -.I 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 torsocks would need a SOCKS server to reach SOCKS servers. - -.TP -.I 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 torsocks 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. - -.TP -.I tordns_enable -This enables the use of the 'tordns' feature in torsocks, which overrides the -standard C library name resolution calls to use SOCKS. The default value is -`true'. - -.TP -.I tordns_deadpool_range -Tor hidden sites do not have real IP addresses. This specifies what range of -IP addresses will be handed to the application as "cookies" for .onion names. -Of course, you should pick a block of addresses which you aren't going to ever -need to actually connect to. The default value is '127.0.69.0/255.255.255.0'. - -.TP -.I tordns_cache_size -This specifies the number of IP addresses looked up through SOCKS to cache. -The default value is 256. Each entry consumes 260 bytes of memory, so the -default adds 66,560 bytes of overhead to each 'torified' process. NOTE: if -the number of IP addresses in tordns_deadpool_range is less than the value -specified for tordns_cache_size, then the cache will be shrunk to fit the -deadpool range. This is to prevent duplicate deadpool addresses from ever -appearing in the cache. - -.SH UTILITIES -torsocks comes with two utilities that can be useful in creating and verifying -the torsocks configuration file. - -.SH EXAMPLE - - export TORSOCKS_CONF_FILE=$PWD/torsocks.conf - torsocks ssh account@sshserver.com - -.SH SEE ALSO -torsocks(8) - -.SH AUTHOR -Robert Hogan (robert@roberthogan.net) -Shaun Clowes (delius@progsoc.uts.edu.au) - -.SH COPYRIGHT -Copyright 2009 Robert Hogan -Copyright 2000 Shaun Clowes - -Renamed for use by torsocks to avoid conflict with torsocks by Robert Hogan. - -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). - -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 diff --git a/src/tsocks.conf.complex.example b/src/tsocks.conf.complex.example deleted file mode 100644 index bdeea24..0000000 --- a/src/tsocks.conf.complex.example +++ /dev/null @@ -1,47 +0,0 @@ -# This is the configuration for libtsocks (transparent socks) -# Lines beginning with # and blank lines are ignored -# -# The basic idea is to specify: -# - Local subnets - Networks that can be accessed directly without -# assistance from a socks server -# - Paths - Paths are basically lists of networks and a socks server -# which can be used to reach these networks -# - Default server - A socks server which should be used to access -# networks for which no path is available -# Much more documentation than provided in these comments can be found in -# the man pages, tsocks(8) and tsocks.conf(8) - -# Local networks -# For this example this machine can directly access 192.168.0.0/255.255.255.0 -# (192.168.0.*) and 10.0.0.0/255.0.0.0 (10.*) - -local = 192.168.0.0/255.255.255.0 -local = 10.0.0.0/255.0.0.0 - -# Paths -# For this example this machine needs to access 150.0.0.0/255.255.0.0 as -# well as port 80 on the network 150.1.0.0/255.255.0.0 through -# the socks 5 server at 10.1.7.25 (if this machines hostname was -# "socks.hello.com" we could also specify that, unless --disable-hostnames -# was specified to ./configure). - -path { - reaches = 150.0.0.0/255.255.0.0 - reaches = 150.1.0.0:80/255.255.0.0 - server = 10.1.7.25 - server_type = 5 - default_user = delius - default_pass = hello -} - -# Default server -# For connections that aren't to the local subnets or to 150.0.0.0/255.255.0.0 -# the server at 192.168.0.1 should be used (again, hostnames could be used -# too, see note above) - -server = 192.168.0.1 -# Server type defaults to 4 so we need to specify it as 5 for this one -server_type = 5 -# The port defaults to 1080 but I've stated it here for clarity -server_port = 1080 - diff --git a/src/tsocks.conf.simple.example b/src/tsocks.conf.simple.example deleted file mode 100644 index bf2a695..0000000 --- a/src/tsocks.conf.simple.example +++ /dev/null @@ -1,16 +0,0 @@ -# This is the configuration for libtsocks (transparent socks) -# Lines beginning with # and blank lines are ignored -# -# This sample configuration shows the simplest (and most common) use of -# tsocks. This is a basic LAN, this machine can access anything on the -# local ethernet (192.168.0.*) but anything else has to use the SOCKS version -# 4 server on the firewall. Further details can be found in the man pages, -# tsocks(8) and tsocks.conf(5) and a more complex example is presented in -# tsocks.conf.complex.example - -# We can access 192.168.0.* directly -local = 192.168.0.0/255.255.255.0 - -# Otherwise we use the server -server = 192.168.0.1 - diff --git a/src/usewithtor.1.in b/src/usewithtor.1.in deleted file mode 100644 index c7500cb..0000000 --- a/src/usewithtor.1.in +++ /dev/null @@ -1,57 +0,0 @@ -.TH USEWITHTOR 1 "" "USEWITHTOR" - -.SH NAME -.BR usewithtor -\- Shell wrapper to simplify the use of the torsocks(8) library to -transparently allow an application to use a SOCKS proxy. - -.SH SYNOPSIS -.B usewithtor -.RB [application\ [application's\ arguments]] -.br -.SH DESCRIPTION -.B usewithtor -is a wrapper between the torsocks library and the application what you -would like to run socksified. - -.SH OPTIONS -.IP \fB[application\ \fB[application's\ arguments]] -run the application as specified with the environment (LD_PRELOAD) set -such that torsocks(8) will transparently proxy SOCKS connections in -that program. - -.SH USEWITHTOR VERSUS TORSOCKS -.B usewithtor -runs -.B torsocks(1) -with the default configuration file, -located at -.B @CONFDIR@/torsocks.conf. -Running torsocks(1) directly means -that no configuration file will be used (unless you manually set the -TORSOCKS_CONF_FILE or TSOCKS_CONF_FILE environment variable), instead -.B torsocks(8) -will -use defaults that are sensible for most Tor installations. - -.SH USEWITHTOR VERSUS TORIFY -.B usewithtor(1) -and -.B torify(1) -intend to achieve the same ends for most -practical purposes. However -.B torify(1) -will use a default tsocks installation if one exists. -.B Usewithtor(1) -will only ever use a -.B torsocks(8) -installation. - -.SH SEE ALSO -torsocks.conf(5) -torsocks(1) -usewithtor(1) - -.SH AUTHOR -Robert Hogan (robert@roberthogan.net).This script is very similar to torify(1), -provided by the Tor project. \ No newline at end of file