Notes · XB Field Notes

A maintenance timer should leave its last result visible

Tue, 04 Aug 2026 00:00:00 +0000

Cron-like syntax is not the whole contract for a maintenance task. The command needs a clear service identity, a bounded runtime, and evidence that distinguishes “not scheduled” from “ran and failed”. A systemd timer and oneshot service keep those concerns separate.

A fired timer is only a scheduling event. Judge this run by its service result, exit status and fresh timestamp.

Define the work as a service

Use an explicit user and absolute command path:

# /etc/systemd/system/site-check.service
[Unit]
Description=Read-only public site check

[Service]
Type=oneshot
User=sitecheck
ExecStart=/usr/local/bin/check-public-site
TimeoutStartSec=2min

TimeoutStartSec limits the oneshot activation, which includes its command runtime; oneshot services otherwise have no start timeout by default. Timeout handling can then require a stop timeout and cannot instantly end uninterruptible kernel I/O, so the helper also needs bounded network requests. The helper should return non-zero when its contract fails and must not modify the service it checks.

Schedule the service

# /etc/systemd/system/site-check.timer
[Unit]
Description=Run the public site check every hour

[Timer]
OnCalendar=hourly
Persistent=true
RandomizedDelaySec=5min
Unit=site-check.service

[Install]
WantedBy=timers.target

Persistent=true triggers one catch-up activation when the timer is activated after missing at least one calendar event; it does not replay every missed hour. The catch-up is still subject to the randomized delay. RandomizedDelaySec spreads routine work across a window; it is not appropriate when the task must run at an exact instant.

Validate before enabling

After creating both unit files, validate them and reload the manager before starting the service manually. These are administrative operations on the intended test host, not read-only checks:

systemd-analyze verify /etc/systemd/system/site-check.service \
 /etc/systemd/system/site-check.timer
systemd-analyze calendar hourly
systemctl daemon-reload
systemctl start site-check.service
systemctl status site-check.service
journalctl -u site-check.service -n 50 --no-pager
systemctl show site-check.service -p Result -p ExecMainCode -p ExecMainStatus

Enable the timer only after the service succeeds with the intended user, environment, paths, and network access:

systemctl enable --now site-check.timer
systemctl list-timers site-check.timer

Alert on the service result

The timer firing is not success. Monitor the oneshot service’s exit status or journal result. Keep stdout concise and send detailed artifacts to a bounded path if they are needed for debugging.

A successful oneshot normally returns to inactive (dead); that alone is not a failure, and systemctl status can return nonzero for an inactive service. Correlate Result and exit status with a fresh journal timestamp so an old successful run is not mistaken for this one. Do not add RemainAfterExit=yes merely to keep it green: a recurring timer does not start a fresh instance while its service is already active. Calendar timing uses the host timezone unless specified, and normal timer accuracy adds scheduling slack beyond the random delay.

Sources

systemd.timer(5), calendar timers, persistence, and delay behavior, checked 2026-08-04.
systemd.time(7), calendar expression syntax, checked 2026-08-04.
systemd.service, oneshot service semantics, checked 2026-08-04.
systemd.service upstream manual (v257), Type=exec/oneshot, readiness, activation timeout, and restart semantics, checked 2026-10-15.
systemd.timer upstream manual (v257), persistence coalesces missed runs; active units, randomized delay, and accuracy, checked 2026-10-15.

Restart policies need a rate limit

Mon, 03 Aug 2026 00:00:00 +0000

Automatic restart is useful for a long-running service, but an unbounded loop can turn a clear failure into a noisy one. The unit should describe both the normal process lifecycle and the amount of recovery that is acceptable.

Count starts within the configured window. A restart rate limit stops rapid churn; it neither proves health nor caps lifetime retries.

Track setup failures

For a long-running process, Type=exec makes failures to execute the configured program visible during start-up rather than treating a fork as success. Pair it with an explicit ExecStart and the least-privileged User that can perform the work.

[Unit]
Description=Example foreground site service
StartLimitIntervalSec=60s
StartLimitBurst=5

[Service]
Type=exec
User=site
ExecStart=/srv/site/bin/server
Restart=on-failure
RestartSec=5s

Type=exec confirms execution, not application readiness. Keep the program in the foreground; use Type=notify when the application supports explicit readiness notification. Restart=on-failure is a recovery policy, not a health check. If the process stays alive while serving bad responses, systemd will not know that the site is broken; an external smoke test still has a job.

Bound the loop

Systemd applies start-rate limiting through StartLimitIntervalSec= and StartLimitBurst=. These directives belong in [Unit], while RestartSec belongs in [Service]. The example allows five starts within 60 seconds; rapid failures separated by five-second restart delays can therefore hit the limit. A longer delay can keep a loop below that rate forever: this is not a lifetime retry budget. Choose limits from the expected failure pattern. When the limit is hit, the journal should contain the evidence needed to distinguish “restarted successfully” from “gave up after repeated failure”.

After installing or editing the unit on an authorized test host, validate the file, reload the manager, and inspect its effective configuration before restarting. The commands below change service state and can interrupt traffic:

systemd-analyze verify /etc/systemd/system/example.service
systemctl daemon-reload
systemctl cat example.service
systemctl show example.service -p Restart -p RestartUSec \
 -p StartLimitIntervalUSec -p StartLimitBurst
systemctl restart example.service
systemctl status --no-pager example.service
journalctl -u example.service -n 80 --no-pager

Do not use a restart policy to conceal missing files, invalid permissions, or a bad environment. Fix the first failure, then test the recovery path.

Once start limiting stops automatic restarts, waiting for the interval alone does not schedule another attempt. After fixing the cause, either start it after the interval or deliberately use systemctl reset-failed example.service to clear the counter before starting. Test missing-executable and rapid-crash cases in an isolated service, and retain the first failure log rather than only the final “start limit hit” message.

Sources

systemd.service, service type, restart, and start-rate limiter, checked 2026-08-03.
systemd.unit, common unit sections and drop-in semantics, checked 2026-08-03.
systemd.service upstream manual (v257), Type=exec/oneshot, readiness, activation timeout, and restart semantics, checked 2026-10-15.
systemd.unit upstream manual (v257), start-limit section placement, rate window, and reset-failed behavior, checked 2026-10-15.

A release checklist for a static site

Thu, 30 Jul 2026 00:00:00 +0000

A static site is simple to publish, but simplicity does not remove the need for a release check. The useful checks are small enough to run on every release and specific enough to fail for a real reason.

The checks belong to the generated artifact. Clean output does not establish reproducibility; placeholder searches are review aids, with parser-based link checks as the gate. Serve the exact artifact before publishing, compare public GET bodies afterward in both languages, and keep the commit, generator version, and download checksums.

Build a clean artifact

Use a pinned generator version and build into a disposable output directory:

set -eu
hugo version
hugo --cleanDestinationDir --gc --minify --destination public

--gc collects unused build-cache resources; it does not clean stale published pages. --cleanDestinationDir removes stale destination files, so use it only on the disposable artifact directory, never a directory containing source or unrelated data. Compare the printed version with the project’s pin; printing a version does not enforce it. Record the build inputs and verify the resulting artifact. A clean destination does not establish byte-for-byte reproducibility: timestamps and other nondeterministic inputs need separate control and comparison. Do not edit generated HTML by hand after the build.

Check the artifact, not only the source

Inspect the generated tree and verify that expected entry points exist. Run this assertion block as a standalone shell script; it must stop before printing the inventory if any required file is missing or empty:

set -eu
test -s public/index.html
test -s public/404.html
test -s public/robots.txt
test -s public/sitemap.xml
find public -type f -print | sort

Then search for accidental placeholders, local paths, and development-only hosts:

rg -l 'localhost|127\.0\.0\.1|TODO|example\.com|/Users/' public --glob '*.html'

This is a review aid, not an automatic release gate: examples like this checklist deliberately match, including in translated pages. This HTML-only scan does not cover XML feeds or JSON search output. rg exits 1 when there are no matches and 2 on an error. Review each listed file, distinguish fenced examples from active links or attributes, and use a parser-based link check for the actual gate. A private path in a published link is a release mistake.

Exercise the public routes

An isolated production-like server pointed at this exact artifact gives the strongest pre-release routing check. Hugo’s development server rebuilds content; the following is a separate source preview, not evidence that the already checked public/ bytes were served. Run the first command in one terminal and the requests in another:

hugo server --bind 127.0.0.1 --port 1313 --baseURL http://127.0.0.1:1313/ \
 --disableFastRender --disableLiveReload --renderToMemory
curl -I http://127.0.0.1:1313/
curl -I http://127.0.0.1:1313/notes/
curl -I http://127.0.0.1:1313/resources/
curl -I http://127.0.0.1:1313/missing-page/

HEAD checks do not compare bodies. Repeat with GET against the staged server, then after publishing compare public bodies with the artifact and check both languages. Confirm that the missing route returns a 404 status in the production server. A pretty error page with a 200 status still breaks monitoring and caches.

Record the result

Keep the source commit, generator version, and checksum of each downloadable resource in the release record. This makes it possible to compare a live file with the source that produced it without relying on memory.

The downloadable version of this checklist is in the Resources section.

Sources

Hugo command reference, generator flags for a clean production build, checked 2026-07-30.
curl manual, HTTP verification and header inspection options, checked 2026-07-30.
Static-site release checklist, downloadable companion resource.
Hugo server command reference, development rebuilds, memory rendering, and live-reload controls, checked 2026-10-15.

SSH host keys are part of the deployment record

Tue, 28 Jul 2026 00:00:00 +0000

In public-key authentication, a client proves possession of its private key; it does not tell the client which server it reached. The server’s host key and the local known_hosts database provide that second half of the identity check.

SSH server identity depends on comparing the observed host key with a separately trusted reference. Strict checking rejects unknown or changed keys. Trust on first use and a network key scan do not independently authenticate first contact.

Separate first contact from rotation

With StrictHostKeyChecking=yes, SSH refuses unknown hosts and changed keys. That is the safest default for a fixed production endpoint, provided the expected key is installed through a trusted channel. accept-new is a narrower convenience for a fleet where new hosts are expected: it accepts a never-seen key but still refuses a changed key.

Host production-site
HostName www.example.test
User deploy
IdentityFile ~/.ssh/site_ed25519
StrictHostKeyChecking yes
UserKnownHostsFile ~/.ssh/known_hosts

Do not “fix” a warning by adding StrictHostKeyChecking=no to a deployment script. It permits connections despite changed host keys, subject to client restrictions; warnings may still be printed, but the intended fail-closed identity check has been weakened. If a host is rebuilt, record the replacement fingerprint and review why the old key is no longer valid.

Make the fingerprint reviewable

Obtain the fingerprint from the host owner or console before the first connection, then compare it with what the client sees. A key change should have a ticket, maintenance note, or other explanation that another operator can inspect.

The same rule applies to automation: the known-hosts file is configuration with security consequences, not disposable cache data. Back it up with the deployment record, but do not publish private keys or copied credentials with the site artifact.

accept-new is trust on first use, not independent proof that the first server was genuine. ssh-keyscan can collect a candidate public key, but fetching it over the same untrusted network does not authenticate it. Compare its fingerprint with the separately trusted value before installing it.

Inspect the effective configuration without connecting, using a standalone copy of the example saved as deploy.conf:

ssh -G -F ./deploy.conf production-site | \
 grep -E '^(hostname|user|stricthostkeychecking|userknownhostsfile) '

Expect the configured host, user, known-hosts path, and strict checking (true or yes, depending on client output). This parses configuration only; it does not test an actual handshake. For a nonstandard port, known-hosts entries normally use [hostname]:port. Keep public-key fingerprints with the private operational release record, not the public website; hostnames can reveal internal topology even though host public keys are not secrets.

Sources

OpenBSD ssh_config, StrictHostKeyChecking and UserKnownHostsFile, checked 2026-07-28.
OpenSSH ssh-keygen manual, fingerprint inspection, checked 2026-07-28.
OpenSSH ssh-keyscan, unverified collected keys do not prevent man-in-the-middle attacks, checked 2026-10-15.
OpenSSH ssh, -G prints evaluated client configuration without opening a session, checked 2026-10-15.

The advantage of small systems

Mon, 27 Jul 2026 00:00:00 +0000

Small does not mean unfinished. It means each component has a clear job, dependencies are deliberate, and the path from request to result remains visible.

Name each request boundary, its evidence and its owner. Fewer components reduce the paths to understand; backups and recovery practice still carry the recovery promise.

Visibility is a feature

When operators can name every boundary, they can also identify which evidence is missing. Logs become more useful, alerts become more specific, and routine maintenance becomes less risky.

For a static website the important boundaries are usually easy to list:

DNS points the hostname to the intended edge.
TLS terminates at the intended proxy.
The proxy serves one known output directory.
The output contains only the files the site needs.
A 404 response is handled by the site, not by an accidental upstream.

Writing this list down is more valuable than adding a dashboard that does not answer any of those questions.

Complexity should earn its place

A new layer is worthwhile when it removes more uncertainty than it creates. A build step that fingerprints assets can be useful when caching is important. A database is useful when content needs transactions. Neither is automatically an improvement for a small, mostly static site.

The same rule applies to client-side JavaScript. If a page genuinely requires client-side scripting, choose the smallest implementation that meets the requirement and review its content security policy deliberately. For this site, that would first require revisiting the accepted zero-script architecture and its verification contract; it is not an exception to the current policy. If the page is a document, plain HTML is often easier to inspect and more resilient.

Make ownership explicit

Every file should have a reason to exist and a clear way to update it. A vendored theme should record its upstream version and license. A generated directory should be marked as generated. A resource download should say what it contains, when it was updated, and how its checksum was produced.

These small statements prevent future operators from treating an accidental artifact as a supported interface.

Leave room for the next change

The best small system is not the one with the fewest lines. It is the one where the next change has a visible place to go. A notes site can start with Markdown, a static generator, and a web server; if it later needs search or comments, the new requirement can be evaluated on its own rather than assumed from the beginning.

Small is not automatically fault-tolerant. A single edge, disk, or operator can still be a single point of failure. Choose acceptable recovery time and data loss, keep an independent backup, and rehearse recovery. The benefit of fewer components is a smaller set of failure paths to understand, not immunity to outages.

Sources

Hugo directory structure, directory conventions for content and assets, checked 2026-07-27.
Caddy file_server directive, static file serving defaults referenced by the design, checked 2026-07-27.

Security headers should describe the actual page

Thu, 23 Jul 2026 00:00:00 +0000

Security headers are not a substitute for secure code, but they make the browser enforce useful boundaries. The policy should describe the page that is actually served, not a generic template copied from another project.

Treat headers as a deployment contract: match actual resources, distinguish enforced and report-only policy, and verify exact host scope and browser behavior.

Start from the resource graph

If a site serves HTML, a local stylesheet, a favicon, and no executable JavaScript, a narrow policy can be understandable:

Content-Security-Policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:

The script-src 'none' choice is only correct while the site does not require executable scripts. Adding search, comments, or an analytics tag changes the resource graph and should trigger a deliberate policy review.

Add transport and framing protections

For an HTTPS-only site, the following headers are common starting points:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=()

Only enable HSTS with includeSubDomains when every subdomain is prepared to serve HTTPS. A header is a contract with future deployments, not merely a score in a scanner.

Check behavior, not just presence

Request a normal page, a missing page, and a static asset. Error responses should carry the same important security headers as successful responses. Also confirm that compression and caching do not change the content type or expose an internal path.

The Caddy example in this site is a starting point, not a universal policy. Adapt the host names, certificate handling, and application routes to your own deployment.

Deliver the CSP as a response header. frame-ancestors is ignored in a meta policy and does not inherit default-src; form-action also needs its own directive. style-src 'self' does not allow inline styles by itself, so test the generated theme, including dark mode. Keep data: in img-src only when the page actually needs data images.

Content-Security-Policy-Report-Only can reveal violations during a rollout, but does not enforce the policy; a reporting endpoint needs separate configuration. Verify enforcement in a real browser as well as checking headers. HSTS is learned from valid HTTPS responses; with includeSubDomains it also applies to descendants of the host that sets it: a policy on www.example.test does not cover the parent example.test or sibling api.example.test. Gradually increase the lifetime after checking that exact scope.

Sources

MDN: Content Security Policy guide, CSP directive names and syntax, checked 2026-07-23.
MDN: Strict-Transport-Security, HSTS directives and deployment cautions, checked 2026-07-23.
Caddy header directive, response header manipulation directives, checked 2026-07-23.
W3C Content Security Policy Level 3, response-header delivery, directive fallbacks, framing, and report-only policies; current working draft, checked 2026-10-15.
RFC 6797 — HTTP Strict Transport Security, valid HTTPS delivery and host/descendant matching in sections 8.1–8.3, checked 2026-10-15.

robots.txt and sitemaps answer different questions

Tue, 21 Jul 2026 00:00:00 +0000

Two small files are often treated as if they were a security boundary. They are not. A robots.txt file describes crawler preferences, while a sitemap gives search systems a list of URLs that belong to the site.

Discovery aids do not grant or deny access. Follow every listed sitemap, validate more than XML syntax, and handle robots error responses according to their actual class.

What robots.txt can and cannot do

The rules are published at the origin’s /robots.txt path and are read by cooperating crawlers. They do not protect a private directory, remove a URL from the network, or replace authentication. A route that must not be public needs server authorization or a network boundary.

Keep the file boring and test its actual location:

User-agent: *
Disallow:
Sitemap: https://www.example.test/sitemap.xml

The file should be UTF-8. If a deployment redirects it, verify the crawler behavior you intend rather than assuming every client follows the same chain.

What a sitemap adds

A sitemap is an inventory, not a permission list. Use absolute URLs from one host, encode XML values correctly, and include only canonical pages that you are prepared to publish. Do not list a URL merely because it exists in a build directory.

Each sitemap may contain at most 50,000 URLs and 50 MB (52,428,800 bytes) uncompressed; gzip does not raise that limit. An index is optional for a small site, but multilingual generators may legitimately produce one pointing to separate language sitemaps. Inspect the root element and follow each listed sitemap rather than assuming /sitemap.xml is a URL set. Validate it as XML and request it through the same HTTPS edge as a normal page.

curl -fsS https://www.example.test/robots.txt
curl -fsS -o sitemap.xml https://www.example.test/sitemap.xml && \
 xmllint --noout sitemap.xml

Separate download and parsing so a failed fetch cannot be hidden by a successful parser. Well-formed XML is only a syntax check: also validate the namespace, URL count, canonical hosts, and whether listed pages exist. If xmllint is not installed, parse the XML in the same CI environment that publishes it. The important part is that the check runs before the file is replaced at the edge.

A robots Disallow is not a reliable de-indexing instruction. Also test error responses: RFC 9309 permits crawling when robots is unavailable with a 4xx response, while a network/server error initially requires complete disallow. Accidentally serving the HTML fallback with status 200 can therefore change crawler behavior even though the URL appears reachable.

Sources

RFC 9309 — Robots Exclusion Protocol, robots rules, file location, and user-agent matching, checked 2026-07-21.
Sitemaps Protocol, sitemap XML structure and discovery, checked 2026-07-21.

Reliable defaults beat clever recovery

Mon, 20 Jul 2026 00:00:00 +0000

Small services often accumulate recovery logic before their normal path is fully understood. Every retry, alternate endpoint, and compatibility branch adds another state that must be observed and tested.

Keep the common path visible. Qualify and bound retries, then recover to a retained known-good state rather than a partial copy.

Make the common path boring

A useful default is explicit, easy to inspect, and safe to repeat. For a static site, that can be as simple as:

Build from a pinned toolchain.
Check the generated HTML, assets, and complete staged directory.
Publish that directory, then verify public responses against it.
Keep the previous directory available for rollback.

The sequence is less impressive than a multi-stage deployment system, but its state is visible. When something fails, the operator can answer whether the problem is in the source, the build, the copy, or the web server.

Retry only a bounded operation

Retries are useful when the failure may be transient and repeating the operation preserves its intended effect. Idempotence does not mean every response or incidental log entry is identical; after a lost response, the first attempt may already have succeeded. A download from an origin may be safe to retry; a database migration may not be. Treating every error as retryable hides the boundary that needs attention.

When a retry is appropriate, record the attempt count and the final reason. A log entry such as “publish failed: checksum mismatch” is more actionable than a sequence of silent retries followed by a generic timeout.

Prefer one authoritative state

Configuration, runtime state, and documentation should agree about which directory is live and which command produces it. If a release can be copied to three different paths depending on who runs it, recovery becomes guesswork.

For a static deployment, a short release record is enough:

release: 2026-07-20
source: git commit <commit-id>
builder: Hugo 0.165.0
output: public/
verification: links + headers + checksums

The placeholder commit ID is deliberately resolved at release time instead of being invented in documentation.

Recovery should restore a known state

Recovery is easiest when it returns the service to the last known-good directory, not when it chooses among several partially built alternatives. Keep the previous output until the new output has passed its checks, then remove old copies according to a retention policy.

The goal is not to eliminate failure. It is to make the failure small enough to explain and the recovery small enough to trust.

Bound retries by both attempts and elapsed time. Use backoff with jitter when many clients could retry together, and avoid stacking retries at every layer. Permission errors and deterministic bad input need correction, not a longer retry loop.

Sources

RFC 9110 — HTTP Semantics, section 9.2.2 on idempotent methods and retries, checked 2026-07-20.
Static-site release checklist, local companion resource.
AWS Builders’ Library: Timeouts, retries, and backoff with jitter, retry amplification, bounded retry budgets, backoff, and jitter, checked 2026-10-15.

A release manifest should name every published byte

Thu, 16 Jul 2026 00:00:00 +0000

A static artifact is a directory, not one executable. Recording only the source commit or homepage checksum leaves gaps: a missing image, stale alias, or changed download can survive unnoticed. Enumerate every regular file in a frozen artifact before transport.

Freeze writers, reject symlinks and special files, and keep both manifests outside the artifact trees. A listed-file check detects missing or changed bytes; recomputing and comparing the complete lists also detects extras. Hashing the trusted source manifest supplies a compact identifier, with separate controls for authenticity and metadata.

Generate a stable list

Run this in Bash with GNU findutils and coreutils, from the directory containing public/. Keep the manifest outside the measured tree. The release must contain only directories and regular files: inspect and reject symlinks or special files first, since they are outside this manifest’s contract.

set -euo pipefail
manifest="$PWD/release.sha256"
(
 cd public
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$manifest"
test -s "$manifest"

Sort filenames before hashing. NUL-delimited paths preserve spaces, tabs, and embedded newlines between tools; GNU sha256sum escapes special names in its ordinary checkable output. Do not parse that output with awk '{print $2}': whitespace is legal in filenames. The separate assignment preserves a failed find exit status; testing only its output could mistake a failed scan for an empty result. Treat any failed scan or pipeline as an incomplete manifest and do not publish it. Stop writers while measuring; these commands do not create a filesystem snapshot.

Verify after transport

In one disposable Bash session on the destination, run the remaining fragments in order so the paths and set options stay in scope. Set the manifest and artifact paths to their actual locations:

set -euo pipefail
manifest=/path/to/release.sha256
artifact=/srv/www/site.new
(
 cd "$artifact"
 sha256sum -c "$manifest"
)

Checking listed files catches missing or changed bytes, but not extra files. Recompute the destination manifest with the same procedure and compare the complete records:

observed=$(mktemp "${manifest}.observed.XXXXXX")
trap 'rm -f "$observed"' EXIT
(
 cd "$artifact"
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$observed"
diff -u "$manifest" "$observed"

No diff and exit status zero means the regular-file paths and hashes agree. An extra stale file now fails too. The temporary output remains outside the artifact so the check never includes itself. Empty directories, permissions, ownership, and timestamps are not measured; validate those separately if deployment depends on them.

Add an aggregate digest for release records

Hash the manifest itself for a compact release identifier:

sha256sum "$manifest"

Its meaning depends on fixed rules: relative paths, sorting locale, algorithm, tool format, and included metadata. Keep the trusted manifest with the source commit and builder version.

Do not confuse integrity with authenticity

Matching SHA-256 digests are strong practical evidence of matching bytes, not proof of authorship. An attacker able to replace both artifact and manifest can make the check pass. Signing and trusted distribution are separate controls; verify only a manifest obtained through the intended trusted channel.

Sources

GNU Coreutils: sha2 utilities, checksum generation and verification; reviewed through the linked upstream manual source, checked 2026-10-15.
GNU Coreutils manual source, untagged checksum escaping, --check, and NUL-delimited sorting, checked 2026-10-15.
sha256sum(1), command behavior and output format, checked 2026-07-16.
GNU Bash: Simple Command Expansion, assignment-only commands retain command-substitution exit status, checked 2026-10-18.

Redirects and error codes should preserve the story

Tue, 14 Jul 2026 00:00:00 +0000

An HTTP status is part of the interface. A browser may render a friendly page, but a monitor, crawler, cache, and API client also need the status code and headers to tell the same story.

Choose relocation or absence deliberately. Preserve the required method, resolve Location, account for caching, and keep error-page status truthful.

Permanent moves are not all interchangeable

308 Permanent Redirect communicates that the resource has a new permanent URI while preserving the request method. That is important for a client that sends POST, PUT, or another non-GET method. A redirect from an old page to a new page is easy to test with GET; a migration of an endpoint must also be tested with the method that real callers use.

curl -sS -D - -o /dev/null https://old.example.test/api/item

Without --location, curl leaves the redirect unfollowed. Resolve Location against the original URI: an absolute URI, root-relative path, or other relative reference can be valid. Check the resolved host, path, and scheme. 301/302 permit changing POST to GET; 307/308 preserve the method. Test state-changing methods only against an isolated endpoint. 308 is heuristically cacheable, subject to method and cache controls, so a cached move can outlive a server configuration change.

If the intent is to show a result after a completed action, 303 See Other points to a separate resource that the client can retrieve with GET or HEAD. It does not ask the client to replay the original write at a new address; choose that behavior deliberately rather than treating every redirect as a relocation.

Distinguish missing from removed

Use 404 Not Found when the server cannot find a current representation and the absence may be temporary or unknown. 410 Gone is stronger: it says access is no longer available and the condition is likely permanent; it does not establish why the resource disappeared. Both should have a body that helps a human, but neither should return 200 just because a custom error page rendered successfully.

404 can also conceal whether a forbidden resource exists. Both 404 and 410 are heuristically cacheable, subject to method and cache controls. Choose an explicit policy for error responses: a cached missing-route result can remain visible after the route is repaired.

The check belongs at the edge:

curl -sS -D missing.headers -o missing.html -w '%{http_code} %{url_effective}\n' \
 https://www.example.test/a-route-that-does-not-exist

Keep the response headers on the error path. Security headers, a useful content type, and a correct status are more valuable than a decorative error animation.

Sources

RFC 9110 — HTTP Semantics, sections 15 and 13, checked 2026-07-14.
RFC 7538 — 308 Permanent Redirect, section 3, checked 2026-07-14.
curl manual, status and redirect inspection flags, checked 2026-07-14.

Read the public edge in two commands

Mon, 13 Jul 2026 00:00:00 +0000

A deployment is complete when public responses match the release contract, not when the last upload exits zero. Two read-only helpers from the operator kit expose useful evidence, but they do not prove the whole artifact was published correctly.

These are illustrative excerpts. Evaluate HTTP status and expiry separately; verify hostname, trust and body equality with the checks that actually test them.

Inspect the response headers

check-http-headers.sh performs a GET, discards the body, follows redirects, and prints the response headers for each hop plus the final status and URL:

check-http-headers.sh https://www.xbcatm.com/

This illustrative output shows the fields to inspect. It is not a fresh production observation:

HTTP/2 200
accept-ranges: bytes
content-security-policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:
content-type: text/html; charset=utf-8
last-modified: Mon, 24 Aug 2026 11:20:54 GMT
permissions-policy: accelerometer=(), camera=(), geolocation=(), gyroscope=(), microphone=(), payment=(), usb=()
referrer-policy: strict-origin-when-cross-origin
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY

HTTP_STATUS 200
FINAL_URL https://www.xbcatm.com/

Check the expected status, final host and path, and the policy on the final response. The helper does not use curl’s --fail: an HTTP 404 or 500 can still leave the shell command successful. Treat its printed status as data to evaluate. A header mismatch warrants investigation of server, proxy, or cache configuration; it does not by itself prove the wrong output directory is live.

Inspect the certificate dates

check-tls-expiry.sh HOST [DAYS] extracts the certificate presented with SNI and checks whether its expiry is at least the requested number of seconds away:

check-tls-expiry.sh www.xbcatm.com 30

An illustrative excerpt, with the fingerprint line omitted:

subject=CN=www.xbcatm.com
issuer=C=US, O=Let's Encrypt, CN=YE1
notBefore=Aug 21 08:37:13 2026 GMT
notAfter=Nov 19 08:37:12 2026 GMT

certificate remains valid for at least 30 day(s)

The helper prints subject, issuer, dates, and SHA-256 fingerprint. It does not print the remaining day count. Its success message describes the expiry test only: the script does not enforce hostname or trust-chain validation, and -checkend does not validate notBefore. The subject CN is not sufficient hostname evidence; service identity is matched against the certificate’s subject alternative names. A valid wildcard may legitimately cover the host.

Use a separate verification when those properties matter:

openssl s_client -connect www.xbcatm.com:443 -servername www.xbcatm.com \
 -verify_hostname www.xbcatm.com -verify_return_error </dev/null

This uses the configured trust store and fails on certificate verification errors under OpenSSL’s matching rules. In OpenSSL 3.0, hostname verification can fall back to the subject CN when no suitable DNS subject alternative name is present. A successful command therefore does not by itself establish RFC 9525’s SAN-only identity policy: inspect the SAN extension and verify the intended client’s policy separately. Keep a job-level timeout around the TLS helper, which does not impose its own network deadline. Certificate inspection and automatic renewal configuration remain separate checks.

Use both around a release

Before: save the expected policy, final URL, validators, and certificate dates with a UTC collection time.
Deploy the already validated artifact.
After: repeat the probes and fetch representative bodies for comparison with that artifact.

Headers and certificate dates cannot establish byte equality. Last-Modified may stay unchanged or be rewritten during copying. The release smoke test saves bodies and compares them directly; a complete manifest extends that check beyond one page. Browser behavior, geographic edge differences, and load-dependent failures need separate tests. Record which paths and observation points were actually checked.

Sources

curl manual, GET, redirect, header output, and HTTP failure behavior, checked 2026-10-15.
OpenSSL s_client, SNI, explicit hostname checks, and failure on verification errors, checked 2026-10-15.
OpenSSL verification options, hostname matching and subject-CN fallback, checked 2026-10-15.
OpenSSL x509, certificate display and expiry-only -checkend behavior, checked 2026-10-15.
RFC 9525 — Service Identity in TLS, subject alternative names and wildcard identity matching, checked 2026-10-15.
Caddy Automatic HTTPS, automatic certificate management and renewal configuration, checked 2026-10-15.
MDN: Content Security Policy guide, CSP directive background, checked 2026-07-13.
RFC 9110 — HTTP Semantics, response metadata and validators do not establish a complete artifact match, checked 2026-10-15.

A release is not complete until the public edge agrees

Thu, 09 Jul 2026 00:00:00 +0000

Static publishing removes application runtime complexity, but it does not remove the boundary between a generated directory and a public response. A release check should cover both.

Use the same artifact before and after selection. The download row refers to public/downloads/check-http-headers.sh in the article. Supported content codings are decoded before cmp; server transformations need a documented rule. Status and header checks are separate. Retain the previous directory for a deliberate rollback.

Start from a clean artifact

Build with the pinned generator into a clean destination. Record the source commit, generator version, output file list, and checksums of files that users download. A clean build catches stale files that a copy-over deployment can accidentally preserve.

set -eu
make verify
find public -type f -print | sort

The file list is evidence, not decoration. If a route disappears, the diff should explain whether the source was removed or the generator failed to emit it.

Exercise three response classes

Before publishing, test the staged artifact with the intended server configuration. After switching directories, repeat these checks at the public edge; probing the old live site cannot validate the new release. Request one HTML page, one static resource, and one missing path. Inspect status, content type, cache policy, and security headers:

set -eu
curl --compressed -fsS -D page.headers -o page.body https://www.example.test/
curl --compressed -fsS -D asset.headers -o asset.body \
 https://www.example.test/downloads/check-http-headers.sh
curl --compressed -sS -D missing.headers -o missing.body \
 https://www.example.test/does-not-exist

cmp public/index.html page.body
cmp public/downloads/check-http-headers.sh asset.body
cmp public/404.html missing.body

Run each fragment as a standalone shell script or in a disposable shell session. set -eu stops this sequential script after a failed build, transfer, or comparison, so a later successful command cannot hide an earlier failure. The missing-path request intentionally does not use -f: a 404 is expected and should still be captured. Check the final status in each header file: 200, 200, then 404; the byte comparisons do not automate that status check. No redirect is followed here. --compressed decodes supported content codings before comparison; a deliberate server-side HTML transformation needs its own documented comparison rule. cmp is silent on equality and returns nonzero on a difference. Repeat for /zh/ and its error page rather than assuming language parity.

Keep rollback simple

Do not delete the previous directory until the new one has passed the checks. A rollback should select a known-good directory, not reconstruct one from memory during an incident. The release checklist and HTTP header check are deliberately small enough to run from a clean shell.

Sources

RFC 9110 — HTTP Semantics, status and representation semantics, checked 2026-07-09.
curl manual, response inspection options, checked 2026-07-09.
Static-site release checklist, local companion resource.

A postmortem should leave a fact record

Tue, 07 Jul 2026 00:00:00 +0000

A postmortem earns trust when its claims can be re-checked. Record each observation’s source, collection time and timezone, command or query, and exit status where relevant. Logs, metrics, and clearly attributed human observations also count; distinguish confirmed facts from hypotheses and preserve redacted evidence rather than secrets. The four phases below keep a write-up reviewable at any later time.

Tie every phase to captured evidence. A post-fix sample is a bounded observation; causes, uncertainty and owned prevention still need explicit treatment.

Detect: the symptom, with evidence

Start with the smallest verifiable symptom and the command that showed it. Save the actual capture. The following is an illustrative excerpt, not evidence of a fresh probe:

$ check-http-headers.sh https://www.xbcatm.com/
HTTP/2 200
content-security-policy: ... script-src 'none' ...
last-modified: Mon, 24 Aug 2026 11:20:54 GMT

If the symptom is that a header changed, the output showing the previous policy and the new one belongs side by side. If it is a failure, include the exit status and the error line.

Scope: how wide, and how you know

State the blast radius with evidence, not adjectives. Define the boundary you can inspect:

Which hosts and paths show the symptom? Record each probed URL and observation time; one successful request cannot establish the state of every edge or visitor.
Does the cache differ from origin? Compare actual responses, cache metadata, and validators from both paths using the same request headers. Vary describes selection inputs, not proof that the response came from cache.
What delays recovery? For a DNS change, record the old TTL and resolver observations. For HTTP caches, record freshness and revalidation policy separately; a DNS TTL is not a universal rollback deadline.

Fix: the change and its intended effect

Record the actual configuration diff and deployment reference so the corrective action can be understood and, where safe, replayed. This header fragment is an expected observation, not a shell command or a complete policy. Prefer the smallest change that restores the contract, and name what the post-fix run should show:

Content-Security-Policy: script-src 'none'

Verify: the post-incident run

Repeat the detection command after the change and show that the observed output now matches the intended contract. A postmortem without this final section is a story; with it, it is a record that approves its own future re-check.

Close the record with contributing causes, what remains uncertain, and preventive actions with an owner, due date, and acceptance check. A successful probe confirms that sampled path at that time; it does not establish the cause or prevent recurrence by itself.

Sources

RFC 9110 — HTTP Semantics, response metadata and conditional requests, checked 2026-07-07.
artifact HTTP header check, read-only inspection used throughout this record.
Google SRE: Postmortem Culture, impact, contributing causes, evidence review, and preventive actions, checked 2026-10-15.
RFC 9111 — HTTP Caching, cache selection and freshness are distinct from DNS cache lifetimes, checked 2026-10-15.

Range requests should prove which bytes were selected

Mon, 06 Jul 2026 00:00:00 +0000

Range requests let a client ask for part of a representation. Media players, resumable download tools, and diagnostic clients use them, but a server that advertises or returns ranges incorrectly can produce silent corruption instead of a clean failure.

Keep the representation and content coding stable. Match interval, total size and actual body bytes; a complete 200 can be valid when Range is ignored. Resume only with an appropriate strong validator.

Establish the complete size

Use an immutable test download of at least 16 bytes. Run the fragments in the same disposable shell session so url and size remain available. Their explicit set -eu stops after a failed transfer, size check, or comparison; inspect the HTTP status and range fields separately. Save the complete body, headers, and validator in that temporary working directory:

set -eu
url=https://www.example.test/downloads/archive.tar.gz
curl -fsS -H 'Accept-Encoding: identity' -D full.headers -o full.body "$url"
size=$(wc -c < full.body)
test "$size" -ge 16
awk 'tolower($1) ~ /^(content-length:|content-encoding:|etag:|last-modified:|accept-ranges:)$/ { print }' full.headers

Check that the full response is 200 and has no unexpected content coding. The commands request the identity representation and do not use automatic decompression; byte ranges apply to the selected encoded representation, so changing encoding invalidates the comparison. Content-Length may be absent, which is why the complete body supplies the size.

Accept-Ranges: bytes is an explicit signal, but absence of the header does not by itself prove that range requests are unsupported. Exercise the request.

Request a known interval

Ask for the first 16 bytes and keep both headers and body:

set -eu
curl -sS -D range.headers -o range.body \
 -H 'Accept-Encoding: identity' -H 'Range: bytes=0-15' "$url"

wc -c range.body
head -c 16 full.body > expected.body
cmp expected.body range.body
awk 'tolower($1) ~ /^(content-range:|content-length:|etag:)$/ || /^HTTP\// { print }' range.headers

A successful byte-range response uses 206 Partial Content. Content-Range should identify 0-15 and the complete representation length, while the body should contain exactly 16 bytes.

The byte comparison deliberately tests the partial-body case. A valid full 200 larger than 16 bytes will fail it and stop this shell session; inspect the saved headers before calling that corruption. Conversely, a complete 16-byte file can pass cmp even with 200, so status and Content-Range still need checking.

Test an impossible range

Start at the complete byte count: for a file of size N, the last valid offset is N−1. Unlike a fixed large constant, this is outside the known representation:

set -eu
curl -sS -D - -o /dev/null \
 -H 'Accept-Encoding: identity' -H "Range: bytes=${size}-" "$url"

When the server rejects an unsatisfiable byte range with 416 Range Not Satisfiable, it should include Content-Range, for example bytes */12345, to report the current size. A 200 response may be valid when the server ignores the range, but it must return the complete representation rather than a mislabeled fragment.

Keep validators in the story

Resumed downloads can use If-Range with a strong ETag. A weak ETag is forbidden; an HTTP date is allowed only when no ETag is available and the date qualifies as a strong validator. If the representation changed, the safe response is the full current representation, not bytes spliced from two versions. Test this behavior before calling a download resumable.

Sources

RFC 9110 — HTTP Semantics, range units, partial responses, and Content-Range, checked 2026-07-06.
curl manual, --range and header options, checked 2026-07-06.

HTTP methods are a promise about side effects

Thu, 02 Jul 2026 00:00:00 +0000

A request method tells the server what the client is asking it to do. A read-only file origin has a narrow contract, but “static site” alone does not prove that proxies or imported handlers expose no write operations. Check the route actually serving the resource.

Separate requested state change from intended repeat effect, then inspect the actual route. The file-handler boundary is scoped; method support is separate from CORS permission.

Safe and idempotent answer different questions

GET and HEAD are safe: the client does not request a state-changing action. Incidental logging, metrics, or accounting can still change server state. PUT and DELETE are idempotent in their defined semantics, but are not safe: repeating the same request is intended to have the same effect as performing it once. That does not require identical response statuses, and it does not make every retry after a network failure appropriate.

For a read-only static origin:

GET retrieves a representation.
HEAD describes the corresponding GET without response content.
OPTIONS asks about the target’s communication options; a file handler may reject it.
POST / PUT / DELETE / PATCH should not fall through to successful file serving unless a separate, intended handler implements their semantics.

A Caddy file handler’s method boundary

Caddy v2.10.2’s file-serving path accepts GET and HEAD and rejects other methods with 405 and Allow: GET, HEAD. Redirects, missing paths, error handlers, and other configured routes can answer earlier or differently, so this is not a universal response for every static-site URL.

The earlier note recorded:

$ curl -s -o /dev/null -w 'OPTIONS -> HTTP %{http_code}\n' -X OPTIONS https://www.xbcatm.com/
OPTIONS -> HTTP 405

The original response log is not retained here, and this review did not reproduce that live result. The command reports only status; it does not establish that the required Allow field was present. Inspect that field separately. 405 means a known method is not supported for this target; 501 Not Implemented is the usual distinction when the server does not recognize or implement a method at all.

HEAD parity allows documented omissions

HEAD should describe the same selected representation as GET, while omitting content. Fields calculated only while generating the content may be omitted. If Content-Length is present, it must describe the corresponding GET content, using the same content coding.

The earlier note reported this comparison:

HEAD content-length: 15890
GET bytes read : 15890

Those historical numbers are not a fixed expected size or a current verification result. A missing HEAD length alone is legal; a wrong supplied length needs investigation. Follow the head-request-parity note for paired probes. The downloadable check-http-headers.sh helper inspects a GET response and does not perform this comparison automatically.

Reject unintended writes without hiding the contract

For a method recognized but disallowed on the target, return 405 with Allow listing the methods actually supported. The list is not necessarily restricted to safe methods on an application route. Do not return a plausible 200 page for an ignored write request.

If browser clients need CORS preflight, define that OPTIONS behavior explicitly; method support and CORS permission are separate decisions. Test write rejection only against an authorized disposable fixture rather than assuming a public endpoint is harmless because the site looks static.

Sources

RFC 9110 — HTTP Semantics, safe/idempotent methods and HEAD/405/501 semantics, checked 2026-10-15.
MDN: HTTP request methods, method overview, checked 2026-10-15.
curl manual, method and response-inspection options, checked 2026-10-15.
Caddy v2.10.2 file-server source, method rejection after file selection, checked 2026-10-15.
WHATWG Fetch Standard, CORS preflight processing, checked 2026-10-15.

Validators decide whether a cached copy is still the answer

Tue, 30 Jun 2026 00:00:00 +0000

A cache can ask whether its stored copy is still usable without always downloading the body again. It sends a validator; a matching conditional GET can receive 304 Not Modified, while a changed representation normally needs a new 200 response. Validation saves bytes on a hit, not on every request.

Illustrative tags; otherwise successful requests. GET/HEAD use weak comparison. HEAD has no body. Matching is neither byte identity nor freshness. Other methods normally return 412; If-Range cannot use weak ETags.

Validator type and strength are different questions

An ETag is an opaque, quoted value. It can be strong ("release-a") or explicitly weak (W/"release-a"). Strong comparison requires both tags to be strong and equal; weak comparison compares the opaque values regardless of the W/ marker. Weak tags can describe semantic equivalence even when bytes differ.

Last-Modified is a timestamp with one-second HTTP-date resolution. It is usually weak unless the conditions in RFC 9110 section 8.8.2.2 establish it as strong. Do not classify every ETag as strong or every timestamp as unconditionally weak.

The earlier site observation recorded:

etag: "dkx84jwth7nkc9e"
last-modified: Mon, 24 Aug 2026 13:55:23 GMT

These are historical values; the original response log is not retained here and the live result was not rechecked in this review. Caddy’s file server normally sets both fields, subject to file metadata and configuration.

Conditional GET uses weak comparison

Send the ETag exactly as received in If-None-Match, including its quotes and any W/. The original note reported HTTP 304 for the value above but printed an unquoted request value. That request text was not valid entity-tag syntax and should not be copied as a working probe. Obtain a current validator before testing a live endpoint.

This socket-free exercise illustrates the comparison for individual, already-parsed tags; it is not a complete HTTP header parser:

def weak_value(tag):
 return tag[2:] if tag.startswith('W/') else tag

def strong_equal(a, b):
 return not a.startswith('W/') and not b.startswith('W/') and a == b

stored = 'W/"release-a"'
current = '"release-a"'
assert weak_value(stored) == weak_value(current)
assert not strong_equal(stored, current)
assert weak_value(stored) != weak_value('"release-b"')
print("weak match: True; strong match: False; changed tag: no match")

For an otherwise successful GET or HEAD, a matching If-None-Match produces a body-free 304. The same false precondition on another method normally produces 412 Precondition Failed. If both If-None-Match and If-Modified-Since are present, the ETag condition takes precedence. Byte-range validation with If-Range cannot use a weak ETag.

Republish without preserving a misleading validator

An ETag is not necessarily a content hash. Caddy v2.10.2’s default file tag is derived from modification time and size; replacing bytes while preserving both can preserve the tag. Inspect the deployed version and any configured overrides, then make the release process update the validator’s inputs or use content-based versioning.

Keep byte checksums in the release manifest and test both unchanged and changed responses. A checksum does not automatically become the server’s ETag. A 304 also needs the applicable cache metadata so a cache can update its stored response; it is not merely an empty success status.

Sources

RFC 9110 — HTTP Semantics, sections 8.8 and 13 on validator strength and preconditions, checked 2026-10-15.
RFC 9111 — HTTP Caching, section 4.3 on validation and updating stored responses, checked 2026-10-15.
MDN: HTTP conditional requests, conditional-request overview, checked 2026-10-15.
Caddy v2.10.2 file-server source, calculateEtag inputs and default response fields, checked 2026-10-15.

Compression changes the selected HTTP representation

Mon, 29 Jun 2026 00:00:00 +0000

Compression saves transfer bytes, but it also creates another representation of a resource. A client announces acceptable content codings with Accept-Encoding; the server describes the applied coding with Content-Encoding.

Compression selects representation bytes, so negotiation, cache matching, and validators must agree. Distinct coded bytes need distinct strong tags. Compare the decoded download with the artifact; an encoded Content-Length need not equal the decoded file size.

Make negotiation visible

When a response can change according to Accept-Encoding, include that request field in Vary. This tells shared caches that a compressed response and an identity response are not interchangeable cache entries.

Compare the two paths instead of checking only a browser request:

curl -sS -D - -o /dev/null \
 -H 'Accept-Encoding: identity' https://www.example.test/
curl -sS --compressed -D - -o /dev/null \
 https://www.example.test/

Inspect Content-Encoding, Vary, Content-Length when present, and the validator. Strong entity tags must differ when content coding changes the representation bytes. A shared weak tag is possible for semantically equivalent variants, but it cannot support strong comparison. Check conditionals against the same negotiated representation.

Compress appropriate content

Text formats such as HTML, CSS, JSON, XML, and SVG usually benefit from compression. Formats that are already compressed might not. Caddy’s encode directive negotiates supported encodings and normally avoids encoding a response without an appropriate content type or minimum size.

Do not add compression solely to satisfy a score. Measure a representative response, confirm that the edge emits the intended headers, and verify that downloadable files retain the correct content type and checksum after transfer decoding.

With --compressed, curl decodes the body automatically but leaves saved response headers unchanged. A reported Content-Length, when present, describes encoded content, so it need not equal the size of the decoded download. Compare a checksum with the artifact only after content decoding; HTTP transfer framing is a separate layer. The option also does not guarantee compression: inspect the actual response, especially for small or already-compressed files.

Sources

RFC 9110 — HTTP Semantics, content codings and Vary, checked 2026-10-15.
Caddy encode directive, content encoding selection and negotiation, checked 2026-10-15.
curl manual, --compressed, checked 2026-10-15.

Cache headers are a contract with two clocks

Thu, 25 Jun 2026 00:00:00 +0000

Caching is not a single switch. A response has a freshness decision made by a cache and a validation conversation with the origin. Mixing those two ideas produces either stale content or needless requests.

Storage, freshness, and validation answer separate questions. Match the policy to how the URL changes, preserve validators exactly, and check shared-cache variants.

Pick the change model first

For an HTML document that may change after publication, Cache-Control: no-cache is usually a more accurate starting point than no-store. no-cache permits storage but requires a cache to validate before reuse; no-store asks caches not to store the response at all. The distinction matters when you want conditional requests and a cheap 304 Not Modified response.

For a fingerprinted asset such as app.4f2c.js, the URL changes when the bytes change. A long freshness lifetime can then be reasonable:

Cache-Control: public, max-age=31536000, immutable

That policy is unsafe for a stable URL whose contents can be replaced in place. If the URL is stable, prefer a shorter lifetime and a validator such as an entity tag (ETag) or a meaningful Last-Modified value.

Choose who may store the response as well as how long it stays fresh. Use the unqualified private directive when shared caches must not store user-specific content; a browser’s private cache can still store it. no-cache alone does not provide that restriction. The public example above is for assets safe to share across users, not a default for personalized responses.

Inspect both paths

Make one ordinary request and one conditional request. The exact server flags vary, but the evidence you want is stable:

curl -sS -D - -o /dev/null https://www.example.test/
curl -sS -D - -o /dev/null \
 -H 'If-None-Match: "copy-a-real-etag-from-the-first-response"' \
 https://www.example.test/

Do not paste a made-up validator into a runbook. Copy the value from the first response or use a test fixture. For this conditional GET, a matching If-None-Match can yield 304 using weak comparison: it permits semantic equivalence, not necessarily byte identity. A changed validator normally produces a new 200 response. Keep the ETag’s quotes and any W/ prefix intact.

Keep intermediaries visible

Age, Vary, and the cache-control directives explain why two clients can receive different results. If a response varies by Accept-Encoding, language, or another request field, that dimension belongs in Vary; otherwise a shared cache can reuse the wrong representation.

The useful release check is not “the scanner found a cache header”. It is “the header matches the replacement policy, and a conditional request behaves as documented”.

immutable applies during the advertised freshness lifetime; it is not a permanent ban on revalidation. Keep versioned URLs immutable and older assets reachable while old HTML can still reference them. Changing today’s cache header does not retroactively shorten a previously cached response’s lifetime, so a cache-policy mistake may require a new URL or an explicitly supported cache purge.

Sources

RFC 9111 — HTTP Caching, sections 4–5, checked 2026-10-15.
RFC 9110 — HTTP Semantics, sections 8 and 13, checked 2026-10-15.
MDN: Cache-Control, directive semantics and defaults, checked 2026-10-15.
RFC 8246 — Immutable Responses, freshness-limited immutable semantics, checked 2026-10-15.

HSTS should be rolled out with a recovery plan

Tue, 23 Jun 2026 00:00:00 +0000

HTTP Strict Transport Security tells a supporting browser to use HTTPS for a host during a cached period. That persistence is the feature and the risk: removing the header does not immediately erase policy already stored by clients.

Extend HSTS only after observation. Decide descendant scope and preload separately. Recovery needs valid HTTPS and cannot instantly erase every stored or preloaded policy.

Verify the HTTPS path first

Before sending HSTS, confirm that the canonical hostname serves a valid certificate and that HTTP redirects to the intended HTTPS URL without depending on user input:

curl -sS -D - -o /dev/null --max-redirs 0 http://www.example.test/
curl -sS -D - -o /dev/null https://www.example.test/

Check representative deep routes and error pages. HSTS cannot repair a certificate error because the browser requires a valid HTTPS connection before accepting the policy.

Start with a short max-age

A staged rollout limits the recovery window while configuration is new:

Strict-Transport-Security: max-age=300

After observing the site and renewal path, increase the duration deliberately. Record the date, chosen value, and rollback conditions. A final policy might use a year, but the number is a commitment rather than a scanner score.

Treat includeSubDomains as a separate decision

includeSubDomains extends policy to every subdomain. Inventory names first, including old services, delegated zones, and hostnames used only on internal networks. One HTTP-only descendant is enough to make the option disruptive for clients that received the parent policy.

Preload is not ordinary header configuration

Browser preload programs can distribute policy outside the normal response cycle. Their requirements and removal delays are stricter than setting a header. Do not request preload merely because a scanner recommends it; confirm long-term ownership of the domain and all covered names.

Verify the public response

curl -sS -D - -o /dev/null https://www.example.test/ \
 | awk 'tolower($1) == "strict-transport-security:" { print }'

Test the canonical public edge, not only an origin port. Proxies may add, remove, or duplicate the header.

Know what rollback can clear

A valid HTTPS response with max-age=0 clears that host’s learned policy only for clients that receive it. Removing the header or sending it over HTTP does not clear a cached policy. A child cannot opt out of a parent’s still-active includeSubDomains, and clearing a parent does not delete policies independently learned for children.

Scope follows the host that sends the header: policy from www.example.test covers that host and, with includeSubDomains, its descendants, not the sibling api.example.test or the parent example.test. Keep HTTPS working during recovery. Preload removal is a separate browser-update process, not an immediate response-header rollback.

Sources

RFC 6797 — HTTP Strict Transport Security, policy processing and scope, checked 2026-10-15.
MDN: Strict-Transport-Security, directives and deployment cautions, checked 2026-10-15.
HSTS preload program, submission requirements and removal constraints, checked 2026-10-15.

HEAD should describe the same representation as GET

Mon, 22 Jun 2026 00:00:00 +0000

The HEAD method asks for the response a server would send to GET, without transferring the response content. It is useful for checks that need status, validators, type, or length, but only when the metadata remains aligned with the real GET path.

Match the URL, request headers, release, and content coding before comparing HEAD with GET. Permitted omissions are not automatic failures. Keep a small GET body or checksum check, because plausible metadata cannot prove that the payload is intact.

Compare a normalized header set

Dynamic headers such as Date will differ between requests. Compare the fields that describe the selected representation:

url=https://www.example.test/downloads/manual.pdf

curl -sS -I "$url" > head.headers
curl -sS -D get.headers -o /dev/null "$url"

for file in head.headers get.headers; do
 printf '== %s\n' "$file"
 awk '
 /^HTTP\// ||
 tolower($1) ~ /^(content-type:|content-length:|content-encoding:|cache-control:|etag:|last-modified:|vary:)$/ { print }
 ' "$file"
done

Run this in a disposable working directory; the two header files are overwritten. Match the URL, request headers, and release version. Compression negotiation belongs in the comparison: send the same Accept-Encoding value to both requests.

HEAD should describe the corresponding GET, but RFC 9110 permits omission of fields determined only while generating content. Missing Content-Length alone is not a failure. If present on HEAD, it must be the length the corresponding GET content would have, not zero just because HEAD has no body. Compare encoded lengths consistently and investigate changed validators or types rather than requiring byte-identical header lists.

Do not use HEAD as the only release check

A server can synthesize plausible headers while the file is missing, unreadable, or truncated. Keep one small GET in the smoke test and verify its body or checksum. HEAD reduces transfer cost; it does not prove the payload.

Check redirects explicitly

Without --location, curl -I reports the first response. That is useful when testing redirect policy. With --location, it prints header blocks for the followed responses, including intermediate redirects and the final destination. Record which question the command answers:

curl -sS -I --max-redirs 0 https://old.example.test/manual
curl -sS -I --location https://old.example.test/manual

Treat method-specific failures as configuration defects

A static page that returns 200 to GET and 405 or 404 to HEAD usually exposes a proxy or routing inconsistency. Fix the method handling instead of teaching monitors to ignore it, unless the endpoint contract deliberately disallows HEAD.

Sources

RFC 9110 — HTTP Semantics, HEAD method semantics, checked 2026-10-15.
curl manual, --head, --include, and redirect options, checked 2026-10-15.