As with recent changes with Linux and MacOS, use --token-file instead of --token when installing the service for Windows.
The secret token was viewable by an unprivileged user by looking at the registry entry HKLM\\SYSTEM\\CurrentControlSet\\Services\\Cloudflared\\ImagePath, which stores the full command-line invocation of cloudflared (complete with --token ).
We fix this by storing the token in a file and restricting access to it.
The canonical way of protecting a secret token on Windows is to use the CryptProtectData and CryptUnprotectData functions in dpapi.h, which encrypt/unencrypt data using an OS-managed secret key. See here:
https://learn.microsoft.com/en-us/windows/win32/api/dpapi/
While we could use the DPAPI to encrypt/decrypt the token before writing it out to disk, this has two problems:
1) We would break existing Windows installs using --token-file with an unencrypted token file
2) We would introduce an inconsistency between how --token-file works on Linux/MacOS and Windows
Because of this, we keep things consistent and just add logic to cloudflared to protect the token file by modifying the permissions of the token file.
Windows's permission model differs completely from Linux and MacOS, so a Windows-specific function is used to restrict the token file's permissions. We strip ACLs from the file such that it's only readable by SYSTEM and Administrators.
Also done by this MR:
* Improve "service install --help" output on Windows to be in-line with Linux and MacOS
* Change uses of path.Join that work with file paths to be filepath.Join instead, which will use the correct platform-specific path separator (\\ on windows or / on \*nix) instead of only forward slashes
* Pull out constant string in MacOS service
Use curves when running pre-checks. Although it is not something critical, pre-checks should closely match the current cloudflared behavior when trying to establish connections to the edge. Adding curves here matches the current behavor.
* Refactor directory-related functions in macos_service.go to pull out common logic
* Use --token-file instead of --token when installing cloudflared with a token on MacOS such that the secret token will not show up in the output of "ps aux" (or similar)
* Improve the "service install" help text on MacOS to distinguish between the "service install " and "service install \<token\>" cases
When installed with a token, e.g.,
$ cloudflared service install \<token\>
cloudflared will set itself up to be run by the init system using the --token argument. This results in tokens being visible in the output of ps aux by unprivileged users. Change this such that this installation method instead puts the token in a file with mode 600 in /etc/cloudflared and uses the --token-file flag instead.
Adding a test that tries to exercise the race condition for the websocket path. The sequence is as follows:
1. The test starts by writing the payload to the mock server
2. Then, it closes the write side of the connection.
3. It waits for 3 seconds to make the race window explicit: the bug in cloudflared would have closed the connection and we would not be able to read.
4. Read the message.
With the fix applied, we should be able to read the full message.
systemctl list-units exits 0 whether or not any pattern matches, so the
filter was a no-op and every unit was always treated as installed.
Detect installed units by checking for the unit file on disk instead.
Generate a clean init script at /etc/init.d/cloudflared backed by
OpenRC's supervise-daemon supervisor, plus a companion
/etc/conf.d/cloudflared for operator overrides.
As it stands, cloudflared prechecks are not taking the `protocol` flag into consideration and is instead falling back to the default protocol, which is QUIC. Prechecks should report the protocol cloudflared will use, not the default protocol.
Fixing some bugs with DNS targets. Most importantly, these changes also fix some wrong assumptionsmade when trying to add support for the `--edge` flag:
1. Removes `StaticEdgeDNSResolver` in favor `resolveStaticEdge`. Since --edge does not imply resolving DNS, this fixes that assumption.
2. Adds EdgeAddrs, which allows us to skip DNS probes when set. This fixes the targets in the DNS rows.
3. Added a new `ResolvedTarget` struct, which joins addresses with the respective DNS results. This avoids the brittle logic we had before, where we assumed there were always two groups (one for each region) when running probes. So this not only makes the code more extensible in case we want to add more regions in the future but also adds support for multiple targets supplied via `--edge`.
4. Changes the existing nomenclature, going from calling things `region` to `target`. The term `region` works when resolving production regions (region1 and region2), but becomes misleading when we add the logic for `--edge`.
The end result of these changes is that we now see the correct addresses when you supply targets via `--edge`, while also making the code a bit clearer.
Instead of having the --precheck flag in cloudflared, we allow controlling prechecks via a DNS flag, so we can short-circuit this behavior in case anything goes wrong. Although we don't expect pre-checks to add that much traffic, we should still guarantee that we can stop pre-checks in case something goes wrong.
Introduce a new crypto/ package as the single source of truth for TLS
curve preferences used on every edge-facing connection, and adopt
X25519MLKEM768 as the primary post-quantum key exchange for both QUIC
and HTTP/2:
PQ Prefer (default): X25519MLKEM768, P256Kyber768Draft00, CurveP256
PQ Strict (--post-quantum): X25519MLKEM768, P256Kyber768Draft00
The curve list is identical under FIPS and non-FIPS builds, so
crypto.GetCurvePreferences takes only a features.PostQuantumMode and
returns a fresh slice on every call.
HTTP/2 now applies these curve preferences the same way QUIC does. The
previous PostQuantumStrict rejection in serveHTTP2 and the forced
QUIC-only selection in NewProtocolSelector are removed since both
transports support the same post-quantum curves; the needPQ parameter
is dropped from NewProtocolSelector accordingly.
Also fix a shared tls.Config race: both the QUIC and HTTP/2 paths now
Clone() the per-protocol entry from TunnelConfig.EdgeTLSConfigs before
mutating CurvePreferences instead of writing through the shared map
entry.
Legacy Kyber draft curve X25519Kyber768Draft00
and the unused removeDuplicates helper are removed along with the old
supervisor/pqtunnels.go / _test.go files.
AGENTS.md is updated with guidance on the new crypto/ package, the
cfdcrypto import alias, the tls.Config cloning rule, and the lint
workflow implications of .golangci.yaml's whole-files: true setting.
Final run method, which runs cloudlflared pre-checks for both the normal startup procedure, as well as cloudflared diag.
For cloudflared diag, this produces a new json output to which is added to the final zip file.
Also added in a new flag to prevent this from running all the time, at least for now until we are 100% sure this works as intended. We will later remove this flag, only leaving in `--no-prechecks`, so this runs by default for everyone using cloudflared.
Tested pre-checks locally with origintunneld. The results show all pre-checks succeeding. In this case, it ran with only 1 region, since locally we run it with `--edge origintunneld1:7844`.
{width=900 height=217}
Check / check (1.22.x, macos-latest) (push) Has been cancelled
Check / check (1.22.x, ubuntu-latest) (push) Has been cancelled
Check / check (1.22.x, windows-latest) (push) Has been cancelled
Semgrep config / semgrep/ci (push) Has been cancelled
Fixing missing TLS settings. While developing the pre-check probes, I forgot to add the certificate settings, which are essential for establishing a connection to origintunneld. I discovered this while testing cloudflared locally.
Check / check (1.22.x, macos-latest) (push) Has been cancelled
Check / check (1.22.x, ubuntu-latest) (push) Has been cancelled
Check / check (1.22.x, windows-latest) (push) Has been cancelled
Semgrep config / semgrep/ci (push) Has been cancelled
Fixing warnings in cloudflared log collector.
This attempts to fix errors like the ones shown below:
```
diagnostic/diagnostic.go:132:23: Error return value of `logHandle.Close` is not checked (errcheck)
defer logHandle.Close()
diagnostic/diagnostic.go:134:26: G303: File creation in shared tmp directory without using ioutil.Tempfile (gosec)
outputLogHandle, err := os.Create(filepath.Join(os.TempDir(), logFilename))
```
Check / check (1.22.x, macos-latest) (push) Has been cancelled
Check / check (1.22.x, ubuntu-latest) (push) Has been cancelled
Check / check (1.22.x, windows-latest) (push) Has been cancelled
Semgrep config / semgrep/ci (push) Has been cancelled
Replace the lock file mechanism with PID+start-time based stale
detection so that no cleanup is required on process death.
When both org and app token locks were held, the first signal handler
to call os.Exit() would kill the process before the second handler
could delete its lock file. The orphaned lock file then caused the
next invocation to wait ~128 seconds in an exponential backoff loop
before forcibly deleting it. The same issue occurred on SIGKILL, OOM,
or any non-signal death.
Lock files now contain the holder's PID and process start time as
JSON. On acquisition, if a lock file already exists, the recorded
process is checked for liveness via gopsutil. Stale locks are
reclaimed immediately with no backoff. Atomic O_CREATE|O_EXCL
prevents races between concurrent acquirers.
Also adds a companion .url file so processes waiting on an active
lock can print the auth URL for the user.
This PR implements all the dialers and resolvers needed to make pre-checks happen. So this task focuses on the following:
1. Implement the DNS probe: call DNSResolver.Resolve(region)
2. Implement the QUIC probe: call QUICDialer.DialQuic (handshake only, no stream opened) and record the result.
3. Implement the HTTP/2 probe: call TCPDialer.DialEdge (TCP + TLS handshake only, no frames sent) and record the result.
4. Implement the Management API probe: call ManagementDialer.DialContext to api.cloudflare.com:443 and record the result.
5. Export edgeDiscovery as EdgeDiscovery in edgediscovery/allregions/discovery.go so the pre-check can reuse the production DNS path.
This sets up the main components to implement the checker.
Check / check (1.22.x, macos-latest) (push) Has been cancelled
Check / check (1.22.x, ubuntu-latest) (push) Has been cancelled
Check / check (1.22.x, windows-latest) (push) Has been cancelled
Semgrep config / semgrep/ci (push) Has been cancelled
To allow pre-checks to test both IPv6 and IPv4, we must change the default value of edge-ip-version's from 4 to auto. This will allows the tunnel (and pre-check) to probe both IPv4 and IPv6 addresses by default, respecting the system's DNS preference. Instead of always preferring IPv4, cloudflared will now use whichever address family the system resolver returns first.
Trying to fix the following errors that showed up in CI, which became an issue when doing the pre-check work in https://gitlab.cfdata.org/cloudflare/tun/cloudflared/-/merge_requests/1814:
```
cmd/cloudflared/tunnel/cmd.go:454:29: Error return value of `metricsListener.Close` is not checked (errcheck)
defer metricsListener.Close()
^
cmd/cloudflared/tunnel/cmd.go:573:18: Error return value of `file.Close` is not checked (errcheck)
defer file.Close()
^
cmd/cloudflared/tunnel/cmd.go:574:13: Error return value of `fmt.Fprintf` is not checked (errcheck)
fmt.Fprintf(file, "%d", os.Getpid())
^
cmd/cloudflared/tunnel/cmd.go:47:2: G101: Potential hardcoded credentials: Password in URL (gosec)
sentryDSN = "https://56a9c9fa5c364ab28f34b14f35ea0f1b:3e8827f6f9f740738eb11138f7bebb68@sentry.io/189878"
^
cmd/cloudflared/tunnel/cmd.go:348:23: G703: Path traversal via taint analysis (gosec)
if err := os.Rename(tmpTraceFile.Name(), traceOutputFilepath); err != nil {
^
cmd/cloudflared/tunnel/cmd.go:354:21: G703: Path traversal via taint analysis (gosec)
err := os.Remove(tmpTraceFile.Name())
^
cmd/cloudflared/tunnel/cmd.go:568:15: G304: Potential file inclusion via variable (gosec)
file, err := os.Create(expandedPath)
^
cmd/cloudflared/tunnel/cmd.go:260:10: ST1005: error strings should not be capitalized (staticcheck)
return fmt.Errorf("Use `cloudflared tunnel run` to start tunnel %s", ref)
^
cmd/cloudflared/tunnel/cmd.go:1146:5: SA4011: ineffective break statement. Did you mean to break out of the outer loop? (staticcheck)
break
^
9 issues:
* errcheck: 3
* gosec: 4
* staticcheck: 2
```
Check / check (1.22.x, macos-latest) (push) Has been cancelled
Check / check (1.22.x, ubuntu-latest) (push) Has been cancelled
Check / check (1.22.x, windows-latest) (push) Has been cancelled
Semgrep config / semgrep/ci (push) Has been cancelled
Create new management token command to support different resource
permissions (logs, admin, host_details). This fixes failing component
tests that need admin-level tokens to access management endpoints.
- Add ManagementResource enum values: Admin, HostDetails
- Create cmd/cloudflared/management package with token command
- Extract shared utilities to cliutil/management.go (GetManagementToken, CreateStderrLogger)
- Refactor tail/cmd.go to use shared utilities
- Update component tests to use new command with admin resource
Closes TUN-10292
* TUN-10247: Update tail command to use /management/logs endpoint
The /management endpoint will be deprecated in favor of new /management/resource endpoints. Because of that, we'll need cloudflared to use the new endpoint.
Closes TUN-10247
Remove the DNS over HTTPS (DoH) proxy feature built on CoreDNS due to
security vulnerabilities (GO-2025-3942, GO-2026-4289).
This removes:
- Standalone proxy-dns command (cloudflared proxy-dns)
- Tunnel subcommand (cloudflared tunnel proxy-dns)
- Proxy-dns flags for tunnel run (--proxy-dns, --proxy-dns-port, etc.)
- Config file resolver section support
- tunneldns/ package (CoreDNS-based implementation)
- Related component tests
BREAKING CHANGE: The proxy-dns feature is no longer available.
Users should migrate to alternative DNS over HTTPS solutions.
* Fix systemd service installation hanging
---
This kills the hanging when there is a network issue (port blocking or no Internet) and the installation cannot be completed with no error sent to the output.
Before (killed manually since it hangs forever):
{width=817 height=69}
After:
{width=825 height=78}
---
Semgrep config / semgrep/ci (push) Has been cancelled
Check / check (1.22.x, macos-latest) (push) Has been cancelled
Check / check (1.22.x, ubuntu-latest) (push) Has been cancelled
Check / check (1.22.x, windows-latest) (push) Has been cancelled
This commit adds support for FedRAMP environments. Cloudflared will
now dynamically configure the management hostname and API URL, switching
to FedRAMP-specific values like `management.fed.argotunnel.com` and `https://api.fed.cloudflare.com/client/v4`
when a FedRAMP endpoint is detected.
Key to this is an enhanced `ParseToken` function, which now includes an `IsFed()`
method to determine if a management token's issuer is `fed-tunnelstore`. This allows
cloudflared to correctly identify and operate within a FedRAMP context, ensuring
proper connectivity.
Closes TUN-9583
Check / check (1.22.x, macos-latest) (push) Has been cancelled
Check / check (1.22.x, ubuntu-latest) (push) Has been cancelled
Check / check (1.22.x, windows-latest) (push) Has been cancelled
Semgrep config / semgrep/ci (push) Has been cancelled
To help support users with environments that don't work well with the
DNS local resolver's automatic resolution process for local resolver
addresses, we introduce a flag to provide them statically to the
runtime. When providing the resolver addresses, cloudflared will no
longer lookup the DNS resolver addresses and use the user input
directly.
When provided with a list of DNS resolvers larger than one, the resolver
service will randomly select one at random for each incoming request.
Closes TUN-9473
Adds an OriginDialerService that takes over the roles of both DialUDP and DialTCP
towards the origin. This provides the possibility to leverage dialer "middleware"
to inject virtual origins, such as the DNS resolver service.
DNS Resolver service also gains access to the DialTCP operation to service TCP
DNS requests.
Minor refactoring includes changes to remove the needs previously provided by
the warp-routing configuration. This configuration cannot be disabled by cloudflared
so many of the references have been adjusted or removed.
Closes TUN-9470
Semgrep config / semgrep/ci (push) Has been cancelled
Check / check (1.22.x, ubuntu-latest) (push) Has been cancelled
Check / check (1.22.x, windows-latest) (push) Has been cancelled
Check / check (1.22.x, macos-latest) (push) Has been cancelled
## Summary
Update several moving parts of cloudflared build system:
* use goboring 1.24.2 in cfsetup
* update linter and fix lint issues
* update packages namely **quic-go and net**
* install script for macos
* update docker files to use go 1.24.1
* remove usage of cloudflare-go
* pin golang linter
Closes TUN-9016
Make sure to enforce snapshots of features and client information for each connection
so that the feature information can change in the background. This allows for new features
to only be applied to a connection if it completely disconnects and attempts a reconnect.
Updates the feature refresh time to 1 hour from previous cloudflared versions which
refreshed every 6 hours.
Closes TUN-9319
During a refresh of the supported features via the DNS TXT record,
cloudflared would update the internal feature list, but would not
propagate this information to the edge during a new connection.
This meant that a situation could occur in which cloudflared would
think that the client's connection could support datagram V3, and
would setup that muxer locally, but would not propagate that information
to the edge during a register connection in the `ClientInfo` of the
`ConnectionOptions`. This meant that the edge still thought that the
client was setup to support datagram V2 and since the protocols are
not backwards compatible, the local muxer for datagram V3 would reject
the incoming RPC calls.
To address this, the feature list will be fetched only once during
client bootstrapping and will persist as-is until the client is restarted.
This helps reduce the complexity involved with different connections
having possibly different sets of features when connecting to the edge.
The features will now be tied to the client and never diverge across
connections.
Also, retires the use of `support_datagram_v3` in-favor of
`support_datagram_v3_1` to reduce the risk of reusing the feature key.
The `dv3` TXT feature key is also deprecated.
Closes TUN-9291
Using path package methods can cause errors on windows machines.
path methods are used for url operations and unix specific operation.
filepath methods are used for file system paths and its cross platform.
Remove strings.HasSuffix and use filepath.Ext and path.Ext for file and
url extenstions respectively.
## Issue
The [documentation for creating a tunnel's configuration
file](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/#4-create-a-configuration-file)
does not specify that the `credentials-file` field in `config.yml` needs
to be an absolute path.
A user (E.G. me 🤦) might add a path like `~/.cloudflared/<uuid>.json`
and wonder why the `cloudflared tunnel run` command is throwing a
credentials file not found error. Although one might consider it
intuitive, it's not a fair assumption as a lot of CLI tools allow file
paths with `~` for specifying files.
P.S. The tunnel ID in the following snippet is not a real tunnel ID, I
just generated it.
```
url: http://localhost:8000
tunnel: 958a1ef6-ff8c-4455-825a-5aed91242135
credentials-file: ~/.cloudflared/958a1ef6-ff8c-4455-825a-5aed91242135.json
```
Furthermore, the error has a confusing message for the user as the file
at the logged path actually exists, it is just that `os.Stat` failed
because it could not expand the `~`.
## Solution
This commit fixes the above issue by running a `homedir.Expand` on the
`credentials-file` path in the `credentialFinder` function.
Per the contribution guidelines, this seemed to me like a small enough
change to not warrant an issue before creating this pull request. Let me
know if you'd like me to create one anyway.
## Background
While working with `cloudflared` on FreeBSD recently, I noticed that
there's an inconsistency with the available CLI commands on that OS
versus others — namely that the `service` command doesn't exist at all
for operating systems other than Linux, macOS, and Windows.
Contrast `cloudflared --help` output on macOS versus FreeBSD (truncated
to focus on the `COMMANDS` section):
- Current help output on macOS:
```text
COMMANDS:
update Update the agent if a new version exists
version Print the version
proxy-dns Run a DNS over HTTPS proxy server.
tail Stream logs from a remote cloudflared
service Manages the cloudflared launch agent
help, h Shows a list of commands or help for one command
Access:
access, forward access <subcommand>
Tunnel:
tunnel Use Cloudflare Tunnel to expose private services to the Internet
or to Cloudflare connected private users.
```
- Current help output on FreeBSD:
```text
COMMANDS:
update Update the agent if a new version exists
version Print the version
proxy-dns Run a DNS over HTTPS proxy server.
tail Stream logs from a remote cloudflared
help, h Shows a list of commands or help for one command
Access:
access, forward access <subcommand>
Tunnel:
tunnel Use Cloudflare Tunnel to expose private services to the Internet
or to Cloudflare connected private users.
```
This omission has caused confusion for users (including me), especially
since the provided command in the Cloudflare Zero Trust dashboard
returns a seemingly-unrelated error message:
```console
$ sudo cloudflared service install ...
You did not specify any valid additional argument to the cloudflared tunnel command.
If you are trying to run a Quick Tunnel then you need to explicitly pass the --url flag.
Eg. cloudflared tunnel --url localhost:8080/.
Please note that Quick Tunnels are meant to be ephemeral and should only be used for testing purposes.
For production usage, we recommend creating Named Tunnels. (https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/)
```
## Contribution
This pull request adds a "stub" `service` command (including the usual
subcommands available on other OSes) to explicitly declare it as
unsupported on the operating system.
New help output on FreeBSD (and other operating systems where service
management is unsupported):
```text
COMMANDS:
update Update the agent if a new version exists
version Print the version
proxy-dns Run a DNS over HTTPS proxy server.
tail Stream logs from a remote cloudflared
service Manages the cloudflared system service (not supported on this operating system)
help, h Shows a list of commands or help for one command
Access:
access, forward access <subcommand>
Tunnel:
tunnel Use Cloudflare Tunnel to expose private services to the Internet or to Cloudflare connected private users.
```
New outputs when running the service management subcommands:
```console
$ sudo cloudflared service install ...
service installation is not supported on this operating system
```
```console
$ sudo cloudflared service uninstall ...
service uninstallation is not supported on this operating system
```
This keeps the available commands consistent until proper service
management support can be added for these otherwise-supported operating
systems.
Rhys Rustad-Elliott
Miguel da Costa Martins Marcelino
Christopher Meng
Christopher Meng
lneto
Evan Raw
GoncaloGarcia
João "Pisco" Fernandes
chungthuang
Kyle Hiller
Kevin Marshall
Devin Carr
Cyb3r Jak3
gofastasf
Rohan Mukherjee
Micah Yeager
Roman
VFLC