Configuration · XB Field Notes

nginx matches normalized paths and can select a location again

Thu, 26 Aug 2027 00:00:00 +0000

nginx location matching uses a normalized URI path rather than the untouched request-target text. Percent-encoded characters are decoded, relative path components are resolved, and adjacent slashes can be merged according to configuration. Later processing can change the current URI again and trigger another location search. Understanding both transformations is necessary when a request appears to enter a different handler than its original spelling suggests.

When it breaks

A path filter that reasons only about the raw request text can disagree with nginx’s routing view. An encoded slash can become a path separator, and a dot segment can remove an earlier component. A backend might apply its own decoding rules as well. Security and routing decisions need an agreed interpretation at each boundary, rather than assuming that every component sees an identical path string.

Logging only $uri can also obscure the incoming request. That variable represents the current normalized URI and may change during request processing. $request_uri retains the full original URI, including its original query. Neither is a universal replacement for the other: one explains current routing, while the other helps reconstruct what the client actually requested.

Index handling and try_files introduce another transition. A request for a directory can internally become a request for its index file. A failed file lookup can redirect internally to a fallback URI, causing a different location and different query arguments to apply. The first prefix match therefore does not necessarily identify the configuration that produces the final response.

Check it quickly

Run the script with host Python, Docker, and the pinned nginx image. It was executed with nginx 1.28.0 on Linux arm64 and Docker 29.3.1. It builds and syntax-checks a temporary configuration, publishes only a host-loopback port, sends request targets without client-side path normalization, and removes its own image, containers, and network:

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True);target.write_text(content)
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'

locations=r'''
location / { return 200 "$uri|$request_uri|$args"; }
location /protected/ { return 403 "blocked"; }
location /docs/ { try_files $uri $uri/ /fallback?reason=missing; }
location = /docs/index.html { return 200 "$uri|$request_uri|$args"; }
location = /fallback { return 200 "$uri|$request_uri|$args"; }
'''
with lab(config(locations),{'docs/index.html':'stored-index'}) as (container,request):
 cases={
 '/a//b/../c?x=1':'/a/c|/a//b/../c?x=1|x=1',
 '/a%2Fb/%2e%2e/c?x=1':'/a/c|/a%2Fb/%2e%2e/c?x=1|x=1',
 '/Protected/item':'/Protected/item|/Protected/item|',
 '/docs/':'/docs/index.html|/docs/|',
 '/docs/missing?x=1':'/fallback|/docs/missing?x=1|reason=missing'}
 for path,expected in cases.items():
 status,headers,body=request(path);assert status==200 and body.decode()==expected,(path,status,body)
 for path in ['/protected/item','/protected%2Fitem','/a/../protected/item']:assert request(path)[0]==403,path
 assert request('/bad%ZZ')[0]==400
 print('matching uses normalized paths: percent-decoding, dot segments, and merged slashes differ from the original request URI')
 print('index and try_files internal redirects choose another location; request_uri remains original while uri and args can change')

The request /a//b/../c?x=1 produces current URI /a/c, while the original request URI remains /a//b/../c?x=1 and the arguments remain x=1. This demonstrates slash merging and dot-segment resolution in the tested default configuration. The response includes all three fields so their meanings can be compared directly.

The encoded request /a%2Fb/%2e%2e/c?x=1 reaches the same current path /a/c. Its original encoded spelling is still preserved in request_uri. This case shows that percent-decoding participates in normalization before routing. The test does not infer behavior from a browser address bar, which may already have rewritten a path before sending it.

The protected prefix returns 403 for /protected/item, /protected%2Fitem, and /a/../protected/item. All normalize into the protected path family. In this Linux environment, /Protected/item instead reaches the ordinary fallback because the case differs. An invalid percent escape such as %ZZ is rejected with HTTP 400 rather than treated as a successful route to arbitrary content.

The fixture includes a real /srv/docs/index.html. Requesting /docs/ reaches the exact /docs/index.html location after index processing, which returns a diagnostic marker instead of the stored file’s body. The original request_uri remains /docs/. This makes the internal location change visible even though the client receives no redirect response.

For /docs/missing?x=1, try_files cannot find the requested file or directory and internally selects /fallback?reason=missing. The response reports current URI /fallback, original request URI /docs/missing?x=1, and current arguments reason=missing. The fallback’s explicit query replaces the earlier arguments in this example; preserving arguments would require an intentional configuration choice.

Verify the path contract across the full request chain

Test representative encoded forms, repeated slashes, dot segments, missing files, and directory requests when changing routing. Include the actual client, proxy, and application in integration tests if they normalize differently. The small fixture establishes nginx behavior for its chosen configuration; it does not prove every upstream framework or security filter interprets the same bytes identically.

Use original and current URI fields deliberately in diagnostics, while recognizing that query strings can contain sensitive data. Log only the request information the operational task needs. An internal redirect can change the final handler and logging context, so verify where the event is ultimately recorded as well as which initial location matched.

Keep fallback behavior explicit. A missing asset should not accidentally become a successful application page if that masks deployment errors, and protected routes should not escape into an unrelated fallback after rewriting. Syntax validation catches malformed configuration; requests with asserted statuses, fields, and bodies establish the behavior users actually receive.

Sources

nginx core location, try_files, and variables, URI normalization, internal redirects, and original versus current URI, checked 2026-09-12.
How nginx processes a request, index processing and subsequent location selection, checked 2026-09-12.
nginx 1.28.0 core implementation, the tested version’s location search and internal-redirection behavior, checked 2026-09-12.

ConfigMap files and environment have different lifetimes

Thu, 01 Jul 2027 00:00:00 +0000

Changing a ConfigMap updates an API object. Whether a running application changes behavior depends on how Kubernetes delivers the value and how the application reads it. Environment injection, normal volume projection, a subPath mount, and an already-open file are different paths with different lifetimes. Diagnose the consumer that actually matters rather than treating all configuration delivery as one mechanism.

Separate delivery from consumption

A ConfigMap reference in a container’s environment is resolved when that container starts. Updating the object does not rewrite the environment of an existing process or the configured environment used for later exec processes in that same container. Replacing the Pod with the intended reference can produce a new environment, but that is a lifecycle action, not an automatic result of editing data.

A normal ConfigMap volume is different: kubelet can project updated data eventually. The delay depends on its synchronization period and change-detection strategy, so an API update and a changed file are not simultaneous events. The projection also does not invoke the application’s reload handler. A program that reads only at startup may continue using its earlier parsed values indefinitely.

An open file description refers to the opened file rather than repeatedly resolving the original pathname. Replacing the file behind a path does not force existing descriptors to follow the replacement. A process that closes and reopens a projected path can therefore see new data while another descriptor still reads the old file. Application caching adds a further layer even after the filesystem view has changed.

Copying projected contents into a writable location creates another snapshot. The copied file is not a live link to the ConfigMap. If a startup script performs this copy, refreshing the copy needs its own explicit process.

When it breaks

A ConfigMap mounted through subPath does not receive the ordinary automatic updates. Choosing a convenient single-file mount can therefore change the update contract. Do not promise that every ConfigMap-backed file will refresh because one full-directory projection did. Inspect the actual volumeMount definition when two containers appear to disagree about the same object.

Watching configuration requires a deliberate application protocol. A watcher must handle the replacement behavior exposed by its filesystem and library; validating and applying the new settings are separate steps. Reading several keys independently can also race a version change. Define how the application loads a coherent configuration, rejects invalid values, and reports which version it is actually using.

A successful edit can otherwise create a split view: the API reports green, a newly opened projected path returns green, and the process still acts on blue. Restarting everything may hide that distinction without explaining it. First compare the object, delivery path, and application state, then choose a reload or replacement consistent with the workload’s intended contract.

Check it quickly

Use a disposable Kubernetes cluster with kubectl and python:3.11-slim-bookworm available on its nodes. Save the code as config-lifetime.py, then run python3 config-lifetime.py KUBECONFIG_PATH CONTEXT with explicit test-cluster arguments. The script creates and later deletes a unique namespace. The recorded cluster ran Kubernetes 1.34.11; allow up to three minutes for the ordinary projection to refresh.

import json
import subprocess
import sys
import time
from uuid import uuid4

assert len(sys.argv) == 3, 'usage: python3 example.py DISPOSABLE_KUBECONFIG CONTEXT'
base = ['kubectl', '--kubeconfig', sys.argv[1], '--context', sys.argv[2], '--request-timeout=30s']
image = 'python:3.11-slim-bookworm'


def k(*args, payload=None, expected=0):
 result = subprocess.run(base + list(args), input=json.dumps(payload) if payload is not None else None,
 capture_output=True, text=True, timeout=150)
 if expected is not None:
 assert result.returncode == expected, result.stderr
 return result


def obj(namespace, kind, name=None, selector=None):
 args = ['get', kind, '-n', namespace, '-o', 'json']
 if name:
 args.append(name)
 if selector:
 args += ['-l', selector]
 return json.loads(k(*args).stdout)


def apply(namespace, data):
 return k('apply', '-n', namespace, '-f', '-', payload=data)


def wait_for(read, ready, seconds=120):
 until = time.monotonic() + seconds
 while time.monotonic() < until:
 value = read()
 if ready(value):
 return value
 time.sleep(0.5)
 raise AssertionError('expected Kubernetes condition did not arrive')


def pod_ready(pod):
 return any(c['type'] == 'Ready' and c['status'] == 'True'
 for c in pod.get('status', {}).get('conditions', []))


def spec(script='import time; time.sleep(600)'):
 return {'automountServiceAccountToken': False, 'terminationGracePeriodSeconds': 1,
 'containers': [{'name': 'app', 'image': image, 'imagePullPolicy': 'IfNotPresent',
 'command': ['python3', '-c', script],
 'resources': {'requests': {'cpu': '10m', 'memory': '24Mi'},
 'limits': {'cpu': '200m', 'memory': '96Mi'}}}]}

namespace = 'notes-lifetime-' + uuid4().hex[:8]
k('create', 'namespace', namespace)
try:
 apply(namespace, {'apiVersion': 'v1', 'kind': 'ConfigMap', 'metadata': {'name': 'settings'},
 'data': {'mode': 'blue'}})
 script = ('from pathlib import Path; import time; '
 'held=open("/etc/lab/config/mode"); '
 'Path("/tmp/startup").write_text(held.read()); '
 'Path("/tmp/held-fd").write_text(str(held.fileno())); time.sleep(600)')
 podspec = spec(script)
 podspec['containers'][0]['env'] = [{'name': 'MODE', 'valueFrom':
 {'configMapKeyRef': {'name': 'settings', 'key': 'mode'}}}]
 podspec['containers'][0]['volumeMounts'] = [
 {'name': 'settings', 'mountPath': '/etc/lab/config', 'readOnly': True},
 {'name': 'settings', 'mountPath': '/etc/lab/single-mode', 'subPath': 'mode', 'readOnly': True}]
 podspec['volumes'] = [{'name': 'settings', 'configMap': {'name': 'settings'}}]
 apply(namespace, {'apiVersion': 'v1', 'kind': 'Pod', 'metadata': {'name': 'reader'}, 'spec': podspec})
 initial_pod = wait_for(lambda: obj(namespace, 'pod', 'reader'), pod_ready)
 wait_for(lambda: k('exec', '-n', namespace, 'reader', '--', 'python3', '-c',
 'from pathlib import Path; raise SystemExit(not Path("/tmp/held-fd").exists())',
 expected=None), lambda result: result.returncode == 0)
 probe = '''from pathlib import Path
import json,os
fd=Path('/tmp/held-fd').read_text()
print(json.dumps({'environment':os.environ['MODE'],
 'full_volume':Path('/etc/lab/config/mode').read_text(),
 'subpath':Path('/etc/lab/single-mode').read_text(),
 'startup_copy':Path('/tmp/startup').read_text(),
 'held_inode':Path('/proc/1/fd/'+fd).read_text()}))'''
 def observe():
 return json.loads(k('exec', '-n', namespace, 'reader', '--', 'python3', '-c', probe).stdout)
 before = observe()
 assert set(before.values()) == {'blue'}
 k('patch', 'configmap', 'settings', '-n', namespace, '--type=merge',
 '-p', json.dumps({'data': {'mode': 'green'}}))
 after = wait_for(observe, lambda values: values['full_volume'] == 'green', seconds=180)
 assert {v for key, v in after.items() if key != 'full_volume'} == {'blue'}
 final_pod = obj(namespace, 'pod', 'reader')
 assert final_pod['metadata']['uid'] == initial_pod['metadata']['uid']
 assert final_pod['status']['containerStatuses'][0]['restartCount'] == 0
 print(json.dumps({'before': before, 'after': after, 'same_pod_uid': True,
 'container_restart_count': 0, 'automatic_app_reload_tested': False}))
finally:
 k('delete', 'namespace', namespace, '--wait=true', '--timeout=90s')

One Pod consumes blue in five ways: its environment, a full-directory projection, a subPath mount, a startup copy, and a file descriptor opened by the original process. The initial check reads blue through all five. The script updates the ConfigMap to green and repeatedly reopens the full projected path until it sees the change.

After propagation, only full_volume reports green. Environment, subpath, startup_copy, and held_inode still report blue. The Pod UID remains identical and the container restart count stays zero. All assertions passed, and cleanup removed the namespace. This is direct evidence of different lifetimes within one running container, rather than an inference from the configuration manifest.

The fixture does not implement or test an application reload watcher, multi-key transactional loading, or a guaranteed propagation deadline. Its startup copy deliberately remains unchanged. In production, verify both delivery and the application’s accepted configuration version; a refreshed file alone cannot prove that requests are now served under the new settings.

Sources

Kubernetes: ConfigMaps, environment snapshots, eventual volume updates and subPath limits, checked 2026-09-13.
Linux: open(2), open file descriptions and pathname-independent references, checked 2026-09-12.

Named config files favor clarity

Sat, 21 Nov 2026 00:00:00 +0000

Configuration that is easy to find, read, and diff is more than a preference; it is how a change stays reviewable. Naming a file with a clear convention is the first step to environment-specific, single-source config.

A file is a record of intent

A named, versioned config file is a record of intent: the deployed values become explicit, reviewable, and reproducible just like code. When the file lives with the project, a change gets history, a blame, and a pull request, so anyone can answer ‘what actually shipped and who changed it’. A clear naming convention (app.conf for application knobs, app.env for environment shape) makes each file’s purpose obvious at a glance, and keeps the settings from being scattered into ad-hoc flags nobody can find.

Env and files solve different problems

Environment variables and files solve different problems. Variables are ideal for deploying the same build into many places without editing an image — you vary the value at run time per environment. Files are better for rich, structured settings a variable string would mangle. Most systems combine both: files keep the structure, the environment injects the values that differ per deploy. The rule that keeps it honest is that the source of truth stays explicit, and the boundary between structure and injectable values is drawn deliberately rather than by accident.

Secrets still move outside

Putting a config file in a repo is not a license to commit secrets into it. Anything that is a credential should be injected or referenced from a secrets store at run time, never baked into the file you commit and diff. The clean split is shape in files, secrets in a store: the committed config stays safe to show and the real values are encrypted where they live. If a value would be embarrassing or dangerous to publish, it does not belong in the committed file — that rule is exactly what tells you which are secrets.

When it breaks

Config names drift and the loader picks the wrong file. A deploy writes app-prod.json while the program opens app.prod.json, so the expected file is missing and the loader quietly falls back to a stale development file. The service starts, talks to the wrong database, and nothing in the diff explains it, because the real mistake is the filename rather than any value. Fail closed instead: resolve one explicit path at startup, log that path, and exit with file-not-found rather than guessing a sibling.

Environment overrides fail silently in the other direction. An empty APP_PORT= or a misspelled APP-PORT either overrides a good file value with an empty string or overrides nothing at all, depending on the loader, and the running value no longer matches any committed file. Because the change leaves no diff, the team re-reads the file and concludes nothing changed. Record the winning source for every key — file, environment, or flag — print it at startup, and reject empty values instead of treating them as real input.

Secrets leak when a convenient file becomes the real store. Someone commits a working .env carrying a production credential to fix staging once, removes it in the next commit, and assumes the problem is gone. It is not: the secret lives on in history, mirrors, and backups, and every clone made in between still carries it. Committed files should hold shape with placeholders such as password = "from-store", real values should arrive only from a secrets store or the runtime environment, and a scanner should block the commit before it lands.

Check it quickly

Save the following as config_precedence_probe.py and run python3 config_precedence_probe.py. It uses only the standard library, writes two temporary JSON files, and never touches your real config. The good sample starts from {"host": "127.0.0.1", "port": 8000, "mode": "dev"}, applies APP_PORT=9001 from the environment, then --mode prod from the command line, and asserts both the merged result and the per-key source map.

"""Config precedence probe: file < environment < CLI (stdlib only)."""
import json
import os
import sys
import tempfile

REQUIRED = ("host", "port", "mode")
ENV_MAP = {"host": "APP_HOST", "port": "APP_PORT", "mode": "APP_MODE"}

def parse_cli(argv):
 """Support --host/--port/--mode and --set key=value; returns dict."""
 out = {}
 i = 0
 while i < len(argv):
 arg = argv[i]
 if arg == "--set" and i + 1 < len(argv):
 i += 1
 kv = argv[i]
 if "=" not in kv:
 raise ValueError(f"bad --set (want key=value): {kv!r}")
 k, v = kv.split("=", 1)
 out[k.strip()] = v
 elif arg in ("--host", "--port", "--mode") and i + 1 < len(argv):
 i += 1
 out[arg[2:]] = argv[i]
 elif arg.startswith("--") and "=" in arg:
 k, v = arg[2:].split("=", 1)
 if k in REQUIRED:
 out[k] = v
 else:
 raise ValueError(f"unknown flag: {arg!r}")
 else:
 raise ValueError(f"unknown argument: {arg!r}")
 i += 1
 return out

def coerce(key, value):
 if key == "port":
 return int(str(value).strip())
 return str(value).strip()

def load_config(path, env, cli_args):
 """Merge file < env < CLI; raise KeyError listing missing fields."""
 with open(path, encoding="utf-8") as fh:
 file_cfg = json.load(fh)
 merged, source = {}, {}
 for key in REQUIRED:
 if key in file_cfg and str(file_cfg[key]).strip() != "":
 merged[key] = coerce(key, file_cfg[key])
 source[key] = "file"
 for key in REQUIRED:
 name = ENV_MAP[key]
 if name in env and str(env[name]).strip() != "":
 merged[key] = coerce(key, env[name])
 source[key] = "env"
 for key, raw in parse_cli(cli_args).items():
 if key in REQUIRED and str(raw).strip() != "":
 merged[key] = coerce(key, raw)
 source[key] = "cli"
 missing = [k for k in REQUIRED if k not in merged]
 if missing:
 raise KeyError(f"missing required fields: {', '.join(missing)}")
 return merged, source

def main():
 with tempfile.TemporaryDirectory() as tmp:
 good = os.path.join(tmp, "app.prod.json")
 with open(good, "w", encoding="utf-8") as fh:
 json.dump({"host": "127.0.0.1", "port": 8000, "mode": "dev"}, fh)
 # GOOD: env beats file, CLI beats env.
 merged, source = load_config(good, {"APP_PORT": "9001"}, ["--mode", "prod"])
 assert merged == {"host": "127.0.0.1", "port": 9001, "mode": "prod"}, merged
 assert source == {"host": "file", "port": "env", "mode": "cli"}, source
 print(f"GOOD {merged} via {source}")
 # BAD 1: missing field is an error, not a silent default.
 bad = os.path.join(tmp, "app.empty.json")
 with open(bad, "w", encoding="utf-8") as fh:
 json.dump({"host": "127.0.0.1"}, fh)
 try:
 load_config(bad, {}, [])
 except KeyError as exc:
 print(f"BAD-MISSING correctly rejected: {exc}")
 else:
 raise AssertionError("empty config should have failed")
 # BAD 2: drifted filename must fail closed, never fall back silently.
 try:
 load_config(os.path.join(tmp, "app-prod.json"), {}, [])
 except FileNotFoundError as exc:
 print(f"BAD-DRIFT correctly failed closed: {exc.filename}")
 else:
 raise AssertionError("drifted filename should have failed")
 print("PASS: file < env < cli, missing fields error, drift fails closed")

if __name__ == "__main__":
 try:
 main()
 except (KeyError, ValueError, FileNotFoundError, AssertionError) as exc:
 print(f"FAIL: {exc}", file=sys.stderr)
 raise SystemExit(1)

The bad samples prove the guardrails. An almost-empty file is rejected with missing required fields for port and mode instead of running on silent defaults, and a drifted filename such as app-prod.json raises file-not-found instead of falling back to another file. Expect three lines starting with good, bad-missing, and bad-drift, followed by a pass line confirming file beats nothing, environment beats file, and flags beat environment. If the good merge differs, the precedence order is wrong; if either bad sample passes silently, the loader is too forgiving.

Sources

12 Factor: config and environment, environment-driven configuration, checked 2026-11-19.
The Twelve-Factor App: build, release, run, separating stages, checked 2026-11-19.
man page: environment variables, how env shapes a process, checked 2026-11-19.

TLS version is a feature you pin

Wed, 23 Sep 2026 00:00:00 +0000

A TLS version policy defines which handshakes an endpoint accepts. Prefer an explicit minimum over assuming that a library’s changing defaults match your requirements. A maximum is a separate constraint: freezing it unnecessarily can prevent adoption of a newer supported protocol. Neither setting replaces certificate verification, suitable algorithms, or timely security updates.

A floor is not a ceiling

RFC 8996 deprecates TLS 1.0 and 1.1. RFC 9325 also rejects SSLv2 and SSLv3, recommends supporting TLS 1.3 and preferring it when implemented, and gives security requirements for retained TLS 1.2 support. A service with a known client population may choose TLS 1.3 only after evaluating interoperability; the existence of a stricter option does not make every TLS 1.2 connection insecure.

When both endpoints support TLS 1.3, merely allowing TLS 1.2 does not mean an attacker can freely force the weakest version. TLS includes authenticated negotiation and specific downgrade protections. However, a real old-only client can legitimately select an allowed older version, and unsafe retry behavior can undermine policy. Enforce the floor on each new connection instead of accepting success at any version.

Version numbers in a capture also need context. TLS 1.3 uses a legacy hello version value of 0x0303 for compatibility and negotiates its actual version through supported_versions. That legacy value alone is not evidence that the connection used TLS 1.2. Prefer the library’s negotiated ConnectionState when available.

When it breaks

A browser succeeding proves only one accepted path. It does not prove that TLS 1.0 is rejected, that a required TLS 1.2 client still works, or that all edge listeners enforce the same floor. Test accepted and rejected boundaries independently, including the correct hostname and trust roots.

A load balancer can terminate TLS before the request reaches the configured application. Client-to-edge and edge-to-origin policies are separate, as are another port, address family, or listener. Test the endpoint customers actually reach. Reloaded configuration is evidence of intent; observed negotiation is evidence of behavior.

Go’s TLS Config must not be modified after being passed to a TLS function. This example constructs configurations before starting servers. Apply a deployment’s supported reload procedure and test new connections; do not mutate a shared configuration while handshakes are using it.

Version overlap is necessary but insufficient. Unsupported signature algorithms, key-exchange groups, certificate names, or trust chains can still cause failure. Preserve the actual error, and do not label every handshake rejection a version mismatch. Avoid silently weakening the floor after a timeout; that can convert a transient network failure into a lasting security change.

Check it quickly

Save this as version_probe.go and run go run version_probe.go with Go 1.23 or newer. Two temporary loopback HTTPS servers share the same test logic but enforce different minimums. The fixture’s certificate is trusted only by its local test client. Requests use fresh transports, keep certificate verification enabled, and have two-second limits.

Server range	Client range	Expected result
1.2–1.3	1.2–1.3	TLS 1.3
1.2–1.3	1.2 only	TLS 1.2
1.2–1.3	1.1 only	Reject
1.3 only	1.2 only	Reject
1.3 only	1.2–1.3	TLS 1.3

package main

import (
 "crypto/tls"
 "fmt"
 "io"
 "log"
 "net/http"
 "net/http/httptest"
 "runtime"
 "sync/atomic"
 "time"
)

func check(ok bool, message string) {
 if !ok {
 panic(message)
 }
}

func probe(server *httptest.Server, minimum, maximum uint16) (uint16, error) {
 config := server.Client().Transport.(*http.Transport).TLSClientConfig.Clone()
 config.MinVersion, config.MaxVersion = minimum, maximum
 check(!config.InsecureSkipVerify, "certificate verification must stay enabled")
 transport := &http.Transport{TLSClientConfig: config, DisableKeepAlives: true}
 defer transport.CloseIdleConnections()
 client := &http.Client{Transport: transport, Timeout: 2 * time.Second}
 response, err := client.Get(server.URL)
 if err != nil {
 return 0, err
 }
 defer response.Body.Close()
 body, err := io.ReadAll(response.Body)
 if err != nil {
 return 0, err
 }
 check(response.StatusCode == 200 && string(body) == "ok\n", "unexpected HTTP reply")
 check(response.TLS.HandshakeComplete && len(response.TLS.VerifiedChains) > 0, "verified handshake required")
 return response.TLS.Version, nil
}

func main() {
 var handled atomic.Int64
 start := func(minimum uint16) *httptest.Server {
 server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 handled.Add(1)
 fmt.Fprintln(w, "ok")
 }))
 server.Config.ErrorLog = log.New(io.Discard, "", 0)
 server.TLS = &tls.Config{MinVersion: minimum, MaxVersion: tls.VersionTLS13}
 server.StartTLS()
 return server
 }
 compatible := start(tls.VersionTLS12)
 defer compatible.Close()
 strict := start(tls.VersionTLS13)
 defer strict.Close()

 version, err := probe(compatible, tls.VersionTLS12, tls.VersionTLS13)
 check(err == nil && version == tls.VersionTLS13, "modern peers must select TLS 1.3")
 fmt.Println("server 1.2-1.3, client 1.2-1.3:", tls.VersionName(version))

 version, err = probe(compatible, tls.VersionTLS12, tls.VersionTLS12)
 check(err == nil && version == tls.VersionTLS12, "TLS 1.2-only client must remain compatible")
 fmt.Println("server 1.2-1.3, client 1.2 only:", tls.VersionName(version))

 _, err = probe(compatible, tls.VersionTLS11, tls.VersionTLS11)
 check(err != nil, "client below TLS 1.2 floor must fail")
 _, err = probe(strict, tls.VersionTLS12, tls.VersionTLS12)
 check(err != nil, "client below TLS 1.3 floor must fail")
 check(handled.Load() == 2, "rejected handshakes must not reach HTTP")

 version, err = probe(strict, tls.VersionTLS12, tls.VersionTLS13)
 check(err == nil && version == tls.VersionTLS13, "strict server must still accept TLS 1.3")
 check(handled.Load() == 3, "exactly three HTTP requests must succeed")
 fmt.Println("both below-floor clients rejected; strict server still accepts TLS 1.3")
 fmt.Println(runtime.Version())
}

The program asserts this matrix and checks that rejected handshakes never reach HTTP. The shared handler count remains two after both negative cases, then becomes three when the strict server accepts a modern client. All assertions passed on macOS with Go 1.27.0. Explicit upper bounds make this experiment reproducible; they are not a recommendation to copy a fixed ceiling into every deployment.

These are genuine negotiated connections, not configuration-file inspection. The test does not execute SSLv2, SSLv3, TLS 1.0, active downgrade attacks, or a production proxy rollout. Before raising a live floor, inventory required clients, test the intended listener configuration in staging, and monitor handshake failures during deployment. If compatibility fails, revisit that deliberate policy decision rather than disabling identity checks.

Sources

RFC 8996: Deprecating TLS 1.0 and TLS 1.1, obsolete-version rejection, checked 2026-09-09.
RFC 9325: Secure Use of TLS and DTLS, version policy, preference, and interoperability guidance, checked 2026-09-09.
RFC 8446: TLS 1.3, supported_versions and downgrade protection, checked 2026-09-09.
Go crypto/tls, MinVersion, MaxVersion, and negotiated state, checked 2026-09-09.
Go net/http/httptest, local TLS fixtures and trusted test clients, checked 2026-09-09.

Configuration · XB Field Notes

nginx matches normalized paths and can select a location again

When it breaks

Check it quickly

Verify the path contract across the full request chain

Sources

ConfigMap files and environment have different lifetimes

Separate delivery from consumption

When it breaks

Check it quickly

Sources

Named config files favor clarity

A file is a record of intent

Env and files solve different problems

Secrets still move outside

When it breaks

Check it quickly

Further reading

Sources

TLS version is a feature you pin

A floor is not a ceiling

When it breaks

Check it quickly

Further reading

Sources