commit 7b11deab9fc9767a414e8dfba9282900ab5773b3 Author: David Goulet dgoulet@ev0ke.net Date: Sun Jun 23 11:37:22 2013 -0400

Rename file so the Makefile does not complain

Signed-off-by: David Goulet dgoulet@ev0ke.net --- doc/torsocks.1 | 63 ++++++++++++++ doc/torsocks.1.in | 63 -------------- doc/torsocks.8 | 189 ++++++++++++++++++++++++++++++++++++++++++ doc/torsocks.8.in | 189 ------------------------------------------ doc/torsocks.conf.5 | 214 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/torsocks.conf.5.in | 214 ------------------------------------------------ doc/usewithtor.1 | 57 +++++++++++++ doc/usewithtor.1.in | 57 ------------- 8 files changed, 523 insertions(+), 523 deletions(-)

diff --git a/doc/torsocks.1 b/doc/torsocks.1 new file mode 100644 index 0000000..555e661 --- /dev/null +++ b/doc/torsocks.1 @@ -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|--shell] +.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[--shell] +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.1.in b/doc/torsocks.1.in deleted file mode 100644 index 555e661..0000000 --- a/doc/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|--shell] -.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[--shell] -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 b/doc/torsocks.8 new file mode 100644 index 0000000..58672e5 --- /dev/null +++ b/doc/torsocks.8 @@ -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 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. + +.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.8.in b/doc/torsocks.8.in deleted file mode 100644 index 58672e5..0000000 --- a/doc/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 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. - -.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.5 b/doc/torsocks.conf.5 new file mode 100644 index 0000000..7cd22d8 --- /dev/null +++ b/doc/torsocks.conf.5 @@ -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/torsocks.conf.5.in b/doc/torsocks.conf.5.in deleted file mode 100644 index 7cd22d8..0000000 --- a/doc/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/doc/usewithtor.1 b/doc/usewithtor.1 new file mode 100644 index 0000000..c7500cb --- /dev/null +++ b/doc/usewithtor.1 @@ -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/doc/usewithtor.1.in b/doc/usewithtor.1.in deleted file mode 100644 index c7500cb..0000000 --- a/doc/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