WIUNIX ACADEMY
Set up Cloudflare Tunnel and Access for a private web app on Ubuntu and Debian
Page 4 of 5. Review the earlier steps and prerequisites before continuing.
YOUR SYSTEM. YOUR STEPS.
Where are you working?
Choose your OS and version. The prerequisites, commands and troubleshooting follow your environment.
USE YOUR OWN VALUES
Configure this tutorial
Set the example values for your environment; related explanations and copy panels update together. Never enter passwords, private keys or tokens. Values stay in this tab and are not sent to the server or share links. Check actual DNS, certificates and network policy before running commands.
Different IP addresses, domains or ports? Open the settings below, change the values and select “Apply to tutorial”, then copy the updated commands.
Set values for my environment8 editable values
LET’S BUILD
Observe the service without publishing metrics
On the connector host, readiness and metrics remain local. Monitor a protected synthetic receiver test as well as connector connection count, errors and origin availability. Never create a public metrics route. A single connector and one origin are single points of failure; multiple edge connections do not make this host redundant. Before adding another replica, it must reach the same application and enforce the same policy; its loopback refers to that second host, not this one.
Run at the location stated in this step
curl --fail --silent --show-error --noproxy '*' http://127.0.0.1:20241/metrics
sudo ss -lntp 'sport = :20241'
Metrics are readable locally, bound exclusively to 127.0.0.1:20241; no metrics route exists.
Diagnose the failing boundary
Work from local receiver → connector → published route → Access identity. Keep the route closed if a security check fails. Do not fix a502 by removing Access, or fix a denied user by adding Everyone. The following diagnostic panels are read-only; their outputs may contain private operational details.
502 while the connector is healthy
On the connector host compare the local receiver body/listener with the dashboard Service URL. Connection refused usually means wrong port/address or a stopped origin. A container’s loopback is not the host’s loopback: this guide runs both processes as host services. For a real HTTPS origin use a trusted certificate and matching originServerName/CA configuration; leave certificate verification enabled. The loopback HTTP marker does not teach noTLSVerify. Review the official HTTPS-origin guide for redirects/Host-header requirements before replacing this demo.
sudo systemctl is-active academy-origin.service
curl --fail --silent --show-error --noproxy '*' http://127.0.0.1:8080/health.txt
sudo ss -lntp 'sport = :8080'
1033 or disconnected connector
Inspect DNS, time and local connector logs. Error1033 means no healthy connector available for the route, not an origin502. Use the current vendor endpoint list with the network owner. UDP netcat success alone does not validate QUIC. Do not open inbound ports or disable the firewall. If only UDP is blocked, auto transport may use HTTP/2 over TCP7844; if both are blocked the tunnel cannot work.
getent ahostsv4 region1.v2.argotunnel.com
dig SRV _v2-origintunneld._tcp.argotunnel.com
timedatectl status
sudo journalctl -u cloudflared-academy.service --since "10 minutes ago" --no-pager
Login loops, denied identities or an exposed marker
Use a clean browser profile and inspect the saved hostname, application AUD/team, policy identity/group and Access decision logs. A valid login does not guarantee membership. For JWT failures check time and HTTPS reachability to the team endpoint, without logging cookies/tokens. A stale session can confuse comparisons. If a signed-out client receives the marker, remove the published route first; do not merely hide the login link. Keep the origin loopback-only and Access application present during repair.
curl --silent --show-error --max-time 20 --dump-header - 'https://app.example.com/health.txt'
timedatectl status
Credential or service startup failure
Check file metadata without displaying its content and inspect the dedicated unit’s status. Confirm LoadCredential points to the selected token file and ExecStart uses the credential directory, not the root-only source path. Do not grant world-read permission or move the token into the unit. On unsupported/modified systemd environments, stop and adapt through a reviewed secret-management design rather than weakening permissions.
sudo test -s '/etc/cloudflared-academy/token'
sudo stat -c '%a %U %G' '/etc/cloudflared-academy/token'
sudo systemctl status cloudflared-academy.service --no-pager