initial commit

g3proxy/doc/configuration/resolvers/c_ares.rst

@@ -0,0 +1,100 @@
+.. _configuration_resolver_c_ares:
+
+c_ares
+======
+
+This is the resolver based on c-ares library.
+
+server
+------
+
+**required**, **type**: str | seq
+
+Set the nameservers.
+
+For *str* value, it may be one or more :ref:`sockaddr str <conf_value_sockaddr_str>` joined with whitespace characters.
+
+For *seq* value, each of its value should be :ref:`sockaddr str <conf_value_sockaddr_str>`.
+
+The default port *53* will be used, if not port is specified in the value string.
+
+Servers in different address families can be set in together.
+
+each_timeout
+------------
+
+**optional**, **type**: int, **unit**: ms
+
+The number of milliseconds each name server is given to respond to a query on the first try.
+After the first try, the timeout algorithm becomes more complicated, but scales linearly with the value of timeout.
+
+**default**: 5000
+
+each_tries
+----------
+
+**optional**, **type**: int
+
+The number of tries the resolver will try contacting each name server before giving up.
+
+**default**: 2
+
+round_robin
+-----------
+
+**optional**, **type**: bool
+
+If true, perform round-robin selection of the nameservers configured for the channel for each resolution.
+
+**default**: false
+
+socket_send_buffer_size
+-----------------------
+
+**optional**, **type**: u32
+
+Set the send buffer size for the socket.
+
+**default**: not set, which should be the value of /proc/sys/net/core/wmem_default
+
+socket_recv_buffer_size
+-----------------------
+
+**optional**, **type**: u32
+
+Set the recv buffer size for the socket.
+
+**default**: not set, which should be the value of /proc/sys/net/core/rmem_default
+
+bind_ipv4
+---------
+
+**optional**, **type**: :ref:`ipv4 addr str <conf_value_ipv4_addr_str>`
+
+Set the IPv4 bind ip for the resolver while setting up sockets.
+
+bind_ipv6
+---------
+
+**optional**, **type**: :ref:`ipv6 addr str <conf_value_ipv6_addr_str>`
+
+Set the IPv6 bind ip for the resolver while setting up sockets.
+
+negative_ttl
+------------
+
+**optional**, **type**: u32
+
+Time-to-Live (TTL) for negative caching of failed DNS lookups.
+This also sets the lower cache limit on positive lookups.
+
+**default**: 30
+
+positive_ttl
+------------
+
+**optional**, **type**: u32
+
+Upper limit on how long we will cache positive DNS responses. It should long than *negative_ttl*.
+
+**default**: 3600

g3proxy/doc/configuration/resolvers/deny_all.rst

@@ -0,0 +1,8 @@
+.. _configuration_resolver_deny_all:
+
+deny_all
+========
+
+This is the dummy resolver designed to drop all requests.
+
+There are no extra config keys for this kind of resolver.

g3proxy/doc/configuration/resolvers/fail_over.rst

@@ -0,0 +1,44 @@
+.. _configuration_resolver_fail_over:
+
+fail_over
+=========
+
+This is a virtual resolver designed to fail over between (real) resolvers.
+
+Rules for result selection:
+
+1. The **success** result of the primary resolver will always be used before the timeout.
+2. The first **success** result either from the primary or the standby resolver will be used after the timeout.
+3. If no success result, the last error one will be used.
+
+primary
+-------
+
+**required**, **type**: string
+
+Set the primary resolver to use.
+
+standby
+-------
+
+**required**, **type**: string
+
+Set the standby resolver to use.
+
+timeout
+-------
+
+**optional**, **type**:
+
+Set the timeout for primary lookup.
+
+**default**: 100ms
+
+negative_ttl
+------------
+
+**optional**, **type**: u32
+
+Time-to-Live (TTL) for negative caching of failed DNS lookups.
+
+**default**: 30

g3proxy/doc/configuration/resolvers/index.rst

@@ -0,0 +1,53 @@
+.. _configuration_resolver:
+
+********
+Resolver
+********
+
+The type for each resolver config is *map*, with two always required keys:
+
+* *name*, which specify the name of the resolver.
+* *type*, which specify the real type of the resolver, decides how to parse other keys.
+
+There are many types of resolver, each with a section below.
+
+Resolvers
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   deny_all
+   fail_over
+   c_ares
+   trust_dns
+
+Common Keys
+===========
+
+This section describes the common keys, they may be used by many resolvers.
+
+Most of them are the runtime (of the standalone resolver thread) config.
+
+graceful_stop_wait
+------------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the wait duration before really shutdown the resolver thread.
+
+There may be queries running inside the resolver,
+we don't wait all of them to finish but instead wait for a fixed time interval.
+
+**default**: 30s
+
+protective_query_timeout
+------------------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the query timeout value for queries sent to driver.
+
+The value should be larger than the value set in the driver specific timeout config.
+
+**default**: 60s

g3proxy/doc/configuration/resolvers/trust_dns.rst

@@ -0,0 +1,98 @@
+.. _configuration_resolver_trust_dns:
+
+trust_dns
+=========
+
+.. versionadded:: 1.1.4
+
+This is the resolver based on trust-dns library.
+
+server
+------
+
+**required**, **type**: str | seq
+
+Set the nameservers.
+
+For *str* value, it may be one or more :ref:`ip addr str <conf_value_ip_addr_str>` joined with whitespace characters.
+
+For *seq* value, each of its value should be :ref:`ip addr str <conf_value_ip_addr_str>`.
+
+server_port
+-----------
+
+**optional**, **type**: u16
+
+Set the port if the default port is not usable.
+
+**default**: 53 for udp and tcp, 853 for dns-over-tls, 443 for dns-over-https
+
+encryption
+----------
+
+**optional**, **type**: :ref:`dns encryption config <conf_value_dns_encryption_config>`
+
+Set the encryption config.
+
+**default**: not set
+
+each_timeout
+------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Specify the timeout for a request.
+
+**default**: 5s
+
+retry_attempts
+--------------
+
+**optional**, **type**: usize
+
+Number of retries after lookup failure before giving up.
+
+**default**: 2
+
+bind_ip
+-------
+
+**optional**, **type**: :ref:`ip addr str <conf_value_ip_addr_str>`
+
+Set the bind ip for the resolver while setting up sockets.
+
+positive_min_ttl
+----------------
+
+**optional**, **type**: u32
+
+Minimum TTL for positive responses.
+
+**default**: 30
+
+positive_max_ttl
+----------------
+
+**optional**, **type**: u32
+
+Maximum TTL for positive responses.
+
+**default**: 3600
+
+negative_min_ttl
+----------------
+
+**optional**, **type**: u32
+
+Minimum TTL for negative responses.
+
+**default**: 30
+
+negative_max_ttl
+----------------
+
+**optional**, **type**: u32
+
+Maximum TTL for negative responses.
+
+**default**: 3600