A named tunnel is a persistent Cloudflare object: it has a UUID, a name, and a credential file. You create it once; cloudflared uses the credential file to authenticate on startup. Two creation paths are available.

Option A: CLI (recommended)

# Inside the operator console
cloudflared tunnel login
# Opens a browser window (or prints a URL to open). Authenticate with your
# Cloudflare account. A certificate is written to ~/.cloudflared/cert.pem.

cloudflared tunnel create ep-<student>
# Replace <student> with your slot name, e.g.: cloudflared tunnel create ep-alpha

Expected output:

Created tunnel ep-alpha with id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Tunnel credentials written to /root/.cloudflared/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json.

Note the tunnel ID (UUID). You will use it in Step 2.

# Confirm the tunnel is registered
cloudflared tunnel list

Option B: dashboard

1. Open dash.cloudflare.com and select your account.
2. Go to Zero Trust > Networks > Tunnels.
3. Click Add a tunnel, select Cloudflared, click Next.
4. Name the tunnel ep-<student>. Click Save tunnel.
5. On the next screen, ignore the auto-install instructions. Click Next, then the Overview tab. Note the Tunnel ID (UUID).
6. On the Connectors tab, click the three-dot menu, then Download credentials JSON. Save the file as <tunnel-id>.json.
7. Copy it into the operator console:

# From your laptop (replace TUNNEL_ID and the path to your download)
TUNNEL_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
docker cp ~/Downloads/${TUNNEL_ID}.json ep-devcontainer:/root/.cloudflared/${TUNNEL_ID}.json

Verify the credential file is present:

ls ~/.cloudflared/
# Expected: cert.pem  <tunnel-id>.json

Create the tunnel configuration file in the operator console. The ingress rule maps your public hostname to the local nginx placeholder on port 8787.

# Replace TUNNEL_ID and STUDENT with your values
TUNNEL_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
STUDENT="alpha"

mkdir -p /etc/cloudflared

cat > /etc/cloudflared/config.yml << EOF
tunnel: ${TUNNEL_ID}
credentials-file: /root/.cloudflared/${TUNNEL_ID}.json

ingress:
  - hostname: api.${STUDENT}.eplabs.cloud
    service: http://localhost:8787
  - service: http_status:404
EOF

Verify it:

cat /etc/cloudflared/config.yml

Expected output:

tunnel: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
credentials-file: /root/.cloudflared/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.json

ingress:
  - hostname: api.alpha.eplabs.cloud
    service: http://localhost:8787
  - service: http_status:404

The service: http_status:404 catch-all is required by cloudflared. Any request that does not match an explicit hostname rule returns a 404 from the tunnel itself.

Route the hostname to the tunnel. cloudflared can create the DNS record directly if your account certificate is present (from the tunnel login step):

# Inside the operator console
TUNNEL_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
STUDENT="alpha"

cloudflared tunnel route dns ${TUNNEL_ID} api.${STUDENT}.eplabs.cloud

Expected output:

2024/xx/xx xx:xx:xx INF Added CNAME api.alpha.eplabs.cloud which will route to this tunnel tunnelID=xxxxxxxx-...

Verify the record was created:

dig CNAME api.${STUDENT}.eplabs.cloud +short
# Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.cfargotunnel.com.

DNS propagation for Cloudflare-managed zones is typically under 30 seconds.

If cloudflared tunnel route dns fails because the operator console account cert is not present (option B tunnel creation), add the CNAME manually via the Cloudflare dashboard: DNS > Records > Add record. Type: CNAME, name: api.<student>, target: <tunnel-id>.cfargotunnel.com, proxy: on (orange cloud).

The tunnel maps api.<student>.eplabs.cloud to http://localhost:8787. Start a minimal nginx response on that port to confirm the end-to-end path before adding the Worker in Lab 07.

nginx is installed in the operator console. Configure a minimal server block:

# Inside the operator console
cat > /tmp/nginx-test.conf << 'EOF'
worker_processes 1;
daemon off;

events { worker_connections 16; }

http {
  server {
    listen 8787;
    location / {
      default_type text/plain;
      return 200 "EPL engagement platform: tunnel ok\n";
    }
    location /health {
      default_type application/json;
      return 200 '{"status":"ok","origin":"operator-console"}';
    }
  }
}
EOF

nginx -c /tmp/nginx-test.conf &
NGINX_PID=$!
echo "nginx PID: $NGINX_PID"

Verify nginx is listening:

curl -s http://localhost:8787/
# Expected:  EPL engagement platform: tunnel ok

curl -s http://localhost:8787/health
# Expected:  {"status":"ok","origin":"operator-console"}

Persistence note. The nginx config is written to /tmp/nginx-test.conf, which does not survive a container restart. If you restart the operator console and need to re-run validation, either run the nginx command above again or move the config to /etc/nginx/conf.d/tunnel-test.conf (a location that persists). For the workshop session, /tmp is sufficient.

# Inside the operator console
cloudflared tunnel --config /etc/cloudflared/config.yml run &
CLOUDFLARED_PID=$!
echo "cloudflared PID: $CLOUDFLARED_PID"

Watch the startup output. After a few seconds you should see:

...INF Connection ... registered connIndex=0 ...
...INF Connection ... registered connIndex=1 ...
...INF Registered tunnel connection ...

At least two connections to the Cloudflare edge should register. Four connections are normal and indicate full redundancy.

Check the tunnel status from a second terminal:

cloudflared tunnel --config /etc/cloudflared/config.yml info

Expected output (abbreviated):

Tunnel ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status:    HEALTHY
Connections: [4]

From outside the operator console, curl the public URL. You can run this from your laptop or from a second terminal in the operator console:

# Replace with your student subdomain
curl -sv https://api.${STUDENT}.eplabs.cloud/
# Expected HTTP status: 200
# Expected body: EPL engagement platform: tunnel ok

Also verify the health endpoint:

curl -s https://api.${STUDENT}.eplabs.cloud/health
# Expected: {"status":"ok","origin":"operator-console"}

If you get a 525 SSL Handshake Error or a Cloudflare error page, the tunnel connection may still be establishing. Wait 10 to 15 seconds and retry.

If you get a 404 from cloudflared’s catch-all rule, the hostname in the ingress rule does not match the URL. Double-check the config file and confirm the CNAME record was created in Step 3.

Running cloudflared in the background with & is fine for the lab session. To keep the tunnel running after an operator console restart, you have two options.

Option A: systemd unit (recommended for local Dev Container)

The operator console runs Debian with systemd available. Use cloudflared service install to write and enable a systemd unit:

# cloudflared service install writes /etc/systemd/system/cloudflared.service
# and enables it. It reads the config from /etc/cloudflared/config.yml.
cloudflared service install

# Start the service
systemctl start cloudflared
systemctl status cloudflared

Expected status output:

● cloudflared.service - cloudflared
   Loaded: loaded (/etc/systemd/system/cloudflared.service; enabled)
   Active: active (running) since ...

Stop the foreground process if it is still running before enabling the service:

kill $CLOUDFLARED_PID 2>/dev/null || true
systemctl start cloudflared

Option B: re-start on session open (Codespace or ephemeral container)

Codespaces restart between sessions. The simplest approach is a one-line restart in .devcontainer/post-start.sh:

# .devcontainer/post-start.sh (add this line)
cloudflared tunnel --config /etc/cloudflared/config.yml run >> /var/log/cloudflared.log 2>&1 &

This keeps the credential file and config on the persistent /root/.cloudflared/ volume and relaunches cloudflared on every Codespace resume.

Verify the tunnel is still connected after whichever path you chose:

cloudflared tunnel --config /etc/cloudflared/config.yml info

# From the operator console, run from the course root
MANIFEST="labs/output/build-manifest.json"
CF_VERSION=$(cloudflared --version 2>&1 | awk '{print $3}' | head -1)

# If the manifest does not exist yet, create a minimal stub
if [ ! -f "$MANIFEST" ]; then
  mkdir -p labs/output
  printf '{"role":"engagement-platform","openwrt_version":"23.05.3","created_at":"%s"}\n' \
    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$MANIFEST"
fi

UPDATED=$(jq --arg v "$CF_VERSION" '. + {cloudflared_version: $v}' "$MANIFEST")
printf '%s\n' "$UPDATED" > "$MANIFEST"

echo "cloudflared_version recorded: $CF_VERSION"
cat "$MANIFEST"

The manifest now contains a cloudflared_version field. The validate script checks for this field.