libsocks5.conf(5)

NAME

libsocks5.conf - configuration file for the socks5 client library

SYNOPSIS
The socks5 client library usually reads the configuration file in /etc/libsocks5.conf. When you configure and build socks5 with the

    --with-libconffile=filename

option, you can change the directory. Under FreeBSD's UNIX port, the configuration file resides in /usr/local/etc/libsocks5.conf.

DESCRIPTION
libsocks5.conf contains information the socks5 client library uses to determine if it should connect directly or through a SOCKS server, what kind of SOCKS server to use, and the port on the server through which to connect.

ENTRIES
All lines in the libsocks5.conf file use the syntax:

    proxy cmd dest-host dest-port [userlist [proxylist]]

proxy
    Identifies the type of proxy server. Valid values include:

    socks4
        SOCKS4 server

    socks5
        SOCKSv5 server

    noproxy
        direct connections

cmd Must be a valid commandpattern. When you specify ping or traceroute as the command, the client ignores dest-host and dest-port, and only attempts connection to the first server in proxylist. If the first server is not available the command fails.

dest-host
    Must be a valid hostpattern

dest-port
    Must be a valid portpattern

userlist
    Optional, must be a valid userpattern

proxylist
    Optional, must be a valid proxypattern and include the SOCKS server(s) this proxy entry uses. Omitting proxylist, instructs the client to use environment variable settings. When you omit proxylist, the client uses:

    proxy is socks5
        The value of the environment variable SOCKS5_SERVER. When SOCKS5_SERVER is not set, the client uses the SOCKS_SERVER environment variable setting. When SOCKS_SERVER is not set, the client uses SOCKS_DEFAULT_SERVER, a default value compiled in the software.

    proxy is socks4
        The value of the environment variable SOCKS4_SERVER. When SOCKS4_SERVER is not set, the client uses the SOCKS_SERVER environment variable setting. When SOCKS_SERVER is not set, the client uses SOCKS_DEFAULT_SERVER, a default value compiled in the software.

PATTERNS

commandpattern
Specify commands as a commandpattern, a comma separated list of letters, with no white space. libsocks5 recognizes these commands:

    c   connect

    b   bind

    u   UDP

    p   ping

    t   traceroute

    -   any command

hostpattern
Specify host addresses and netmasks as a hostpattern, using this format:

    hostip/mask
        Matches when the host address bitwise anded with the mask equals the hostip anded with the mask. Use hostip/mask to mask the host portion of the address from the network or subnetwork portion.

    -   all hosts match

    n1. equivalent to n1.0.0.0/255.0.0.0

    n1.n2.
        equivalent to n1.n2.0.0/255.255.0.0

    n1.n2.n3.
        equivalent to n1.n2.n3.0/255.255.255.0

    .domain.name
        hostname must end with the string .domain.name

    a.host.name
        hostname must match exactly with a.host.name

Although libsocks5 also supports older hostpattern syntax, we recommend using the newer method. The newer method is also easier to read. The older hostpattern syntax is:

    hostip/a
        all match, same as "-"

    hostip/n
        network match. Masks the host and subnet portions of the address, leaving the network portion. The IP address class for hostip determines the mask.

    hostip/s
        subnet match. Masks the host portion of the address, leaving the subnetwork and network portion. The IP address class for hostip determines the mask.

    hostip/h
        host match, equivalent to hostip

portpattern
Specify ports in a portpattern as a service name, number, or range. Enclose ranges in brackets to indicate the range is inclusive, or parentheses to indicate the range is non-inclusive. Specify the range as two port names or numbers, separated by a comma, with no white space.

    tftp
        the service port for tftp, usually port 69

    80  port 80

    -   all ports

    [100,1000]
        ports 100 through 1000

    (100,1000)
        ports 101 through 999

    (100,1000]
        ports 101 through 1000

userpattern
Specify multiple users in a userpattern, a comma separated list of individual UNIX usernames with no white space or wildcard patterns. Dash, -, matches all users.

proxypattern
Specify SOCKS servers as a proxypattern, a comma separated list of server entries, with no white space. Specify servers in order of preference. The client attempts to connect to servers in the order in which they are listed in the proxypattern. It only attempts connections to a server when the preceding server is not available. If cmd is the ping or traceroute commands, the client only attempts to connect to the first server in proxypattern.

server entries
A server entry is a hostname or IP address, optionally followed by a colon and the port number. When you omit the port number, the socks5 client library uses the default port.

    host
        hostname, default port

    host:port
        hostname, port

ENVIRONMENT
These environment variables control the Client library.

SOCKS5_DEBUG [val]
    Turns on debugging and optionally sets the debug level to val. If you omit val, libsocks5 sends only warning messages.

    Valid values for val are 1, 2, and 3. If you specify other values, libsocks5 assumes 3. Valid values and their meanings are:

        1 LOG_NOTICE Reports non-error conditions that may require special handling

        2 LOG_INFO Reports informational messages

        3 LOG_DEBUG Reports information useful for debugging

SOCKS5_ENCRYPT
    If possible, the next server should encrypt the link. SOCKS5_ENCRYPT is only useful when the socks5 build includes Kerberos authentication.

SOCKS5_FAKEALLHOSTS
    Specify that the client library should fake all hostname lookups. Faking all hosts causes faster connections when the host lookup is slow. SOCKS5_FAKEALLHOSTS and SOCKS5_LOCALDNSONLY are mutually exclusive. Setting both causes all DNS lookups to fail.

SOCKS5_LIBCONF filename
    filename specifies an alternate file name for the libsocks5.conf file. The socks5 client library usually reads the configuration file in /etc/libsocks5.conf. Use this environment variable to change the directory and file name.

SOCKS5_LOCALDNSONLY
    Specify to never fake hostnames. Preventing faking limits unnecessary connections to the server on systems on which the client can resolve the same names that the server resolves. SOCKS5_FAKEALLHOSTS and SOCKS5_LOCALDNSONLY are mutually exclusive. Setting both causes all DNS lookups to fail.

SOCKS5_LOG_STDERR
    Sends debug output to stderr.

SOCKS5_LOG_SYSLOG
    Sends debug output to syslog. When you omit the debug output destination, socks5 sends the output to the system log. To send debug output to stderr and syslog, set SOCKS5_LOG_SYSLOG and SOCKS5_LOG_STDERR.

SOCKS5_NOINTCHK
    The next server should proxy the data only, and should not integrity check it. SOCKS5_ NOINTCHK is only useful when the socks5 build includes Kerberos authentication.

SOCKS5_NONETMASKCHECK
    Instructs the client to disregard checking the client host's netmask. By default, the client checks the netmask and connects directly to hosts on the same subnet before consulting the configuration file.

SOCKS5_PASSWD [password]
    Identify the password for Username/Password authentication.

SOCKS5_PRESERVE_STDERR
    Prevent the system from closing stderr or dup2ing it. This is most useful for debugging X Windows processes that send stderr output to a window that fills up too quickly, or constantly pops up.

SOCKS5_SERVER [host:port] [host]
    Identify the socks5 server the client uses and sets SOCKSv5 as the default version. See server entries for additional information on specifying host and port, and proxylist for additional information on how socks5 searches for the server.

SOCKS4_SERVER [host] [host:port]
    Identify the socks4 server the client uses and sets socks4 as the default version. See server entries for additional information on specifying host and port, and proxylist for additional information on how socks5 searches for the server.

SOCKS_SERVER [host] [host:port]
    Identify the default socks server, version 4 or 5, to use when SOCKS5_SERVER or SOCKS4_SERVER is not set and the client requires a specific version. SOCKS_SERVER sets socks5 as the default version. See server entries for additional information on specifying the host and port, and proxylist for additional information on how socks5 searches for the server.

SOCKS5_USER [user id]
    Identify the username for Username/Password authentication.

EXAMPLES

    socks4	-	-	-	-
Allows socks5 clients to use a socks4 server, and uses the socks4 server identified in the SOCKS4_SERVER environment variable.

    socks5    -  143.101.64.200  telnet  fred  11.22.33.10
Only allows user fred to telnet to host 143.101.64.200 using the socks5 server running on 11.22.33.10

    noproxy    -   11.22.33.   -   -
Specifies a direct connection to subnetwork 11.22.33

    socks5    -   -   -   -   srvA:1090,srvB
Specifies two socks5 servers, srvA on port 1090 and srvB on the default port.

    socks5     -  131.12.24.16  -  jeff  servA,servB
User jeff can issue any command to destination host 131.12.24.16 to any destination port using servA. If servA is unavailable, the client attempts to use servB, unless the client issued a ping or traceroute command.

SEE ALSO
socks5.conf(5) and socks5_clients(1)

AUTHORS
NWSL SOCKS5 Development Team
Send comments to socks5-comments@socks.nec.com