M3SOCKS.CONF(5)

NAME
m3socks.conf - configuration file for Modula-3 socks clients

DESCRIPTION
The Modula-3 SOCKS library reads its configuration information from /usr/local/etc/m3socks.conf when bind() or connect() is called. If the file does not exist, then the environment variable SOCKS_CONF is expected to give the name of the configuration file.

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 ‘#’ at any point in the line prior to the :shellcmd, if present. Non-comment lines take the form:

bind defaultwild
domain domain
nameserver nameserver
findserver findserver
sockd [@=server] [*=users] destspec [op dport [dport2]] [:shellcmd]
direct [*=users] destspec [op dport [dport2]] [:shellcmd]
deny [*=users] destspec [op dport [dport2]] [:shellcmd]

Fields are constructed as follows:

domain
    The “local” domain: the default name resolver is assumed to have information for all hosts in domain. The user can override this field using the SOCKS_LOCAL_DOMAIN environment variable. To indicate that the default server is able to resolve all addresses, use the command: ‘domain’..

nameserver
    A comma separated list of name servers that are able to resolve addresses outside of domain. The user can override this field using the SOCKS_NS environment variable.

findserver
    One of Yes or. The default is Yes. If set, the client will attempt to find the “best” SOCKS server, based on the results of looking up destnet.socks-addr (note that this is not an FQDN). 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 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.

    If clear (findserver), then the lookup is not performed.

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 ‘$’ 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 SOCKS_SERVER environment variable.

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 ‘/’. Inside the file, user names may be listed one or several per line, with spaces, tabs, and commas being valid separators. The appearance of ‘#’ marks the remainder of the line as a comment. Each line in a file is limited to 1023 characters. If users is omitted, the line applies to all users.

destspec
    The destination specification, which is either daddr dmask or *.some.domain, which indicates that the line applies to all IP addresses whose reverse lookup, using gethostbyaddr(), produces a name ending in ‘.some.domain’.

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 gethostbyname() is used.

dmask
    Mask for daddr, in dotted form. Bits in dmask which are 0 are ignored in daddr. Specifying 255.255.255.255 requires an exact match, while 0.0.0.0 matches regardless of the value of daddr. This is the same way netmasks are specified, and is the opposite of the interpretation used in older versions of SOCKS.

op dport [dport2]
    A constraint on the destination TCP port. If op is eq, neq, lt, gt, le, or ge, the destination port must have the corresponding relation to dport. If op is btw, the destination port must be between dport and dport2, inclusive.

:shellcmd
    When the line is matched, shellcmd is passed to /bin/sh, with stdin, stdout, and stderr redirected to /dev/null. The following substitutions occur before the string is presented to the shell:

    %A  replaced by the client host's domainname if known, by its IP address otherwise.

    %a  replaced by the client host's IP address.

    %c  replaced by ‘connect’ or ‘bind’.

    %p  replaced by the process id of the client program.

    %S  replaced by the service name (e.g., ftp) if known, by the destination port number otherwise.

    %s  replaced by the destination port number.

    %U  replaced by the user-id at login.

    %u  replaced by the effective user-id.

    %Z  replaced by the destination host's domainname if known, by its IP address otherwise.

    %z  replaced by the destination host's IP address.

    %%  replaced by a single ‘%’.

EXAMPLES
All connections to net 15 are local:
    direct 15.0.0.0 255.0.0.0

Deny all requests destined for hosts on network 23:
    deny 23.0.0.0 255.0.0.0

Use the server my-server for hosts on network 36:
    sockd @=my-server 36.0.0.0 255.0.0.0

A typical complete configuration file:

    # 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

SEE ALSO
m3socks(1)

AUTHORS
SOCKS was developed by David Koblas and Ying-Da Lee. The HP enhancements were done by LaMont Jones.