[tor-commits] [torsocks/osx] Clarify use of the configuration file.
hoganrobert at torproject.org
hoganrobert at torproject.org
Sun Oct 23 18:27:11 UTC 2011
commit 74fe908c9ddbeed0d5b777cdfb0fc47976e22cae
Author: mwenge <robert at roberthogan.net>
Date: Mon Sep 21 20:57:33 2009 +0100
Clarify use of the configuration file.
Amend the default behaviour to work as summarized below and updated the
manual pages to make the default behaviour obvious to users.
"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."
---
configure.in | 2 +-
src/parser.c | 2 +
src/torsocks.1 | 46 ----------
src/torsocks.1.in | 63 ++++++++++++++
src/torsocks.8 | 188 ------------------------------------------
src/torsocks.8.in | 189 ++++++++++++++++++++++++++++++++++++++++++
src/torsocks.conf.5 | 201 ---------------------------------------------
src/torsocks.conf.5.in | 214 ++++++++++++++++++++++++++++++++++++++++++++++++
src/tsocks.c | 3 +-
src/usewithtor.1 | 30 -------
src/usewithtor.1.in | 57 +++++++++++++
src/usewithtor.in | 8 +-
12 files changed, 532 insertions(+), 471 deletions(-)
diff --git a/configure.in b/configure.in
index 05559f2..390d08e 100644
--- a/configure.in
+++ b/configure.in
@@ -548,7 +548,7 @@ AC_SUBST(LIBTOOL_DEPS)
AC_ENABLE_SHARED
AC_ENABLE_STATIC
-AC_CONFIG_FILES([src/usewithtor src/torsocks])
+AC_CONFIG_FILES([src/usewithtor src/torsocks src/torsocks.conf.5 src/torsocks.8 src/usewithtor.1 src/torsocks.1])
AC_OUTPUT(Makefile src/Makefile)
diff --git a/src/parser.c b/src/parser.c
index 331d60c..f0d3387 100644
--- a/src/parser.c
+++ b/src/parser.c
@@ -88,6 +88,8 @@ int read_config (char *filename, struct parsedfile *config) {
/* Insure null termination */
line[sizeof(line) - 1] = (char) 0;
filename = line;
+ show_msg(MSGWARN, "Configuration file not provided by TORSOCKS_CONF_FILE "
+ "environment variable, attempting to use defaults in %s.\n", filename);
}
/* If there is no configuration file use reasonable defaults for Tor */
diff --git a/src/torsocks.1 b/src/torsocks.1
deleted file mode 100644
index 5799db5..0000000
--- a/src/torsocks.1
+++ /dev/null
@@ -1,46 +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 torsocks.
-.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 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 at 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.1.in b/src/torsocks.1.in
new file mode 100644
index 0000000..b383859
--- /dev/null
+++ b/src/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 at 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 b/src/torsocks.8
deleted file mode 100644
index f482370..0000000
--- a/src/torsocks.8
+++ /dev/null
@@ -1,188 +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
-/etc/torsocks.conf - default torsocks configuration file
-
-.SH SEE ALSO
-torsocks.conf(5)
-torsocks(1)
-
-.SH AUTHOR
-Shaun Clowes (delius at 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 at yggdrasil.com (Adam J. Richter) and can be had from ftp.yggdrasil.com
-pub/dist/pkg
diff --git a/src/torsocks.8.in b/src/torsocks.8.in
new file mode 100644
index 0000000..0cda513
--- /dev/null
+++ b/src/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
+ at CONFDIR@/torsocks.conf - default torsocks configuration file
+
+.SH SEE ALSO
+torsocks.conf(5)
+torsocks(1)
+usewithtor(1)
+
+.SH AUTHOR
+Shaun Clowes (delius at 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 at yggdrasil.com (Adam J. Richter) and can be had from ftp.yggdrasil.com
+pub/dist/pkg
diff --git a/src/torsocks.conf.5 b/src/torsocks.conf.5
deleted file mode 100644
index 6b70eb8..0000000
--- a/src/torsocks.conf.5
+++ /dev/null
@@ -1,201 +0,0 @@
-.TH TSOCKS.CONF 5 "" "Shaun Clowes" \" -*-
- \" nroff -*
-
-.SH NAME
-.BR tsocks.conf
-\- configuration file for tsocks(8)
-
-.SH OVERVIEW
-
-The configuration for tsocks 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 tsocks 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 tsocks 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 tsocks 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 inspectsocks 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)
-tsocks 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)
-tsocks 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 tsocks 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 tsocks 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 tsocks, 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
-tsocks comes with two utilities that can be useful in creating and verifying
-the tsocks configuration file.
-
-.TP
-inspectsocks
-inspectsocks can be used to determine the SOCKS version that a server supports.
-Inspectsocks takes as its arguments the ip address/hostname of the SOCKS
-server and optionally the port number for socks (e.g 'inspectsocks
-socks.nec.com 1080'). It then inspects that server to attempt to determine
-the version that server supports.
-
-.TP
-validateconf
-validateconf can be used to verify the configuration file. It checks the format
-of the file and also the contents for errors. Having read the file it dumps
-the configuration to the screen in a formatted, readable manner. This can be
-extremely useful in debugging problems.
-
-validateconf can read a configuration file from a location other than the
-location specified at compile time with the -f <filename> command line
-option.
-
-Normally validateconf simply dumps the configuration read to the screen (in
-a nicely readable format), however it also has a useful 'test' mode. When
-passed a hostname/ip on the command line like -t <hostname/ip>, validateconf
-determines which of the SOCKS servers specified in the configuration file
-would be used by tsocks to access the specified host.
-
-.SH SEE ALSO
-tsocks(8)
-
-.SH AUTHOR
-Shaun Clowes (delius at progsoc.uts.edu.au)
-
-.SH COPYRIGHT
-Copyright 2000 Shaun Clowes
-
-Renamed for use by torsocks to avoid conflict with tsocks by Robert Hogan.
-
-tsocks and its documentation may be freely copied under the terms and
-conditions of version 2 of the GNU General Public License, as published
-by the Free Software Foundation (Cambridge, Massachusetts, United
-States of America).
-
-This documentation is based on the documentation for logwrites, another
-shared library interceptor. One line of code from it was used in
-tsocks and a lot of the documentation :) logwrites is by
-adam at yggdrasil.com (Adam J. Richter) and can be had from ftp.yggdrasil.com
-pub/dist/pkg
diff --git a/src/torsocks.conf.5.in b/src/torsocks.conf.5.in
new file mode 100644
index 0000000..b8ab870
--- /dev/null
+++ b/src/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 at sshserver.com
+
+.SH SEE ALSO
+torsocks(8)
+
+.SH AUTHOR
+Robert Hogan (robert at roberthogan.net)
+Shaun Clowes (delius at 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 at yggdrasil.com (Adam J. Richter) and can be had from ftp.yggdrasil.com
+pub/dist/pkg
diff --git a/src/tsocks.c b/src/tsocks.c
index 60522c2..d76808c 100644
--- a/src/tsocks.c
+++ b/src/tsocks.c
@@ -297,8 +297,9 @@ static int get_config () {
/* Determine the location of the config file */
#ifdef ALLOW_ENV_CONFIG
- if (!suid)
+ if (!suid) {
conffile = getenv("TORSOCKS_CONF_FILE");
+ }
#endif
/* Read in the config file */
diff --git a/src/usewithtor.1 b/src/usewithtor.1
deleted file mode 100644
index 588ef83..0000000
--- a/src/usewithtor.1
+++ /dev/null
@@ -1,30 +0,0 @@
-.TH TORIFY 1 "" "TORIFY"
-
-.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
-or
-.B usewithtor
-.RB [on|off]
-.br
-or
-.B usewithtor
-.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 usewithtor(8) will transparently proxy SOCKS connections in
-that program
-.SH AUTHOR
-This script was created by Tamas SZERB <toma at rulez.org> for the debian
-package of usewithtor. It (along with this manual page) have since been
-adapted into the main torsocks project and modified. Torify is a modified
-copy for the Tor project.
diff --git a/src/usewithtor.1.in b/src/usewithtor.1.in
new file mode 100644
index 0000000..c7500cb
--- /dev/null
+++ b/src/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 at 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/usewithtor.in b/src/usewithtor.in
index b252663..ac25fe9 100644
--- a/src/usewithtor.in
+++ b/src/usewithtor.in
@@ -92,14 +92,14 @@ fi
if [ "$PROG" = "torsocks" ]; then
# Define our torsocks config file
- TSOCKS_CONF_FILE="@CONFDIR@/torsocks.conf"
- export TSOCKS_CONF_FILE
+ TORSOCKS_CONF_FILE="@CONFDIR@/torsocks.conf"
+ export TORSOCKS_CONF_FILE
# Check that we've got a torsocks config file
- if [ -r "$TSOCKS_CONF_FILE" ]; then
+ if [ -r "$TORSOCKS_CONF_FILE" ]; then
exec torsocks "$@"
else
- echo "$0: Missing torsocks configuration file \"$TSOCKS_CONF_FILE\" - torsocks will use defaults sensible for Tor." >&2
+ echo "$0: Missing torsocks configuration file \"$TORSOCKS_CONF_FILE\" - torsocks will use defaults sensible for Tor." >&2
exec torsocks "$@"
fi
fi
More information about the tor-commits
mailing list