Skip to main content
Version: 4.6.1-saas

Cloudflare Agent

Overview​

The NetFUNNEL Cloudflare agent is a NetFUNNEL-dedicated client that communicates with the NetFUNNEL server from Cloudflare Workers.

Worker Environment Setup​

Setting up the Cloudflare Worker environment with reference to Cloudflare's official documentation should be your first step.

Review Cloudflare's official documentation on setting up a Worker project, then configure the Worker environment according to the guide.

Worker CLI guide: CLI

Create and Configure Worker​

Create Worker​

  • Go to [Workers and Pages].
  • Under Workers, click [Create].
  • Click [Hello world].
  • Deploy to add.

Apply Agent to Worker​

import handleEvent from './netfunnel-cloudflare-agent.js'
export default {
  async fetch(request, env, ctx) {
    return await handleEvent(request, env, ctx);
  },
};
  • Click the [Deploy] button at the top right to deploy the Worker.

Worker Configuration​

  • Select the Worker you created and go to the [Settings] menu.
  • Under Domains and routes, click [+ Add].
  • Click [Route].
  • In [Zone], select the domain and enter in [Route] the domain where the Worker will run. (Add /* at the end so the Worker runs on subpages as well.)
  • Select [Fail open].
  • Click [Add route].
  • Add the CLIENT_ID variable.
info

You can find CLIENT_ID in the NetFUNNEL console.

  • After adding the variable, click [Deploy].

Domain Configuration​

Configure the domain set in section 3.2 as a CNAME so that requests to that path are handled by the Worker.

warning

You must set the Proxy type.

Additional Features​

Good Bot Exception​

You can exclude specific User-Agent values from agent behavior through Worker configuration.

Worker Configuration​

  • In [Workers and Pages], select the Worker with the agent applied and go to the [Settings] tab.
  • Add environment variables under Variables and secrets as shown in the table below.
info

Example of excluding Google, Microsoft, Yahoo, Apple, and Facebook bots.

TypeNameValue
TextGOOD_BOTSGooglebot, Bingbot, Slurp, Applebot, facebookexternalhit
  • After adding, click [Deploy].

Entry Key Auto-Return​

The NetFUNNEL Cloudflare agent automatically returns the NetFUNNEL key after entry so the next user in line can enter. Use this feature when you want the key to be returned at the segment timeout instead of returning it immediately.

Worker Configuration​

  • In [Workers and Pages], select the Worker with the agent applied and go to the [Settings] tab.
  • Add the environment variable RETURN_KEY (value: true) under Variables and secrets.
info

When set to true (default), the agent automatically returns the NetFUNNEL key when the user enters after waiting. When set to false, the key is returned at the timeout configured in the segment.

  • After adding, click [Deploy].

Change Waiting Room Domain​

The domain of the NetFUNNEL waiting room page is agent-lib.stclab.com. To change it to your service domain, contact the NetFUNNEL service team with your desired domain and update the Worker configuration.

Worker Configuration​

  • In [Workers and Pages], select the Worker with the agent applied and go to the [Settings] tab.
  • Add environment variables under Variables and secrets as shown in the table below.
TypeNameValue
TextVWR_PAGE_DOMAINhttp(s)://{CNAME_DOMAIN} e.g. https://wait.stclab.com
  • After adding, click [Deploy].

Keys issued by the NetFUNNEL server are stored in cookies based on the current page domain. To share keys across different subdomains, configure the main domain to be stored in the cookie.

info

Set to .stclab.com so that cookies are shared across pages with different subdomains, such as develop.stclab.com and staging.stclab.com.

Worker Configuration​

  • In [Workers and Pages], select the Worker with the agent applied and go to the [Settings] tab.
  • Add environment variables under Variables and secrets as shown in the table below.
TypeNameValue
TextCOOKIE_DOMAIN.{MAIN_DOMAIN} e.g. .stclab.com
  • After adding, click [Deploy].