#
#  resolver.txt - protocol description for communicating with resolvers
#

The SOCKS protocols do not require name resolution to function, as
long as each client can resolve names on its own.  The default
operation for Socks5++ is to run without domain name support.

When socks5pp is run with the -r option, it can perform domain name
look-ups for clients without their own resolution support.  The -r
option must be called with an integer, e.g,. "socks5pp -r 5", which
determines how many resolvers are started.  Each resolver can only
resolve one name at a time, so starting several resolvers can speed
load times for many websites, by allowing many names to be resolved
in parallel.

The default Socks5++ resolver is s5resolver.  This uses the internal
libraries on the system running the server, to convert a name into a
list of addresses, according to the DNS servers configured for the
system.  Alternative resolvers can be configured as well, by using
the -R option to socks5pp.

Each resolver is a child process to the socks5pp process.  The parent
socks5pp process resolves DNS names to IP addresses by sending the
name to the resolver via the resolver's standard input.  The resolver
sends the IP addresses back to the parent via its standard output.

The protocol used to communicate between these processes is simple.
Each request and response is line-oriented.  In the examples below,
a line sent from socks5pp to the resolver process is marked with [in]
while lines sent from the resolver back to socks5pp are marekd with
[out].  The [in] and [out] are only for illustration, and not part
of the protocol.

The resolver sends "OK" to the parent process when it is ready to
resolve a new name.  The parent process sends a name to the resolver,
on a single line.  The resolver sends one or more response lines,
and then sends "OK" on a single line when it is ready for the next
name from the parent.

E.g., from the resolver's perspective:

[out] OK
[ in] www.google.com
[out] www.google.com 172.253.135.105
[out] www.google.com 172.253.135.104
[out] www.google.com 172.253.135.106
[out] www.google.com 172.253.135.99
[out] www.google.com 172.253.135.147
[out] www.google.com 172.253.135.103
[out] www.google.com 2607:f8b0:4023:1015::93
[out] www.google.com 2607:f8b0:4023:1015::6a
[out] www.google.com 2607:f8b0:4023:1015::67
[out] www.google.com 2607:f8b0:4023:1015::63
[out] OK

The [in] line is the request from the parent process, and the [out]
lines are the responses.

If the resolution fails, the resolver will send a single '0' as the
response, e.g.,

[out] OK
[ in] www.bogus-name.com
[out] www.bogus-name.com 0
[out] OK

Both IPv4 and IPv6 addresses are supported, but order is not
guaranteed.

For resolvers that have access to TTL information, there are also
TTL lines, which communicate the TTL for subsequent records, e.g.,
the s5dnstls resolver can report TTL values for each response:

[out] OK
[ in] www.google.com
[out] TTL 299
[out] www.google.com 142.251.153.119
[out] www.google.com 142.251.156.119
[out] www.google.com 142.251.157.119
[out] www.google.com 142.251.154.119
[out] www.google.com 142.251.151.119
[out] www.google.com 142.251.150.119
[out] www.google.com 142.251.152.119
[out] www.google.com 142.251.155.119
[out] www.google.com 2607:f8b0:4023:1803::68
[out] www.google.com 2607:f8b0:4023:1803::6a
[out] www.google.com 2607:f8b0:4023:1803::67
[out] www.google.com 2607:f8b0:4023:1803::63
[out] OK

The TTL value applies to all of the records that follow it, until
the next TTL line is seen.  If a response does not contain a TTL
value, socks5pp will use a reasonable default value, which can be
changed with the -t option.  The minimum allowed TTL value can
also be configured with the -T option.

The resolvers included in this package can be run by hand from
the command line, to allow experimentation and debugging.

There are different resolvers included, which can be selected
with the -R option to socks5pp:

s5resolver - minimal C++ resolver; fast and light; uses libc
    name resolution methods, such as getaddrinfo(3)
s5host - small Python wrapper around the ISC 'host' utility,
    which must be installed to use the resolver; this is a
	heavier resolver, but offers more options
s5dnstls - uses the Python dnspython package to implement
    DNS-over-TLS queries; this is also a somewhat heavier
	resolver process, but it allows encryption of queries

Custom resolvers can also be written from scratch, as long as
they follow the protocol described above.

# EOF: resolver.txt
