Spoolfolder documentation might use an update

[systemdlete]

The spoolfolder documentation page fails to be clear about certain things.

The spoolfile must match the pattern cXXXXXX...

Is this really so? I found it hard to hash names given so few characters; a hash is pretty much necessary for my usage case. I've managed to solve it and my hash seems to work, but it would have been nice to have a larger namespace to work with.

The page offers an example of what a proper spoolfolder queue file should look like internally:

The file contains a header block like this:

### Active Check Result File ###
file_time=<unix timestamp>

But in the example at the bottom of the page, this header is omitted. So, is this header really required? And is the comment-looking first line required to be that exact string (###Active Check Result File###)?

Just after this, the doc indicates

Naemon will discard and remove the file if the timestamp is older than max_check_result_file_age.

Trouble is, I can not find much if any documentation on this max_check_result_file_age. It seems to be hardcoded into naemon (strings -a on the binary shows it is indeed in the code). Again, the example at the bottom of the page does not include the header with this information, so is it really necessary?

exited_ok: Should be 1. If 0, Naemon will discard the result and put a error message into the plugin output.

The example at the bottom of the page has this set to 0, which means it will be discarded. For hours and days, I could not understand why my check spool files were not getting processed! Might be better to illustrate it as "1" (the more normal case), or otherwise comment within the lower example that this file will be discarded.

start_time: Unix timestamp (with fractions) when the check started.

finish_time: Unix timestamp (with fractions) when the check finished.

The example at the bottom shows both of these having ".0" as the fractional part of the time--is this fraction actually required? Or does the doc imply they are optional? In my case, fractions are usually available with the checks I am generating. In other cases, I just add that ".0" literally to the end of both time strings. However, I have noticed that this fraction does not seem to matter and, in fact, when I have forgotten to generate these times, the checks still worked! (Maybe I just got lucky, idk.)

All of this might be obvious to the more veterate users of naemon, but it is confusing and frustrating for at least one user. That said, I do have all of this working after a long struggle. The spoolfolder is a powerful and (very much!) necessary part of naemon; without it, long output lines (with option perfdata) will not make it through the naemon.cmd pipe in one piece if there are multiple lines, in my own experience at least.

Given the necessity and usefulness of this facility, I think a doc update is warranted. Keep up the good work, thanks!

[nook24]

I guess some refresh of the documentation would be not too bad, feel free to send over a pull request :)
I have checked the Naemon code to see what's going on under the hood. This are my results:

The spoolfile must match the pattern cXXXXXX...

Is this really so? I found it hard to hash names given so few characters; a hash is pretty much necessary for my usage case. I've managed to solve it and my hash seems to work, but it would have been nice to have a larger namespace to work with.

Yes, Naemon will simply ignore all files where the filename length is != 7 and the first char is not a c.

naemon-core/src/naemon/checks.c

Lines 246 to 247 in 22f0fb6

	x = strlen(dirfile->d_name);
	if (x == 7 && dirfile->d_name[0] == 'c') {

This is probably from back in the (very) old days, when the spool files where used by Nagios for internal communication between the forked processes. The files where created using mkstemp.
https://github.com/NagiosEnterprises/nagioscore/blob/43a53356b7dc84790b83698c178990c2ea35ba81/base/utils.c#L2168-L2170

The Naemon fork uses the query handler for this since day 1 AFAIK.

You do not need to use a hash or something like this. I did it this way:

1. Generate a new random filename matching the pattern cXXXXXX
2. Make sure the file does not exist (if so, generate a new filename)
3. Touch the file
4. Write your content
5. close the file handler
6. touch the cXXXXXX.ok file to tell Naemon the fill is ready to get processed.

The ### Active Check Result File ### comment is not required. Naemon will skip all lines starting with a #

naemon-core/src/naemon/checks.c

Lines 391 to 393 in 22f0fb6

	/* skip comments */
	if (input[0] == '#')
	continue;

My best guess is, that this is for humans debugging the files back in the day when this feature got used internally.

Trouble is, I can not find much if any documentation on this max_check_result_file_age.

That's true, max_check_result_file_age is hard coded to be 3600 seconds

naemon-core/src/naemon/defaults.h

Line 23 in 22f0fb6

#define DEFAULT_MAX_CHECK_RESULT_AGE 3600 /* maximum number of seconds that a check result file is considered to be valid */

I'm not so sure about the file_time part as it looks like there are two checks. The first one checks last modified time of the file.

naemon-core/src/naemon/checks.c

Lines 279 to 283 in 22f0fb6

	/* if the file is too old, we delete it */
	if (stat_buf.st_mtime + max_check_result_file_age < time(NULL)) {
	delete_check_result_file(dirfile->d_name);
	continue;
	}

The second one checks the value of file_time if it exists. So sort of optional?

naemon-core/src/naemon/checks.c

Lines 417 to 425 in 22f0fb6

	/* found the file time */
	if (!strcmp(var, "file_time")) {
	/* file is too old - ignore check results it contains and delete it */
	/* this will only work as intended if file_time comes before check results */
	if (max_check_result_file_age > 0 && (current_time - (time_t)(strtoul(val, NULL, 0)) > max_check_result_file_age)) {
	break;
	}
	}

The comment says it's important that that the file_time is above the check_results. (You can pass more than one check result in a single spool file)

So i would say, yes it's better to add the header to your files.

exited_ok: Should be 1. If 0, Naemon will discard the result and put a error message into the plugin output.

The example at the bottom of the page has this set to 0, which means it will be discarded.

That's true, there is an open pull request that fixes this.
naemon/naemon.github.io#157
I'm currently looking why the CI is failing to get this merged.

From my understanding the fractional part of start_time is required

naemon-core/src/naemon/checks.c

Lines 442 to 448 in 22f0fb6

	else if (!strcmp(var, "start_time")) {
	if ((v1 = strtok(val, ".")) == NULL)
	continue;
	if ((v2 = strtok(NULL, "\n")) == NULL)
	continue;
	cr.start_time.tv_sec = strtoul(v1, NULL, 0);
	cr.start_time.tv_usec = strtoul(v2, NULL, 0);

and Naemon will go with the default of 0 for start_time if it is missing.

naemon-core/src/naemon/checks.c

Lines 519 to 520 in 22f0fb6

	info->start_time.tv_sec = 0;
	info->start_time.tv_usec = 0;

So i guess its better to make sure you always have .0 appended to your timestamps.

I always set start_time to the same value as finish_time. I'm not so sure what finish_time is used for. Maybe to calculate plugin execution time?

// Edit
That's my spoolfile template I used back in the day: #467 (comment)