fnOS Share Bypass

FNOS share bypass lets signed-out visitors open native /s/... share links after fnOS validates them. It creates a restricted, short-lived access session for only the current share; it does not expose the entire fnOS site, another Host, or any other path.

The feature works with Subdomain mode using direct public ingress, and with either subdomain mapping or path mode for NAT traversal. It is unavailable in Direct mode.

Requirements

1. External requests must first enter the fn-knock gateway.
2. The current request must match an HTTP route that actually points to fnOS.
3. The link must be a standard /s/{shareId} share entry generated by fnOS.
4. Enable FNOS share bypass under System settings → FNOS.

Keep an explicit application mapping to fnOS in the Host routes, for example:

fnos.example.com -> http://127.0.0.1:5666

The gateway probes the Target, Host, and route identity that the current request actually matched; it no longer guesses the backend from other mappings. Path mode does not require fnOS to be the default route, but /s/... and its resource paths must match the same fnOS route. Share bypass refuses to handle them if another path rule or the default route takes over.

For the related configuration, see Subdomain Routing or Path-based Reverse Proxy (Compatibility Mode).

Request Flow

Visitor opens /s/{shareId}
  -> fn-knock asks the fnOS upstream to validate the share
  -> Valid or password-protected share: issue a short-lived session scoped to /s
  -> Allow the share page, previews, thumbnails, downloads, and static assets
  -> Invalid, timed out, unrecognized, or out of scope: clear the session and return /

Validation checks more than the shape of the URL. fn-knock requests the same share entry from the fnOS upstream and parses its share data. The bypass starts only when the upstream confirms that the share is valid or that it is a legitimate password-protected link. If fn-knock cannot confirm it, access is denied by default.

Session Scope

A valid share sets the fn-knock-fnos-share-session Cookie with its path restricted to /s. The session record is bound to both one shareId and the fnOS backend matched by the current route, and allows only that share's required path families on that backend:

• /s/{shareId} and its subpaths
• /s/preview/{shareId}
• /s/thumb/{shareId}
• /s/static/..., /s/busstatic/..., and /s/download/...

Accessing a matching resource renews the session. If the Cookie is used for another share, another Host or routed backend, or outside the permitted paths, the gateway clears it. A share session cannot be reused across backends.

This session is separate from a normal fn-knock sign-in session. It cannot open the admin page, fnOS desktop, or another application.

Relationship to Other Access Methods

• A Host's Require sign-in setting and any existing strict allowlist rules still protect ordinary requests; only a valid share path enters the bypass.
• local_exempt is a separate, earlier source exception. The gateway already skips normal sign-in when it identifies a loopback, private, or link-local source. A LAN test therefore does not prove that share bypass works from the public internet.
• Skip Basic Auth injects credentials for the target service into upstream requests from a Host. It is not share authorization and does not automatically allow an arbitrary /s/... path.
• The share's own password, expiration, and revocation state are still controlled by fnOS. fn-knock does not replace those settings.

Defaults and UI Boundaries

The current page provides only an enable switch. The backend uses the following defaults, which cannot be changed in the regular UI:

Behavior	Default	Purpose
Upstream validation timeout	2500 ms	Wait for the fnOS share page to respond
Validation cache	30 s	Reduce repeated probes for the same share
Concurrent validation lock	5 s	Coalesce concurrent probes for the same share
Share session	300 s	Preserve continuous browsing; matching resources renew it

Clearly parsed valid and invalid results are cached. Uncertain results, such as an upstream timeout or a page that cannot be parsed, are not. Shortly after revoking a share, you might still see a cached result, but the share session remains restricted to the original share paths.

Platform Boundaries

• This is a gateway capability and does not depend on the host firewall. It works with supported Host/path gateways on the native fnOS FPK, Docker, OpenWrt, Linux, Synology DSM 7 SPK, and Windows.
• Direct mode only opens original ports after sign-in. It has no unified proxy path for share bypass to intercept, so this feature is unavailable there.
• In Docker, 127.0.0.1:5666 refers to the container itself. If fnOS runs on the host, change the Host Target to a host address reachable from the container.
• fn-knock can validate only the share-page structure returned by the current fnOS version. If the upstream is unreachable, responds too slowly, or changes its structure, fn-knock rejects the request instead of falling back to public access.
• This feature does not replace fnOS updates, permission settings, share revocation, or backups.

Enable and Verify

1. Confirm that the current mode is not Direct mode.
2. Keep an fnOS mapping in the Host routes; in path mode, confirm that /s/... and its resource paths actually match the fnOS Target.
3. From the fn-knock runtime environment, directly open the fnOS Target and a valid share.
4. Enable the switch under System settings → FNOS.
5. Create a real share link and open it from a private window on a mobile network, or from another signed-out device.
6. Test the details, previews, thumbnails, downloads, and the password-entry flow for a protected share.
7. Then open the fnOS root path and another application, confirming that they still require the normal sign-in or are denied.

Do not perform your only verification in a signed-in browser or on the LAN. A normal session and local_exempt can both hide whether share bypass is actually working.

Troubleshooting

1. You still reach the sign-in page or root entry: Confirm that the switch is enabled and that the system can identify the fnOS Target.
2. Host routing fails: Keep an explicit fnOS Host mapping, confirm that the current Host actually matches it, and check that its Target is reachable.
3. Path mode fails: Check whether another path rule or the default route captures /s/.... Adjust route order or match scope, then synchronize the routes.
4. The entry opens but its resources fail: Check whether /s/preview, /s/thumb, static asset, and download requests all pass through the same gateway.
5. A recent share-state change still shows the old result: Wait about 30 seconds for the cache to expire, then retry.
6. Validation sometimes times out: Check fnOS load, the Target address, and any intermediate proxy before changing the entire Host to public access.

For runtime-mode steps, see NAT Traversal with Subdomain Routing and Public IP Access with Subdomain Routing. See System Settings and Maintenance for global entry points and NAT Traversal and Tunnels for the tunnel path.