Sign inRegisterCheck connection

Installing a Stale-File Checker for Cumulus Uploads

Install a Cumulus stale-file checker: which paths to watch, how to set timeouts from the realtime interval, and how to send email when uploads stop.

Back to Cumulus weather software guides

A Cumulus website is only as current as the last file the logger actually delivered. Installing a stale-file checker is a configuration job: name the remote path, convert the realtime interval into a timeout, and decide who gets mail when the file stops moving. This dotted URL, /projects.checkserver, is that setup note. The quality-control argument—why a green HTTP status is not a current observation—lives on the slash twin, heartbeats for a weather website.

This hostname does not rehost the historical TNET Server Check script. Modern TNET Weather does not monitor Cumulus sites and does not maintain third-party checkers.

Historical context

The Cumulus Wiki TNET scripts catalog lists a “Cumulus Server Check Script” among the named PHP helpers (last checked 13 August 2026). Operators ran it on the public host, where visitors already read realtime.txt or a processed extra file. Independently, the Cumulus Wiki Toolbox can watch whether Cumulus is running and whether realtime processing is updating, and can email on failure. Those are two install locations. This article configures the host-side check. Toolbox remains a complementary Windows process check, not a substitute for pointing PHP at the file the public actually reads.

Current optional realtime behavior is on the realtime.txt wiki page: generation is off by default; when enabled, the file is rebuilt on a realtime interval and may be uploaded on the same interval. A checker that does not know that interval cannot be configured.

Where the checker runs

Put the checker on the same filesystem the template reads. If PHP includes /home/user/public_html/realtime.txt, that is the path to configure. Checking a different copy—a sample in a documentation folder, a Weather Display clientraw.txt, or the Cumulus data folder on the logger PC—installs a detector for the wrong object.

A host-side checker answers: did this file on this host get rewritten recently enough? It does not answer whether the USB cable is seated. Toolbox’s System Checks tab is the logger-side install for that second question. Running both is coherent if you document which alert means which failure. Pinging the homepage is not a stale-file checker; HTTP 200 only proves the web server answered.

Do not point the checker at a homemade realtime log. That file is supposed to age as it grows.

Paths to configure

Write four paths in the station notes before you edit any script settings.

Source file. The remote filename Cumulus actually uploads. Commonly realtime.txt. It may instead be a processed extra file if that is what the public page reads. Use an absolute filesystem path as PHP sees it, not a URL. Fetching https://example/realtime.txt over HTTP adds DNS, TLS, and cache layers that are not the upload.

Optional secondary file. If the checker watches two files, give each its own timeout. A one-minute realtime packet and a ten-minute extra file are not one experiment.

State file. A small local file that records the last alert time and last-seen packet clock. Without it, every page view that finds a stale source will try to send mail. Put it outside the web root if the host allows it.

Log or status output. A public “last checked” line is optional. If you publish one, label it as a derived flag, not as weather.

Confirm the source file is Cumulus. Field 39 in the classic realtime.txt layout is the version string; fields 14–17 are unit tokens.

Timeouts from the interval you actually set

Do not copy a forum number. Read the realtime interval from the software that writes the file: Cumulus 1 Internet Sites/Options, or MX realtime timer, period, transfer, and this-file generation. Size the checker to that interval. Many EasyWeather-class loggers update on the order of 48 seconds.

Then measure, from your own logs, how long after generation the file usually appears on the host. FTP queueing and clock granularity are why a timeout equal to the interval alone false-alarms.

Document three times:

  1. Cumulus realtime interval (seconds), copied from settings.
  2. Observed upload delay, from your logs.
  3. Grace window you are willing to tolerate.

The checker timeout is interval plus delay plus grace. Store the three addends, not only the sum, so a later change to the interval does not leave a mystery number in config.php.

Use both filesystem modification time and the packet’s own date and time fields (classic fields 1–2). Trusting mtime alone fails when an uploader rewrites unchanged bytes. Trusting the packet clock alone fails when the logger PC clock is wrong. Report which clock moved. Align timezones: a host in UTC and a packet in station local time will look stale every evening if you compare them naively.

Do not page a human for a single skipped interval unless your written policy says so. Persistent gaps are the operational event. The first missed interval is often FTP delay.

Email without a mail storm

Toolbox documents mail-server settings, a test button, and a notification address on the logger PC. A host-side PHP checker needs the same three facts plus a debounce rule.

Recipient and From. One operator address is enough. The From address must be a domain the host is allowed to send. Shared-host mail() is frequently silently discarded; authenticated SMTP to the same provider that hosts the mailbox is the usual repair. Test with a forced stale condition, not by waiting for a real outage.

Subject. Include the station name and the filename. “Check failed” on three sites in one inbox is not actionable.

Body. Include source path, server time, file mtime, packet clock, configured timeout, and which comparison failed. Do not paste the whole realtime line into a shared mailbox.

Debounce. Write a state file when you send. Do not send again until the file has been fresh once, or until a documented reminder interval has passed (for example, once per hour while still stale).

Do not send credentials, FTP passwords, or Cumulus.ini fragments in the alert. The checker’s job is freshness, not a configuration dump. If you suppress overnight mail, keep the public last-updated label honest.

Failure modes of the installer

Most “checker is broken” reports are configuration.

  • Wrong path. Relative paths change with the PHP working directory. Use absolute paths.
  • Permission. The PHP user cannot stat the file, so the check errors and you treat the error as stale—or worse, as fresh.
  • Realtime still off. Default is off. A missing file is not a stale file. The install is incomplete until generation and upload are enabled.
  • Timeout copied from another station. A 15-second interval and a 48-second EasyWeather interval cannot share a timeout.
  • Homepage ping. Re-point it at the observation file.
  • Email on include. If the checker runs inside the public template, every visitor triggers it. Run it from cron or from a Toolbox HTTP request.

Recovered PHP that takes the watched path from a query string is a security object, not an installer. Do not run it.

Practical checklist

  1. Enable realtime generation and upload in Cumulus, or name the extra file you actually publish.
  2. Record the realtime interval from settings, then measure upload delay on this host.
  3. Set timeout = interval + delay + grace, and write the three parts down.
  4. Point the checker at the absolute path of that file, not at the HTML skin.
  5. Compare mtime and packet clock to the server clock; log which one failed.
  6. Reject a zero-byte or truncated line as incomplete, not as “old but present.”
  7. Configure mail with a test, a From the host may send, and a state file for debounce.
  8. Keep Toolbox process checks, if you use them, labeled as logger-side.
  9. Show last-updated on the public page when the check fails. Hiding staleness is a failed install.

Modern relevance

MX sites that publish JSON over HTTP still need a path, a timeout derived from the publish interval, and a notification channel. A 200 from /api is the new FTP success; it is not a configured checker until you name the document and its valid time. Raspberry Pi loggers still fail by SD-card wear, power loss, and Wi-Fi drops. Those failures look like meteorology until a checker says the file stopped.

TNET’s public note on data sources, quality controls, and methodology is the modern discussion of source identity and freshness for records used in connection research. It does not publish internal thresholds, and this page does not either.

Related pages: the slash heartbeat article, the reference card for documenting a checker, the projects map, and the Cumulus legacy hub.

Sources