Merge pull request #2137 from pi-hole/update/civetweb

Add 'o' webserver port documentation

src/config/config.c

@@ -1000,7 +1000,7 @@ static void initConfig(struct config *conf)
 	conf->webserver.acl.c = validate_stub; // Type-based checking + civetweb syntax checking
 
 	conf->webserver.port.k = "webserver.port";
-	conf->webserver.port.h = "Ports to be used by the webserver.\n Comma-separated list of ports to listen on. It is possible to specify an IP address to bind to. In this case, an IP address and a colon must be prepended to the port number. For example, to bind to the loopback interface on port 80 (IPv4) and to all interfaces port 8080 (IPv4), use \"127.0.0.1:80,8080\". \"[::]:80\" can be used to listen to IPv6 connections to port 80. IPv6 addresses of network interfaces can be specified as well, e.g. \"[::1]:80\" for the IPv6 loopback interface. [::]:80 will bind to port 80 IPv6 only.\n In order to use port 80 for all interfaces, both IPv4 and IPv6, use either the configuration \"80,[::]:80\" (create one socket for IPv4 and one for IPv6 only), or \"+80\" (create one socket for both, IPv4 and IPv6). The + notation to use IPv4 and IPv6 will only work if no network interface is specified. Depending on your operating system version and IPv6 network environment, some configurations might not work as expected, so you have to test to find the configuration most suitable for your needs. In case \"+80\" does not work for your environment, you need to use \"80,[::]:80\".\n If the port is TLS/SSL, a letter 's' must be appended, for example, \"80,443s\" will open port 80 and port 443, and connections on port 443 will be encrypted. For non-encrypted ports, it is allowed to append letter 'r' (as in redirect). Redirected ports will redirect all their traffic to the first configured SSL port. For example, if webserver.port is \"80r,443s\", then all HTTP traffic coming at port 80 will be redirected to HTTPS port 443. If this value is not set (empty string), the web server will not be started and, hence, the API will not be available.";
+	conf->webserver.port.h = "Ports to be used by the webserver.\n Comma-separated list of ports to listen on. It is possible to specify an IP address to bind to. In this case, an IP address and a colon must be prepended to the port number. For example, to bind to the loopback interface on port 80 (IPv4) and to all interfaces port 8080 (IPv4), use \"127.0.0.1:80,8080\". \"[::]:80\" can be used to listen to IPv6 connections to port 80. IPv6 addresses of network interfaces can be specified as well, e.g. \"[::1]:80\" for the IPv6 loopback interface. [::]:80 will bind to port 80 IPv6 only.\n In order to use port 80 for all interfaces, both IPv4 and IPv6, use either the configuration \"80,[::]:80\" (create one socket for IPv4 and one for IPv6 only), or \"+80\" (create one socket for both, IPv4 and IPv6). The '+' notation to use IPv4 and IPv6 will only work if no network interface is specified. Depending on your operating system version and IPv6 network environment, some configurations might not work as expected, so you have to test to find the configuration most suitable for your needs. In case \"+80\" does not work for your environment, you need to use \"80,[::]:80\".\n If the port is TLS/SSL, a letter 's' (secure) must be appended, for example, \"80,443s\" will open port 80 and port 443, and connections on port 443 will be encrypted. For non-encrypted ports, it is allowed to append letter 'r' (as in redirect). Redirected ports will redirect all their traffic to the first configured SSL port. For example, if webserver.port is \"80r,443s\", then all HTTP traffic coming at port 80 will be redirected to HTTPS port 443.\n When specifying 'o' (optional) behind a port, inability to use this port is not considered an error. For instance, specifying \"80o,8080o\" will allow the webserver to listen on either 80, 8080, both or even none of the two ports. This flag may be combined with 'r' and 's' like \"80or,443os,8080,4443s\" (80 redirecting to SSL if available, 443 encrypted if available, 8080 mandatory and unencrypted, 4443 mandatory and encrypted).\n If this value is not set (empty string), the web server will not be started and, hence, the API will not be available.";
 	conf->webserver.port.a = cJSON_CreateStringReference("comma-separated list of <[ip_address:]port>");
 	conf->webserver.port.f = FLAG_RESTART_FTL;
 	conf->webserver.port.t = CONF_STRING;

src/webserver/webserver.c

@@ -352,7 +352,7 @@ void http_init(void)
 	}
 
 	/* Initialize the library */
-	log_web("Initializing HTTP server on port %s", config.webserver.port.v.s);
+	log_web("Initializing HTTP server on ports \"%s\"", config.webserver.port.v.s);
 	unsigned int features = MG_FEATURES_FILES |
 	                        MG_FEATURES_IPV6 |
 	                        MG_FEATURES_CACHE;

test/pihole.toml

@@ -634,19 +634,26 @@
   # bind to port 80 IPv6 only.
   # In order to use port 80 for all interfaces, both IPv4 and IPv6, use either the
   # configuration "80,[::]:80" (create one socket for IPv4 and one for IPv6 only), or
-  # "+80" (create one socket for both, IPv4 and IPv6). The + notation to use IPv4 and
+  # "+80" (create one socket for both, IPv4 and IPv6). The '+' notation to use IPv4 and
   # IPv6 will only work if no network interface is specified. Depending on your
   # operating system version and IPv6 network environment, some configurations might not
   # work as expected, so you have to test to find the configuration most suitable for
   # your needs. In case "+80" does not work for your environment, you need to use
   # "80,[::]:80".
-  # If the port is TLS/SSL, a letter 's' must be appended, for example, "80,443s" will
-  # open port 80 and port 443, and connections on port 443 will be encrypted. For
-  # non-encrypted ports, it is allowed to append letter 'r' (as in redirect). Redirected
-  # ports will redirect all their traffic to the first configured SSL port. For example,
-  # if webserver.port is "80r,443s", then all HTTP traffic coming at port 80 will be
-  # redirected to HTTPS port 443. If this value is not set (empty string), the web
-  # server will not be started and, hence, the API will not be available.
+  # If the port is TLS/SSL, a letter 's' (secure) must be appended, for example,
+  # "80,443s" will open port 80 and port 443, and connections on port 443 will be
+  # encrypted. For non-encrypted ports, it is allowed to append letter 'r' (as in
+  # redirect). Redirected ports will redirect all their traffic to the first configured
+  # SSL port. For example, if webserver.port is "80r,443s", then all HTTP traffic coming
+  # at port 80 will be redirected to HTTPS port 443.
+  # When specifying 'o' (optional) behind a port, inability to use this port is not
+  # considered an error. For instance, specifying "80o,8080o" will allow the webserver
+  # to listen on either 80, 8080, both or even none of the two ports. This flag may be
+  # combined with 'r' and 's' like "80or,443os,8080,4443s" (80 redirecting to SSL if
+  # available, 443 encrypted if available, 8080 mandatory and unencrypted, 4443
+  # mandatory and encrypted).
+  # If this value is not set (empty string), the web server will not be started and,
+  # hence, the API will not be available.
   #
   # Possible values are:
   #     comma-separated list of <[ip_address:]port>