Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SOCKSRC(5)			    socksrc			    SOCKSRC(5)

NAME
       socksrc - Socks 5 configuration file

DESCRIPTION
       /usr/local/etc/socksrc is a unified configuration file for both the
       Socks 5 server, sockd, and applications that use	the Socks 5 protocol
       to contact a Socks 5 server, such as sockd.

       This configuration file may be installed	on:

       o   Firewalls that run the sockd(1)[1] server.  sockd will read the
	   server configuration	settings from /usr/local/etc/socksrc.

       o   Servers that	run applications that use the Socks 5 protocol.	The
	   applications	read a list of available Socks 5 servers from
	   /usr/local/etc/socksrc, and determine the address of	the Socks 5
	   server to use for a particular network connection.

       This manual page	describes both the client and the server-related
       settings	in this	configuration file.  /usr/local/etc/socksrc may	be
       either a	single file, or	a directory. If	/usr/local/etc/socksrc is a
       directory, its contents are read	and concatenated together, to form the
       actual configuration file. Files	in this	directory whose	names contain
       periods or tildes, and any file named "CVS", are	ignored. Everything
       else is concatenated together and read as a single configuration	file.

       Blank lines in /usr/local/etc/socksrc are ignored. Comments are
       introduced by the '#' character,	which are also ignored.

   Client Configuration
       proxy netmask hostname[:port][/ipv4][/redirect=domain[:port]] [ userid
       password	]
	   Connections to netmask, which is a network address in CIDR format
	   (n.n.n.n/l),	should be proxied via a	Socks 5	server running on
	   hostname. Multiple "proxy" statements are used to select different
	   proxies based on the	destination network address.

	   hostname can	be optionally followed by a colon and a	port number,
	   to use a Socks 5 server that's running on a port other than the
	   default port	1080. The following options may	follow,	separated by a
	   forward-slash character:

	   /ipv4
	       The Socks server	does not have IPv6 connectivity, and
	       IPv4-mapped addresses must be converted to native IPv4
	       addresses.

	   /redirect=domain[:port]
	       Redirect	the connection.	After contacting the Socks server, do
	       not request a proxy connection to the original destination IP
	       address.	The proxy connection is	established to domain instead.
	       The original destination	port will be used by default, unless
	       domain is followed by ":port".

	   Use a comma-separated list to specify multiple available Socks 5
	   servers. Each listed	server will be tried, in turn, until a
	   succesful connection	is established to a server.

	   userid and password are optional. They are required when the	Socks
	   5 proxy requires authentication, and	they specify the
	   authentication credentials.

	       Note
	       /usr/local/etc/socksrc needs to be readable by any system
	       application that	uses Socks 5 proxies, so this file is usually
	       globally	readable.

       noproxy netmask
	   Do not use a	Socks 5	proxy when connecting to a network identified
	   by netmask.

       allowenv
	   Allow the SOCKS_PROXY environment variable to override proxy
	   statements.	"allowenv" may be specified anywhere in
	   /usr/local/etc/socksrc (if /usr/local/etc/socksrc is	a directory,
	   "allowenv" may appear in any	file in	the directory).	When
	   "allowenv" is specified, if the SOCKS_PROXY environment variable is
	   defined, it disables	all "proxy" statements,	and replaces them with
	   the contents	of the environment variable. If	the SOCKS_PROXY
	   environment is not defined, the "proxy" statements are read as
	   usual.

	   The "noproxy" statements are	always processed. When "allowenv" is
	   specified and SOCKS_PROXY environment variable is defined, all
	   connections to any IP address are proxied through the server
	   defined by SOCKS_PROXY, except for IP addresses listed in the
	   "noproxy".

	   SOCKS_PROXY's contents follow the same format as the	"proxy"
	   statement. In other words, the contents of SOCKS_PROXY are parsed
	   as if all "proxy" statements	in /usr/local/etc/socksrc are replaced
	   with	the single statement "proxy 0.0.0.0/0 $SOCKS_PROXY".

       When multiple proxy and noproxy statements match	a destination address,
       the one with the	longest	CIDR prefix is selected. The physical order of
       proxy and noproxy statements is irrelevant, the longest CIDR prefix
       will be selected	from all the available candidates. It is an error to
       have the	same network prefix listed more	than once.

   Server Configuration
       port address[:port]
	   Accept connection on	"address".  "address" must be an IP address,
	   like	192.168.0.10, and not a	domain.	The Socks 5 server creates a
	   socket for each "port" statement in /usr/local/etc/socksrc. At
	   least one "port" statement is required, the Socks 5 server will not
	   create any default ports.

	   Use the "port" statement to enumerate all internal IP addresses on
	   the firewall. Do not	specify	any external IP	addresses, because
	   that	would be a security hole.  "address" is	optionally followed by
	   a colon and a port number. The server defaults to the "socks" port,
	   port	1080 (the "socks" service must be listed in the	/etc/services
	   file).

       anonproxy netmask1 [netmask2] [bind=address] [block4=filename]
	   Accept proxy	connections from the IP	address	specified by netmask1,
	   which should	be a network address in	CIDR format (n.n.n.n/l),
	   without requiring authentication.

	   By default, the connecting client may open a	proxy connection to
	   any IP address.  netmask2 is	optional, if specified the proxy
	   connections may only	be opened to the specified IP address range.

	   "bind=address" is optional. If specified, netmask2 must also	be
	   provided, and must be a single IP address (usually "0.0.0.0/32"),
	   and not a CIDR netmask. If "bind=address" is	present, a connection
	   attempt from	netmask1 to netmask2 is	redirected to address, which
	   must	also be	an IP address. This is used to properly	implement
	   proxies for incoming	connections. See the example below for more
	   information.

	   "block4=filename" is	optional.  filename must be a binary database
	   file, created by the	mkbl4(8)[2] command, that contains a list of
	   blacklisted IPv4 address ranges. Connections	to the specified IP
	   address ranges are blocked.

	       Note
	       netmask2	must be	present	if either the "bind" or	the "block4"
	       option is present. Use 0.0.0.0/0	to specify the default,	global
	       IP address range. Example:

		   anonproxy 10.0.0.0/8	0.0.0.0/0 block4=/etc/blacklist.dat

       authproxy netmask1 [netmask2] [bind=address] [block4=filename]
	   Like	the "anonproxy"	command, except	that the connecting client
	   must	provide	an acceptable userid and password, before the proxy
	   connection is allowed.

       user username
	   Run the Socks server	as user	"username" (default: nobody). The
	   Socks server	cannot bind to privileged ports	unless it runs as
	   root. If you	choose to do so, "user root" needs to be added to
	   /usr/local/etc/socksrc.

       group groupname
	   Run the Socks server	as group "groupname". If not specified,	the
	   user's group	gets used. The group option must appear	after the user
	   option.

       debug n
	   Enables debugging messages from the Socks server. The debugging
	   messages are	sent to	syslog (as "daemon" facility log messages).
	   Consult the syslog documentation for	information on where the
	   actual log files are.

	   "n" controls	which activites	are logged. It should be set to	the
	   following values:

	   1
	       Log configuration file parsing.

	   2
	       Log connection requests from Socks clients.

	   16
	       Log only	completed, established proxy connections.

       prefork n
	   Create "n" (default:	5) processes that listen for incoming
	   connections from Socks clients.

       The socks server	first creates a	socket for each	IP address specified
       by the "port" entry, and	begins accepting proxy connection requests.
       For each	connection request the server searches the list	of all
       "anonproxy" and "authproxy" entries until it finds a statement that
       matches the source and the destination IP address, taking into account
       whether the Socks client	supplied a valid userid	and password. The
       proxy connection	request	is rejected unless a matching entry is found.

EXAMPLE
	   proxy 0.0.0.0/0 brimstone
	   noproxy 127.0.0.0/8
	   noproxy 192.168.0.0/24

       This example specifies the proxy	server brimstone, except for
       127.0.0.0/8 (the	loopback interface), and 192.168.0.0/24, the internal
       LAN.

	   Note
	   127.0.0.0/8 should always be	specified as "noproxy" (otherwise the
	   results will	be rather interesting).

	   proxy    0.0.0.0/0	    brimstone:1100,hellraiser
	   noproxy  127.0.0.0/8
	   noproxy  10.0.0.0/8
	   proxy    192.168.5.0/24  portal   daphne  sys64738

       This example uses a default proxy server	on brimstone, port 1100. If
       this server cannot be contacted,	hellraiser will	be the backup proxy
       (on the default port 1080). Connections to the 127 and 10 networks are
       not proxied, and	the 192.168.5 network is reachable via the proxy
       server daphne, logging in as userid daphne, password sys64738.

	   port	192.168.0.5
	   port	192.168.1.5:1100
	   anonproxy 192.168.0.0/24
	   authproxy 192.168.1.0/24 192.168.0.0/24
	   authproxy 192.168.1.0/24 0.0.0.0/32 bind=192.168.0.8

       This example configures the Socks 5 server to listen on two IP
       addresses, 192.168.0.5 and on port 1100 of 192.168.1.5. Clients from
       the IP address range 192.168.0.0/24 are allowed to establish a proxy
       connection to any IP address without requiring authentication. Clients
       from the	IP address range 192.168.1.0/24	are allowed to establish a
       proxy connection	only to	192.168.0.0/24,	and they must authenticate.
       Connection requests from	any other IP address is	rejected.

       The second "authproxy" entry needs more explanation. The	Socks 5
       protocol	provides a limited ability for a Socks client to establish an
       incoming	connection. The	Socks 5	client requests	the server to listen
       on a local port,	then any incoming connection is	the forwarded to the
       client.

       The wildcard IP address,	supplied by the	Socks client when binding the
       port for	a listening socket, is represented by the IP address 0.0.0.0,
       which therefore must be matched by some "authproxy" or "anonproxy"
       entry (take care	to specify 0.0.0.0/32 and NOT 0.0.0.0/0). The Socks
       client can also specify an external, or public, IP address instead of
       the 0.0.0.0/32, so in most cases	additional entries will	be needed.

       If the Socks client does	not explicitly specify an external IP address,
       and uses	0.0.0.0, the external IP address can be	supplied
       automatically. This is what "bind" does.	In this	example, the Socks
       proxy server's external IP address is 192.168.0.8. If the Socks client
       tries to	listen on address 0.0.0.0, the "bind" option causes the	Socks
       server to bind on the IP	address	192.168.0.8 instead.

BINDING	TO RESERVED PORTS
       Under the default configuration,	the Socks server cannot	listen to
       reserved	ports (ports 1-1023). Only a root process can do that, and the
       Socks server does not run as root in the	default	configuration. If the
       Socks server is configured to run as root it will be able to bind to a
       reserved	port, provided that the	client is also connecting from a
       reserved	port.

CLIENT TROUBLESHOOTING
       Setting the SOCKS_DEBUG environment variable before running a Socks 5
       client enables diagnostic messages which	will be	sent to	standard
       error. Socks 5 clients use SOCKS_DEBUG instead of the "debug" setting
       from /usr/local/etc/socksrc.  SOCKS_DEBUG should	be set to the
       following values:

       1
	   Configuration settings.

       2
	   Proxy connection establishment.

       4
	   Intercepted select(2) and poll(2) system calls.

       8
	   Miscellaneous proxy logic.

       128
	   Internal errors.

       Multiple	diagnostic messages may	be selected by adding them together.

BUGS
       The filename in "block4=filename" option	may not	have spaces.

SEE ALSO
       socksify(1)[3], sockd(1)[1].

AUTHORS
       Double Precision, Inc.

NOTES
	1. sockd(1)
	   [set	$man.base.url.for.relative.links]/sockd.html

	2.

	   mkbl4(8)
	   [set	$man.base.url.for.relative.links]/mkbl4.html

	3.

	   socksify(1)
	   [set	$man.base.url.for.relative.links]/socksify.html

Courier	Mail Server		  11/16/2017			    SOCKSRC(5)

NAME | DESCRIPTION | EXAMPLE | BINDING TO RESERVED PORTS | CLIENT TROUBLESHOOTING | BUGS | SEE ALSO | AUTHORS | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=socksrc&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help