DOC: add some documentation for the "init-addr" server keyword

All 4 new values were documented at once.

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 147a9fbe7f23a1f96c822ec19840491951984680..80343a055edb1a0f0ddc5dd8c9e97f3c0c8ff385 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -7358,7 +7358,8 @@ server <name> <address>[:[port]] [param*]
                     - 'abns@'  -> address is in abstract namespace (Linux only)
               You may want to reference some environment variables in the
               address parameter, see section 2.3 about environment
-              variables.
+              variables. The "init-addr" setting can be used to modify the way
+              IP addresses should be resolved upon startup.
 
     <port>    is an optional port specification. If set, all connections will
               be sent to this port. If unset, the same port the client
@@ -10787,6 +10788,35 @@ id <value>
 
   Supported in default-server: No
 
+init-addr {last | libc | none | <ip>},[...]*
+  Indicate in what order the server's address should be resolved upon startup
+  if it uses an FQDN. Attempts are made to resolve the address by applying in
+  turn each of the methods mentionned in the comma-delimited list. The first
+  method which succeeds is used. If the end of the list is reached without
+  finding a working method, an error is thrown. Method "last" suggests to pick
+  the address which appears in the state file (see "server-state-file"). Method
+  "libc" uses the libc's internal resolver (gethostbyname() or getaddrinfo()
+  depending on the operating system and build options). Method "none"
+  specifically indicates that the server should start without any valid IP
+  address in a down state. It can be useful to ignore some DNS issues upon
+  startup, waiting for the situation to get fixed later. Finally, an IP address
+  (IPv4 or IPv6) may be provided. It can be the currently known address of the
+  server (eg: filled by a configuration generator), or the address of a dummy
+  server used to catch old sessions and present them with a decent error
+  message for example. When the "first" load balancing algorithm is used, this
+  IP address could point to a fake server used to trigger the creation of new
+  instances on the fly. This option defaults to "last,libc" indicating that the
+  previous address found in the state file (if any) is used first, otherwise
+  the libc's resolver is used. This ensures continued compatibility with the
+  historic behaviour.
+
+  Example:
+      defaults
+          # never fail on address resolution
+          default-server init-addr last,libc,none
+
+  Supported in default-server: Yes
+
 inter <delay>
 fastinter <delay>
 downinter <delay>