.\" From: /3a/socks/man/RCS/socks.conf.4,v 2.11 1995/05/05 18:05:26 lamont Exp
.Dd May 5, 1995
.Os FreeBSD
.Dt M3SOCKS.CONF 5
.Sh NAME
.Nm m3socks.conf
.Nd configuration file for Modula-3 socks clients
.Sh DESCRIPTION
The Modula-3 SOCKS library reads its configuration information from 
.Pa /usr/local/etc/m3socks.conf
when
.Fn bind
or
.Fn connect
is called.
If the file does not exist, then the environment variable
.Ev SOCKS_CONF
is expected to give the name of the configuration file.
.Pp
Each non-blank, non-comment line in the file contains a direction on how
to process requests that match certain criteria.
Comments are denoted by a
.Ql #
at any point in the line prior to the
.Ic : Ns Ar shellcmd ,
if present.
Non-comment lines take the form:
.Pp
.Bl -item -compact
.It
.Ic bind default Ns \*(Ba Ns Ic wild
.It
.Ic domain Ar domain
.It
.Ic nameserver Ar nameserver
.It
.Ic findserver Ar findserver
.It
.Ic sockd
.Op Ic @= Ns Ar server
.Op Ic *= Ns Ar users
.Ar destspec
.Op Ar op Ar dport Op Ar dport2
.Op Ic : Ns Ar shellcmd
.It
.Ic direct
.Op Ic *= Ns Ar users
.Ar destspec
.Op Ar op Ar dport Op Ar dport2
.Op Ic : Ns Ar shellcmd
.It
.Ic deny
.Op Ic *= Ns Ar users
.Ar destspec
.Op Ar op Ar dport Op Ar dport2
.Op Ic : Ns Ar shellcmd
.El
.Pp
Fields are constructed as follows:
.Bl -tag -width Fl
.It Ar domain
The
.Dq local
domain:  the default name resolver is assumed to have
information for all hosts in 
.Ar domain .
The user can override this field using the
.Ev SOCKS_LOCAL_DOMAIN
environment variable.
To indicate that the default server is able to resolve all addresses,
use the command:
.Ql domain \&. .
.It Ar nameserver
A comma separated list of name servers that are able to resolve addresses
outside of
.Ar domain .
The user can override this field using the
.Ev SOCKS_NS
environment variable.
.It Ar findserver
One of
.Ic Yes
or
.Ic \&No .
The default is
.Ic Yes .
If set, the client will attempt to find the
.Dq best
SOCKS server, based
on the results of looking up
.Ar destnet Ns Ic .socks-addr
(note that this is not an FQDN).
.Ar destnet
consists of the first one, two, or three octets of the destination network,
depending on whether the destination network is class A, B, or C.  The octets
are used in reverse order, just like
.Ic IN-ADDR.ARPA .
For example, if the destination address is 129.105.69.100, then a search for
TXT records for '105.129.socks-addr' would be made.  If any TXT records are
found, the record is prepended
to the list of servers from the config file.  There is no environment
variable to override this.
.Pp
If clear
.Pq Ic findserver Ic \&No ,
then the lookup is not performed.
.It Ar server
A comma separated list of SOCKS servers that can
be used as proxy for this destination.  No spaces or tabs are allowed
inside the list.  Names beginning with a
.Ql $
are expanded from the users
environment.  Each server in the list is tried until a successful
connection is established.  When a server has multiple addresses, it
is assumed to be a group of hosts: the address list is randomized and
each address is tried before proceeding to the next name in the list.
The user can override this field using the
.Ev SOCKS_SERVER
environment variable.
.It Ar users
Specifies the users on the requesting host (not the destination host
or server host) to whom this line should apply.  This is a comma
separated list of names and/or filenames, with no spaces or tabs.
Filenames must be fully qualified with a leading
.Ql / .
Inside the file, user names may be listed one or several
per line, with spaces, tabs, and commas being valid separators.
The appearance of
.Ql #
marks the remainder of the line as a comment.  Each line in a file
is limited to 1023 characters.  If
.Ar users
is omitted, the line applies to all users.
.It Ar destspec
The destination specification, which is either
.Ar daddr dmask
or
.Ic *. Ns Ar some.domain ,
which indicates that the line applies to all IP addresses
whose reverse lookup, using 
.Fn gethostbyaddr ,
produces a name ending in
.Ql Cm . Ns Ar some.domain .
.It Ar daddr
The destination address to which this line applies.  This is
usually specified in dotted form (e.g., 15.28.96.137).
If a hostname is used, then the first address returned by
.Fn gethostbyname
is used.
.It Ar dmask
Mask for
.Ar daddr ,
in dotted form.  Bits in
.Ar dmask
which are 0 are ignored in
.Ar daddr .
Specifying 255.255.255.255 requires an exact match, while 0.0.0.0 matches
regardless of the value of
.Ar daddr .
This is the same way netmasks are specified, and is the opposite
of the interpretation used in older versions of SOCKS.
.It Ar op dport Op Ar dport2
A constraint on the destination TCP port.
If
.Ar op
is
.Ic eq ,
.Ic neq ,
.Ic \&lt ,
.Ic gt ,
.Ic le ,
or
.Ic ge ,
the destination port must have the corresponding relation to
.Ar dport .
If
.Ar op
is
.Ic btw ,
the destination port must be between
.Ar dport
and 
.Ar dport2 ,
inclusive.
.It Ic : Ns Ar shellcmd
When the line is matched,
.Ar shellcmd
is passed to
.Pa /bin/sh ,
with stdin, stdout, and stderr redirected to
.Pa /dev/null .
The following substitutions occur before the string
is presented to the shell:
.Bl -tag -width \&%Xxx
.It Cm \&%A
replaced by the client host's domainname if known,
by its IP address otherwise.
.It Cm \&%a
replaced by the client host's IP address.
.It Cm \&%c
replaced by
.Ql connect
or
.Ql bind .
.It Cm \&%p
replaced by the process id of the client program.
.It Cm \&%S
replaced by the service name (e.g., ftp) if known,
by the destination port number otherwise.
.It Cm \&%s
replaced by the destination port number.
.It Cm \&%U
replaced by the user-id at login.
.It Cm \&%u
replaced by the effective user-id.
.It Cm \&%Z
replaced by the destination host's domainname if known,
by its IP address otherwise.
.It Cm \&%z
replaced by the destination host's IP address.
.It Cm \&%%
replaced by a single
.Ql \&% .
.El
.El
.Sh EXAMPLES
All connections to net 15 are local:
.Dl Ic direct 15.0.0.0 255.0.0.0
.Pp
Deny all requests destined for hosts on network 23:
.Dl Ic deny 23.0.0.0 255.0.0.0
.Pp
Use the server my-server for hosts on network 36:
.Dl Ic sockd @=my-server 36.0.0.0 255.0.0.0
.Pp
A typical complete configuration file:
.Bd -literal -offset indent
# The default name server is used for addresses inside
# the FreeBSD.org domain.
domain FreeBSD.org
# ns.FreeBSD.org is used as the name server for addresses
# outside FreeBSD.org.
nameserver ns.FreeBSD.org
# Don't find socks servers automatically.
findserver No
# All local connections are direct.
direct *.FreeBSD.org
# All other connections use the SOCKS server
# on socks.FreeBSD.org.
sockd @=socks.FreeBSD.org 0.0.0.0 0.0.0.0
.Ed
.Sh SEE ALSO
.Xr m3socks 1
.Sh AUTHORS
SOCKS was developed by David Koblas and Ying-Da Lee.
The HP enhancements were done by LaMont Jones.