Documentation for a DNS director

[Dridi Boukelmoune]

Hi,

I have a working DNS director prototype on another branch, and I
would like to port that to the current master. Before I do that, I have
to write test cases around dynamic backends support, coming soon
hopefully.

I'd like feedback on what the director looks like to end-users, before
I start porting it.

Current generated man:
--->8-------->8-------->8-------->8-------->8-------->8-------->8-------->8-------->8-------->8---
OBJECT DNS
       Description
              Create a DNS director.

              The director creates backends with DNS lookups and chooses  them
              in  a  round  robin  fashion. An ACL (Access Control List) can be
              used as a white-list to restrict the use of resolved addresses.

       Example

                 acl www_backends {
                      "192.168.15.0"/24;
                      !"192.168.15.1";
                 }

                 sub vcl_init {
                      new www_dir = directors.dns("www.example.com", "80");
                      www_dir.restrict_to(www_backends);
                      www_dir.set_ttl(5m);
                 }

                 sub vcl_recv {
                      set req.backend_hint = www_dir.backend();
                 }

   VOID dns.restrict_to(ACL)
       Prototype
              VOID dns.restrict_to(ACL)

       Description
              Restrict usage of resolved IP addresses to a named ACL.

   VOID dns.set_ttl(DURATION)
       Prototype
              VOID dns.set_ttl(DURATION)

       Description
              Set the DNS lookup TTL (defaults to one hour).

   BACKEND dns.backend()
       Prototype
              BACKEND dns.backend()

       Description
              Pick a backend from the director.
--->8-------->8-------->8-------->8-------->8-------->8-------->8-------->8-------->8-------->8---

Yes, I hope this director will be part of the directors built-in, and
don't want to maintain an out-of-tree module :) However, due to
its nature, it doesn't rely on the vdir code shared by the other
directors.

Comments? Questions?

Related:
https://www.varnish-cache.org/lists/pipermail/varnish-dev/2015-June/008367.html

Related but not supported yet by my prototype:
https://www.varnish-cache.org/lists/pipermail/varnish-dev/2015-June/008359.html

Somewhat related (to the not sharing vdir code), but not for 4.1:
https://www.varnish-cache.org/lists/pipermail/varnish-dev/2015-May/008329.html

Best Regards,
Dridi

PS. Oops!... I did it again, big email :-/