OpenFlare/docs/en/guide/tunnel-usage.md

Tunnel & Intranet Penetration

You will learn: The design principles of OpenFlare intranet penetration tunnels, core concepts (Relay nodes and Tunnel clients), and how to safely and stably publish your intranet development environment or private cloud services to a public domain name from scratch.

In many practical development and operations scenarios, our origin servers are deployed in local LANs, local development machines, or heavily guarded private VPCs, having no public IP address and no port mapping (NAT) configured on border firewalls or routers.

OpenFlare provides an end-to-end solution based on reverse relay penetration tunnels. You only need to initiate a secure outbound connection from your intranet environment to the public relay node, without configuring any inbound ports, to smoothly route public web traffic into your intranet origin. At the same time, you benefit from automatic TLS certificate hosting and WAF security protection provided by the gateway.

---

Core Concepts

Before using the intranet penetration features, you need to familiarize yourself with the following components and core concepts:

Concept	Description	Component / Operation
Relay Node (Relay)	Traffic relay services deployed at the public edge, responsible for listening to intranet client persistent connections, acting as the transit bridge between the gateway Agent (OpenResty) and internal traffic.	Node of type tunnel_relay running the openflare-relay daemon
Penetration Tunnel (Tunnel)	Logical penetration client instances having a globally unique ID and secure authentication token, used to identify a specific intranet environment.	Globally unique ID generated by Server tunnel_id (format: tun-<32hex>)
Tunnel Client (Client)	A lightweight controller running in the intranet environment, automatically managing the underlying frpc tunnel subprocesses according to the configuration dispatched by the Server.	The openflared container or independent binary process deployed in the intranet
Tunnel Upstream (Tunnel Upstream)	A special upstream type in the website configuration. When this type is selected, the gateway forwards public traffic to the Vhost port of the local relay node, eventually reaching the intranet origin.	Upstream of type tunnel configured in the website details

---

Recommended Operation Sequence

To publish an intranet service to the public internet, we recommend doing so in the following order:

1. Register and deploy at least one public Relay Node (Relay) and keep it online.
2. Create a Penetration Tunnel (Tunnel) in the management console and copy its dedicated Token.
3. Deploy and start the Tunnel Client (OpenFlared) on your intranet server.
4. Confirm that the status of the tunnel in the management console shows as "Online".
5. Add a website configuration, selecting Intranet Penetration as the upstream type, binding it to the corresponding tunnel, and entering the intranet port (e.g., 127.0.0.1:8080).
6. Publish and activate the new version.
7. Access via the public domain to verify that the intranet penetration link is established.

---

Detailed Configuration Steps

Step 1: Prepare the Relay Node (Relay)

Intranet traffic is routed through public relay nodes. Before starting, ensure you have a public relay server available.

1. Log into the management console and go to "Node Management".

2. Add a new node, selecting Relay Node (tunnel_relay) as the Node Type.

3. Save and copy the node-specific agent_token.

4. Start the openflare-relay process on your public server. You can run it quickly using Docker:

   docker run -d --name openflare-relay --restart unless-stopped \
     -p 7000:7000 \
     -e OPENFLARE_SERVER_URL=http://<YOUR_SERVER_PUBLIC_IP>:3000 \
     -e OPENFLARE_AGENT_TOKEN=<YOUR_COPIED_AGENT_TOKEN> \
     -v openflare-relay-data:/var/lib/openflare-relay \
     ghcr.io/rain-kl/openflare-relay:latest
   

   Important

   Make sure to allow port 7000 (the control port for frpc client connections) in your cloud provider's security group. If your Server and Relay are deployed on the same machine, OPENFLARE_SERVER_URL should point to the Server's public or internal IP.

Step 2: Create a Penetration Tunnel in the Management Console

1. Navigate to the "Intranet Penetration" section in the side navigation bar.
2. Click the "Create Tunnel" button and enter:
   • Tunnel Name: Describes the intranet environment, e.g., home-lab or office-dev.
   • Description: Optional, describes the purpose of this tunnel.
3. Click save, and the system will automatically generate a globally unique ID and a dedicated tunnel_token (e.g., tun-xxxx...).
4. Copy the Client Deployment Command generated in the popup window, which will be used in the next step.

Step 3: Deploy the Intranet Client (OpenFlared)

Return to your intranet server and execute the copied deployment command to run the client.

Option A: Deploy with Docker (Highly Recommended)

The official openflared image embeds the master daemon and frpc runtime, working out-of-the-box with no extra dependencies:

docker run -d --name openflared --restart unless-stopped \
  -e OPENFLARE_SERVER_URL=http://<YOUR_SERVER_PUBLIC_IP>:3000 \
  -e OPENFLARE_TUNNEL_TOKEN=<YOUR_COPIED_TUNNEL_TOKEN> \
  -v openflared-data:/app/data \
  ghcr.io/rain-kl/openflared:latest

Option B: Host Binary Manual Execution

If you cannot use Docker, you can download or compile the flared binary:

1. Create a flared.json configuration file in the same directory as the executable on your intranet machine:

   {
     "server_url": "http://<YOUR_SERVER_PUBLIC_IP>:3000",
     "tunnel_token": "<YOUR_COPIED_TUNNEL_TOKEN>",
     "frpc_path": "/usr/local/bin/frpc",
     "data_dir": "./data"
   }
   

2. Execute the startup command:

   ./flared -config ./flared.json
   

Verify Online Status

Once started successfully, the intranet client will send heartbeats through outbound networks to synchronize configurations. At this point:

1. Refresh the "Intranet Penetration" list in the management console; the tunnel status indicator should turn green and show "Online".
2. Click tunnel details to view which public Relays the intranet client is currently connected to.

Step 4: Create a Website and Bind the Tunnel Upstream

Now you can configure public reverse proxy and domain routing for your intranet service.

1. Go to the "Website Configuration" page and click "Create Website".
2. Enter the Domain Name required to access the service publicly, e.g., nas.example.com.
3. Critical Configuration: In the "Upstream Configuration" section, switch the Upstream Type from "Direct" to "Intranet Penetration".
4. In the dropdown list, select your newly deployed Intranet Tunnel (e.g., home-lab).
5. Enter the Intranet Target Address (the local address and port reachable by the intranet client, e.g., 127.0.0.1:8080) and select the Intranet Protocol (usually http).
6. Configure other standard website settings (such as TLS certificates) and click save.

Step 5: Publish & Activate

To allow the gateway's OpenResty instance to match and route domain traffic correctly, we need to publish a new configuration version.

1. Click "Preview Config" in the top right corner of the navigation bar to verify the generated configurations.
2. In the popup window, click "Publish & Activate".
3. Now, the public edge Agent pulls the latest routing, forwarding requests for nas.example.com to the loopback virtual host port of openflare-relay (frps).
4. The intranet client openflared (frpc) receives the relayed packets, securely hands them over to the local 127.0.0.1:8080 service, and returns responses back through the tunnel.
5. Access nas.example.com in your browser to confirm that the intranet service displays successfully!

---

Advanced Application Scenarios

1. Single-Tunnel Multi-Service Multiplexing (Multi-Port Mapping)

You do not need to deploy an openflared container for every single internal service.

If you want to map multiple different services in the same intranet environment (e.g., 127.0.0.1:80 for a blog, 127.0.0.1:8080 for an API, and 192.168.1.120:9000 for a local network drive):

1. Keep this single openflared client online.
2. Create three independent website configurations in the management console (binding their respective public domains).
3. Set the Upstream Type to the same intranet tunnel for all three website configurations.
4. Fill in their respective "Intranet Target Addresses" (e.g., 127.0.0.1:80, 127.0.0.1:8080, and 192.168.1.120:9000).
5. Publish and activate the new version to achieve single-tunnel multi-service multiplexing.

2. Seamless Integration with Gateway Security Features

Since all public traffic enters the public Agent node first, completing the HTTPS/TLS handshake and WAF filtering before traveling through the secure tunnel:

Your intranet services naturally benefit from the following advanced features without any code changes:

• One-Click HTTPS: Select or issue SSL certificates directly in the management console, encrypting transmission end-to-end.
• Global/Custom WAF Protections: Enables SQL injection blocking, XSS prevention, and regional IP filtering.
• Human-Machine Challenge (PoW CC): Instantly blocks brute-force CC API attacks targeting your intranet services.

---

Common Troubleshooting

1. Tunnel Shows as "Offline" in the Management Console

• Check the Token: Check if the tunnel_token configured in flared logs or environment variables matches the one generated in the management console.
• Check Outbound Connectivity: The intranet server must be able to make outbound requests to the Server address. Ensure the control plane firewall is not blocking HTTP requests from the client.
• Relay Firewall Port Closed: Check if port 7000 (or your custom bindPort) on the public Relay node has been allowed in the public security groups.

2. Accessing the Public Domain Returns 502 Bad Gateway / 504 Gateway Timeout

• Intranet Service Not Running: Verify that the service corresponding to the intranet target address is running and listening on the intranet server.
• Target Address Unreachable: If the intranet address is set to 127.0.0.1:8080, ensure the service is running on the exact same host as openflared; if set to a LAN IP 192.168.x.x, test connectivity to that IP inside the openflared container.
• Check Client Application Logs: View the "Apply Logs" in the management console or inspect local flared logs for any LastError. When frpc fails to connect to the intranet port, it reports the failure details to the Server.

3. Multiple Relays Network Instability or Retry Failures

• When the control plane associates multiple Relay nodes, openflared spawns independent frpc daemon processes for each Relay and pulls topology states periodically at sync_interval (default 30s) configured in flared.json.
• If a Relay drops frequently due to network jitter, the system triggers the backoff retry mechanism automatically. You can see frpc process missing, starting logs on the host, which is a normal process self-healing action and will recover within 5-10 seconds after network recovery.