update documentation for accept() disabling

doc/FAQ.md

@@ -168,3 +168,17 @@ protocols: (
                 ["^(GET|POST|PUT|OPTIONS|DELETE|HEADER) [^ ]* HTTP/[0-9.]*[\r\n]*Host: host_B.acme"] }
 );
 ```
+
+I get an error "Too many open files"
+====================================
+
+`sslh` used up all the file descriptors it can (1024 by default in Linux),
+which means it cannot create new connections. On some
+systems, you can increase the process limit with `ulimit -n
+2048` (for example). Maybe more usefully, you can limit the
+connection usage based on protocols or listening address, as
+described in the [max_connections](max_connections.md)
+guide.
+
+
+

doc/max_connections.md

@@ -9,18 +9,29 @@ complicated from the server side. This attack will cause
 `sslh` to create a large number of file handles, which can
 cause exgagerated resource consumption.
 
-This threat can be mitigated using several limitation
-mechanisms. Keep in mind that limiting the number of
-connections means that in case of an attack, the server
-resources are protected, but this might be at the expense of
-serving legitimate connections. In particular, in some cases
-this might mean SSH is no longer available.
+In particular, when `sslh` runs into its file descriptor
+limit (as defined with `ulimit -n`), bad things happen: It
+becomes impossible to accept() new sockets efficiently
+(refer to libev's documentation, "The special problem of
+ accept()ing when you can't"). Currently, when `sslh-ev` or
+`sslh-select` reaches its limit of file descriptors, it just
+stops accepting new connections altogether for a few
+seconds, hoping for the situation to get better soon. It is
+better to configure `sslh` to limit connections so the
+`ulimit` is never reached.
+
+Keep in mind that limiting the number of connections means
+that in case of an attack, the server resources are
+protected, but this might be at the expense of serving
+legitimate connections. In particular, in some cases this
+might mean SSH is no longer available.
 
 There are several mechanisms to limit the number of
 connections:
 
 - Use `ulimit` (see bash(3) or your shell's man page) to
-limit the number of file descriptors.
+limit the number of file descriptors. (but then accepting
+new connections might fail for a while)
 
 Then, `sslh` provides several mechanisms to limit the number
 of concurrent connections, which in turns limits the number