docs

Conclusion: it depends on where TLS is terminated

[Client] ──TLS handshake──▶ [ only whoever saw the ClientHello can compute JA4 ]

Computing JA4 requires the raw ClientHello byte sequence. A process that only sees the plaintext HTTP after TLS decryption cannot reconstruct JA4 afterward.

JA4 feasibility by setup pattern

Computing JA4 needs the raw ClientHello bytes, so feasibility is decided solely by where TLS is terminated (= who sees the client's ClientHello first) and how unmask is deployed (nginx native module / gateway container). The backend app is irrelevant.

● = node where unmask is installed  ★ = TLS termination (where the ClientHello is seen)

• native = nginx + unmask-plugin-nginx. The C module parses the ClientHello directly and computes JA4 (fastest, no subrequest, runs even on old distros like CentOS 6). Use this if your site is served by nginx and you want JA4.
• gateway container = the unmask.sh/unmask image: the official nginx image with the unmask module, plus the unmask daemon, in one container. It terminates TLS in front of any HTTP server (Apache, Node, another nginx, …) and computes JA4 the same way as native, so nothing changes on the server behind it. See Running unmask in containers and the install guide.
• Apache has no unmask module: for JA4 on an Apache site, put the gateway container in front of it (the recommended setup for Apache).
• Rows 3–4 need a front layer that forwards the client JA4 in a request header: GCP HTTPS LB through a custom request header (X-Client-JA4); Cloudflare through its own cf-ja4 header, once that is enabled (plan-dependent); AWS CloudFront / ALB only if your AWS setup can deliver the JA4 in a header. Without such a header, these rows get no JA4.
• In rows 3–4 the step is the same either way: pick your front CDN / LB under “trusted LB / CDN”. unmask then accepts the forwarded JA4 only from that CDN / LB's address ranges and ignores it from anywhere else; the header name comes with the preset (X-Client-JA4, or cf-ja4 for Cloudflare). No toggle and no manual wiring in nginx. See LB / CDN setup below.

HTTP/3 (QUIC) — the q prefix

The first letter of a JA4 fingerprint names the transport the ClientHello arrived over: t = TLS over TCP, q = QUIC. The nginx plugin computes JA4 for HTTP/3 the same way it does for TCP — when nginx is built with --with-http_v3_module and listens on a listen … quic port, the QUIC ClientHello passes through the same TLS-library callback the module already hooks, so no extra configuration is needed. Verified against both TLS backends nginx HTTP/3 builds commonly use: the OpenSSL 3.5+ native QUIC API and the quictls patch set.

TCP  (HTTP/1.1, HTTP/2)  →  t13i3514h2_bfa337485184_3ad6d895dd8c
QUIC (HTTP/3)            →  q13i0306h3_55b375c5d22e_1cecd519fee8

• The same client presents a different string over HTTP/3 than over TCP — the transport letter, the ALPN and the hello contents all change. When writing a custom JA4 rule for a site that serves HTTP/3, match both forms.
• unmask's cookie rebinding already treats an HTTP/2 ↔ HTTP/3 switch by the same visitor as normal — it does not count as a fingerprint mismatch.
• Behind a front CDN / LB that terminates HTTP/3 and forwards JA4, the forwarded value arrives with a q prefix; the trusted-LB gate passes it through unchanged.

What happens if JA4 cannot be captured?

Even with an empty JA4, unmask still works. Bot detection continues with the following signals:

• User-Agent classification — identifies known bots via a crawler / bot UA list of 600+ patterns
• Official IP ranges — registers official ranges (Googlebot / Bingbot etc.) on the bypass list to avoid ranking accidents. Vendors that publish ranges are verified by IP, not UA, so a spoofed UA is caught (crawlers without a range pass on UA)
• rate-limit — escalates to a challenge when the per-IP × path threshold is exceeded
• honeypot — bans clients that hit registered trap paths (e.g. CMS paths your site doesn't run)
• behavioral CAPTCHA — a human-likeness score across 5 axes: mouseTrail / scroll / keyboard etc.

Summary — which setup to choose

• Site served by nginx → nginx + unmask-plugin-nginx (native mode). nginx must be terminating TLS
• Apache or any other HTTP server → the gateway container in front of it. It terminates TLS and computes JA4 itself
• Have a front CDN / LB that terminates TLS → have it forward the client JA4 in a header → LB / CDN setup below

For install steps, see the install guide.

1. The big picture

[Client] ──TLS──▶ [LB] ──HTTP + X-Client-JA4──▶ [nginx + unmask]
                  ↑                ↑
        extract JA4 here    read it from the header

The LB / CDN's job:

• ① Compute the JA4 fingerprint from the client TLS handshake
• ② Put the value in a header of the request forwarded to the backend: X-Client-JA4 by convention (Cloudflare uses its own cf-ja4, which unmask's Cloudflare preset reads as is)
• ③ Any value of that header the client sent must be overridden at the LB stage (spoofing prevention)

There are two places to configure:

• §2 CDN / LB side — put the client JA4 into a request header (configured per LB)
• §3 unmask side — declare “trust that LB” in the admin UI. The default is no LB trusted (secure default), so it is explicitly opt-in

3. unmask-side setup

Once §2 has the front layer (LB / CDN) sending the JA4 header, the unmask side just decides which source to trust, in one place. The action is the same for native mode and the gateway container (admin → Settings → Network).

1. Under “trusted LB / CDN”, check the LB / CDN you use (GCP HTTPS LB / Cloudflare / AWS CloudFront, …)
2. For anything not listed (your own internal LB / ALB etc.), add its source CIDR + JA4 header under custom LB

On save, unmask adopts the JA4 header only when it comes from that source (the header name comes with the preset: X-Client-JA4, or cf-ja4 for Cloudflare); a direct visitor's spoofed header is dropped. Then sudo nginx -s reload (the gateway container reloads itself). Nothing is added to the nginx server block for JA4. You're done.

Under the hood (no operator action needed): native — the plugin computes JA4 from the ClientHello (works even with no front layer), and the rendered http.inc takes the trusted LB's header instead when one arrives; gateway container — the same, inside the container. No separate toggle.

4. Verify it works (admin dashboard)

1. After the reload, open the target site in a private browser window, so your browser holds no unmask pass cookie yet
2. In the unmask admin, open Bot hunt and find your own IP. The JA4 column shows the fingerprint unmask used for that request (it starts with t, or q over HTTP/3). unmask records a visit when it is challenged, which by default includes a first visit without the cookie
3. Or, on the unmask host: sudo unmask stats -kind ja4 -since 1h lists the fingerprints recorded in the last hour

Reading the JA4 column:

• Different fingerprints for different browsers / devices → the client JA4 is arriving ✓
• - (empty) → no JA4 reached unmask: the LB is not sending the header, or the LB / CDN is not selected in §3
• NOT_TRUSTED → a JA4 header arrived from an address outside the trusted ranges: check which LB / CDN is selected, and its CIDRs
• The same fingerprint on every request → it is the LB's own TLS connection to nginx, not the client's: the header is not being used

(none) in the verdict column, or in the Stats page's “JA4 verdict distribution” card, is not a failure: it means the fingerprint matched no verdict rule, which is what an ordinary browser does. It also covers requests with no JA4 at all, so judge by the JA4 column itself.

Native mode, request by request: http.inc defines a log format named unmask that records the JA4 unmask used and why (diag=ok; untrusted_lb_header = a JA4 header from outside the trusted ranges; trusted_no_header = a trusted LB sent none). Point an extra access log at it for a while, in the same block as your existing access_log line:

access_log /var/log/nginx/unmask-ja4.log unmask;   # then reload nginx

sudo tail -f /var/log/nginx/unmask-ja4.log         # each line: ... ja4=... v=... a=... diag=...