NAT Traversal and Tunnels

When a device has no reachable public entry point, FRP or Cloudflared can establish an outbound tunnel from the private network and carry external requests to the fn-knock gateway. A tunnel changes only the network topology. Once a request enters the gateway, it is still routed by Host or the compatibility path router and then evaluated against the access policy.

Under System settings → Mode, select Reverse proxy mode. Choose Subdomain mapping for a new deployment; choose the Path mode marked as not recommended only when preserving an existing single-domain path entry point.

macOS and Synology DSM 7 SPK provide in-app FRP and Cloudflared resources and process management. Windows x86_64 does not include these resources, so the System settings → FRP and System settings → Cloudflared steps on this page do not apply to Windows. If you run a tunnel client yourself on the same Windows host, it can use 127.0.0.1:7999 as its origin, but the administrator is responsible for that process's installation, credentials, and lifecycle.

Two Tunnel Options

Option	External resource	Best fit
FRP	A public server running frps and a remote port	You want full control over the public address, port, and transport configuration
Cloudflared	A Cloudflare Account, Zone, and API Token	You use Cloudflare and want Tunnel, wildcard DNS, and Ingress managed automatically

FRP and manual Cloudflared normally target the actual gateway entry point, commonly 127.0.0.1:7999. Managed Cloudflared uses a dedicated local entry that fn-knock configures automatically; no origin port needs to be entered.

Choose a Routing Method

Subdomain Mapping

The recommended request path is:

nas.example.com -> FRP / Cloudflared -> fn-knock -> Host nas.example.com -> fnOS

The tunnel must preserve the original Host and send both the auth Host and application Hosts to the same gateway. Managed Cloudflared automatically maintains the *.example.com Ingress and proxied CNAME. With FRP TCP forwarding, DNS and the remote port together direct traffic to frps.

Path Mode

The compatibility request path is:

https://example.com/alist -> Tunnel -> fn-knock -> Path /alist -> AList

It preserves legacy URLs, but an application may require prefix stripping, HTML rewriting, or a root-path mode. Do not default new services to path routing merely because they use a tunnel.

FRP

First download the resource under System settings → FRP, then open Tunnels → FRP. The proxy generated by default usually includes:

type = "tcp"
localIP = "127.0.0.1"
localPort = 7999
transport.proxyProtocolVersion = "v2"

PROXY Protocol v2 carries the public client address through to the gateway. If frps, the forwarding path, or a custom configuration does not support it, the gateway may see only the FRP node's address, distorting allowlist decisions and post-login IP authorization.

The page offers two editing methods:

• Form mode manages the server address, server port, Token, local port, and remote port. It updates only supported fields and preserves other valid TOML.
• Custom edits frpc.toml directly. frpc verify runs before saving; invalid syntax prevents saving and also prevents a reliable return to the form.

Back up the original text before switching editing methods on an existing custom configuration.

System settings → FRP labels the resource as Not downloaded, Outdated, or Downloaded (ready). Update an outdated resource before using it. The download is selected for the current platform and verified against a pinned official SHA-256 digest before extraction. Updating the resource does not automatically stop an older frpc process that is already running, avoiding an immediate tunnel interruption. That process may continue running, but an older instance that has stopped cannot start again until the resource is updated.

After the new resource is installed, Tunnels → FRP continues to flag instances that are still using the older executable. Stop and start those instances one at a time until the warning disappears, then verify the tunnel from an external network. Installing the resource and switching a running process are separate steps; a ready resource state does not mean that every instance has switched.

Cloudflared

When the resource page reports an update, fn-knock downloads to a temporary file, verifies the pinned digest, pauses a running managed process, backs up the executable and metadata, then resumes it after replacement. If the new binary cannot start, it restores the previous files and attempts to restart the old process. Expect a brief tunnel interruption and verify external access afterward.

First download the resource under System settings → Cloudflared, then enter the recommended Cloudflare Account API Token under Tunnels → Cloudflared. Choose the dedicated Tunnel, preview, and apply. fn-knock creates or attaches to the Tunnel, maintains wildcard DNS and Ingress, retrieves the Tunnel Token, and starts the process. Manual Tunnel Token mode remains available under the advanced section.

See Cloudflare Tunnel with cloudflared for managed setup, Token permissions, standard HTTPS URLs, Optimization Beta, and fallback behavior.

Access Policies and Real Client IPs

A tunnel does not replace fn-knock sign-in, allowlists, or credential scopes. In the Host editor, Require sign-in switches between public and login-first access. Strict-allowlist rules in legacy configurations still operate on source IPs. In Path mode, each mapping determines whether sign-in is required.

Authentication decisions use the client IP ultimately recognized by the gateway. Private, loopback, and link-local sources are marked local_exempt and bypass normal sign-in and strict-allowlist checks, making source-address forwarding part of the tunnel's security boundary:

• Keep the default PROXY Protocol v2 configuration for FRP whenever possible.
• Managed Cloudflared trusts CF-Connecting-IP only on its dedicated loopback entry. Do not apply the EdgeOne / ESA switch or trust visitor-supplied X-Forwarded-For.
• After startup, connect over a mobile network and verify in request logs that the client IP is the visitor's public address, not 127.0.0.1, a container address, or the tunnel node's address.

Process Supervision and Failure Diagnostics

FRP and Cloudflared processes managed by fn-knock show Stopped, Starting, Running, or Waiting to restart. If a process that should remain running exits unexpectedly, the system restarts it with progressive delays of roughly 1, 2, 5, 10, 30, 60, 120, and 300 seconds, with a small random jitter. The consecutive-failure count resets after about 5 minutes of stable runtime. A manual stop cancels pending retries.

While waiting to restart, the page shows the consecutive failure count, next retry time, and latest diagnosis. Logs preserve the PID, start and exit times, uptime, exit code or signal, failure summary, and recent stdout/stderr. Use these fields to distinguish Token, TLS, network, configuration, and binary failures. Redact Tokens, domains, public addresses, and server details before sharing logs.

After the fn-knock service itself restarts, it resumes tunnels saved as desired-running and can adopt a still-running process when it can be validated. This supervisor covers only built-in FRP / Cloudflared processes started by fn-knock. Administrators remain responsible for Windows and other external processes.

Platform Boundaries

• Tunnels use outbound connections and do not depend on fn-knock changing the host firewall, so Docker can use them as well.
• The runtime must have FRP / Cloudflared executables for the matching architecture. Check their readiness under System settings → FRP or System settings → Cloudflared.
• Synology DSM 7 SPK supports these built-in resources. Its admin entry remains available only through the DSM desktop CGI. fn-knock configures the managed Cloudflared entry automatically; FRP and self-managed tunnels use the actual gateway port.
• Native Intel and Apple Silicon macOS packages support these built-in resources. Downloads match the current Darwin architecture, while the admin panel remains local at 127.0.0.1:7991.
• Windows does not provide the built-in resources or their readiness status. A separately deployed tunnel process is not controlled by fn-knock's start, stop, or log management.
• Inside Docker, 127.0.0.1 means the current container. Use it when the fn-knock gateway and tunnel process are in the same container. For a separate tunnel container, use a service name or container-network address instead.
• Reverse proxy mode does not provide Smart Connect or protocol mappings. Design additional TCP / UDP services separately on the FRP or Cloudflare platform.
• When leaving reverse proxy mode, the system attempts to stop tunnel processes managed by fn-knock. Independently managed external processes remain outside its control.

Startup and Verification

1. Save the routing method, auth Host, and at least one application mapping.
2. Save and start FRP, or connect the Cloudflare API Token, preview, and apply the managed Cloudflared configuration.
3. Confirm that the runtime status is Connected. If it shows Waiting to restart, inspect the consecutive failure count, next retry time, and latest diagnosis, then check for Token, TLS, network, or port errors.
4. Access the auth Host and application Host from an external network.
5. Verify the Host, client IP, authorization type, and upstream Target in request logs.

For step-by-step instructions, see NAT Traversal with Subdomain Routing and Publish a Subdomain through a Tunnel without a Public IP.