clients/upsstats.c, docs/man/upsstats.html.txt, conf/upsstats*.html.sample.in, NEWS.adoc, UPGRADING.adoc: introduced @NUT_UPSSTATS_TEMPLATE@ magic token that HTML templates must start with [networkupstools#3249]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>

Author: jimklimov

NEWS.adoc

@@ -265,6 +265,9 @@ several `FSD` notifications into one executed action. [PR #3097]
      these JSON documents when browsing. [issue #2524, PRs #3171, #3249]
    * Handle `device.model` in addition to `ups.model` in upsstats HTML
      templates. [#3180]
+   * Introduced a `@NUT_UPSSTATS_TEMPLATE@` command which the HTML template
+     files now MUST start with (safety check that we are reading a template).
+     [PR #3249]
 
  - `upssched` tool updates:
    * Previously in PR #2896 (NUT releases v2.8.3 and v2.8.4) the `UPSNAME` and

UPGRADING.adoc

@@ -50,6 +50,12 @@ Changes from 2.8.4 to 2.8.5
   installed (and possibly customized) with the `*.html.sample` files delivered
   by the new build. [PR #3180]
 
+- Introduced a `@NUT_UPSSTATS_TEMPLATE@` command which the NUT CGI template
+  files now MUST start with (safety check that we are reading a template).
+  While the delivered `upsstats*.html.sample` files would include the change,
+  ultimate `upsstats*.html` templates deployed for end-users MUST be updated.
+  [PR #3249]
+
 - Dropped the `compile` script from Git sources. It originates from automake
   and is added to work area (if missing) during `autogen.sh` rituals anyway
   (as `make` says, `'automake --add-missing' can install 'compile'` when you

clients/upsstats.c

@@ -1036,7 +1036,13 @@ static int do_command(char *cmd)
 		return 1;
 	}
 
-	upsdebug_call_finished1(": unknown cmd");
+	if (!strncmp(cmd, "NUT_UPSSTATS_TEMPLATE ", 22) || !strcmp(cmd, "NUT_UPSSTATS_TEMPLATE")) {
+		upsdebugx(2, "%s: saw magic token, ignoring", __func__);
+		upsdebug_call_finished0();
+		return 1;
+	}
+
+	upsdebug_call_finished2(": unknown cmd: '%s'", cmd);
 	return 0;
 }
 
@@ -1100,6 +1106,27 @@ static void display_template(const char *tfn)
 		exit(EXIT_FAILURE);
 	}
 
+	if (!fgets(buf, sizeof(buf), tf)) {
+		fprintf(stderr, "upsstats: template file %s seems to be empty (fgets failed): %s\n", fn, strerror(errno));
+
+		printf("Error: template file %s seems to be empty\n", tfn);
+
+		upsdebug_call_finished1(": empty template");
+		exit(EXIT_FAILURE);
+	}
+
+	/* Test first line for a bit of expected magic */
+	if (!strncmp(buf, "@NUT_UPSSTATS_TEMPLATE", 22)) {
+		parse_line(buf);
+	} else {
+		fprintf(stderr, "upsstats: template file %s does not start with NUT_UPSSTATS_TEMPLATE command\n", fn);
+
+		printf("Error: template file %s does not start with NUT_UPSSTATS_TEMPLATE command\n", tfn);
+
+		upsdebug_call_finished1(": not a valid template");
+		exit(EXIT_FAILURE);
+	}
+
 	while (fgets(buf, sizeof(buf), tf)) {
 		parse_line(buf);
 	}

conf/upsstats-single.html.sample.in

@@ -1,3 +1,4 @@
+@NUT_UPSSTATS_TEMPLATE single@
 <!-- upsstats template file -->
 
 <!--

conf/upsstats.html.sample.in

@@ -1,3 +1,4 @@
+@NUT_UPSSTATS_TEMPLATE default@
 <!-- upsstats template file -->
 
 <!--

docs/man/upsstats.html.txt

@@ -14,6 +14,9 @@ use-cases, are used by linkman:upsstats.cgi[8] to generate NUT CGI status
 pages. Certain commands are recognized, and will be replaced with various
 status elements on the fly.
 
+As a bit of a safety check, the file must start with `@NUT_UPSSTATS_TEMPLATE@`
+command.
+
 For details about configuring some popular web servers to run NUT CGI
 programs, please see the linkman:upsset.conf[5] page.
 
@@ -105,6 +108,15 @@ example (more examples are available in upsstats.html).
 OTHER COMMANDS
 --------------
 
+*@NUT_UPSSTATS_TEMPLATE [args]@*::
+The template file MUST start exactly with `@NUT_UPSSTATS_TEMPLATE@` or
+`@NUT_UPSSTATS_TEMPLATE Some text@` so that linkman:upsstats.cgi[8] is
+not coerced into showing arbitrary files.
++
+Currently the command and its arguments are otherwise ignored; templates
+shipped with NUT use the argument values "default" and "single" effectively
+as a comment for debugging/troubleshooting.
+
 *@UPSSTATSPATH filename@*::
 URI to the linkman:upsstats.cgi[8] program placed into HTML references.
 Default is the program's name, making it a link relative to the currently