curben
/
cloudflared-mirror
mirror of https://github.com/cloudflare/cloudflared.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Replace README with fork-specific documentation for EdgeOS and multi-arch builds 

- Explains this is an auto-synced fork with MIPS/EdgeOS support
- Documents all 9 supported architectures with device mapping table
- Provides quick install commands for all EdgeRouter models
- Explains the automated upstream sync CI/CD pipeline with diagram
- Includes EdgeOS service setup guide
- Includes cross-compilation instructions
- Links back to upstream project and documentation

Co-authored-by: ApophisLee <2356831+ApophisLee@users.noreply.github.com>
Agent-Logs-Url: https://github.com/cafe-x-technologies/cloudflared/sessions/28c1db55-3cb1-4db2-9ae3-ad4fb3869432
This commit is contained in:
copilot-swe-agent[bot] 2026-03-25 14:25:46 +00:00
parent f4a5b44a43
commit 53b676c007
1 changed files with 138 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
README.md
View File

@ -1,82 +1,166 @@
# Cloudflare Tunnel client
# cloudflared — EdgeOS & Multi-Arch Fork
Contains the command-line client for Cloudflare Tunnel, a tunneling daemon that proxies traffic from the Cloudflare network to your origins.
This daemon sits between Cloudflare network and your origin (e.g. a webserver). Cloudflare attracts client requests and sends them to you
via this daemon, without requiring you to poke holes on your firewall --- your origin can remain as closed as possible.
Extensive documentation can be found in the [Cloudflare Tunnel section](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel) of the Cloudflare Docs.
All usages related with proxying to your origins are available under `cloudflared tunnel help`.
> 🔄 **Auto-synced fork** of [`cloudflare/cloudflared`](https://github.com/cloudflare/cloudflared) with additional builds for **UniFi EdgeOS** routers and other MIPS devices.
You can also use `cloudflared` to access Tunnel origins (that are protected with `cloudflared tunnel`) for TCP traffic
at Layer 4 (i.e., not HTTP/websocket), which is relevant for use cases such as SSH, RDP, etc.
Such usages are available under `cloudflared access help`.
[![Sync Upstream Release](https://github.com/cafe-x-technologies/cloudflared/actions/workflows/sync-upstream-release.yml/badge.svg)](https://github.com/cafe-x-technologies/cloudflared/actions/workflows/sync-upstream-release.yml)
You can instead use [WARP client](https://developers.cloudflare.com/warp-client/)
to access private origins behind Tunnels for Layer 4 traffic without requiring `cloudflared access` commands on the client side.
## What is this?
This repository is a fork of the official [cloudflare/cloudflared](https://github.com/cloudflare/cloudflared) Cloudflare Tunnel client. It adds:
## Before you get started
- **Automated upstream sync** — A CI/CD pipeline checks for new upstream releases every 6 hours and automatically builds & publishes them here
- **MIPS architecture support** — Pre-built binaries and `.deb` packages for UniFi EdgeOS devices that are not available in the official releases
- **Multi-architecture releases** — Every release includes 9 platform/arch combinations plus `.deb` packages
Before you use Cloudflare Tunnel, you'll need to complete a few steps in the Cloudflare dashboard: you need to add a
website to your Cloudflare account. Note that today it is possible to use Tunnel without a website (e.g. for private
routing), but for legacy reasons this requirement is still necessary:
1. [Add a website to Cloudflare](https://developers.cloudflare.com/fundamentals/manage-domains/add-site/)
2. [Change your domain nameservers to Cloudflare](https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/)
## Supported Architectures
| Platform | Architecture | Binary | `.deb` | Devices |
|---|---|---|---|---|
| Linux | amd64 | ✅ | ✅ | Standard x86_64 servers |
| Linux | arm64 | ✅ | ✅ | Raspberry Pi 3/4/5, AWS Graviton |
| Linux | armhf (ARMv7) | ✅ | ✅ | Raspberry Pi 2, 32-bit ARM |
| Linux | arm (ARMv5) | ✅ | — | Older ARM devices |
| Linux | 386 | ✅ | — | 32-bit x86 |
| Linux | **mipsle** | ✅ | ✅ | **EdgeRouter X / ER-X-SFP** (MT7621) |
| Linux | **mips64** | ✅ | ✅ | **EdgeRouter Lite / ER-4 / ER-6P / ER-12** (Cavium Octeon) |
| macOS | amd64 | ✅ | — | Intel Mac |
| macOS | arm64 | ✅ | — | Apple Silicon (M1/M2/M3/M4) |
## Installing `cloudflared`
## Quick Install — EdgeOS
Downloads are available as standalone binaries, a Docker image, and Debian, RPM, and Homebrew packages. You can also find releases [here](https://github.com/cloudflare/cloudflared/releases) on the `cloudflared` GitHub repository.
### EdgeRouter X / ER-X-SFP (MIPS little-endian)
* You can [install on macOS](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/#macos) via Homebrew or by downloading the [latest Darwin amd64 release](https://github.com/cloudflare/cloudflared/releases)
* Binaries, Debian, and RPM packages for Linux [can be found here](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/#linux)
* A Docker image of `cloudflared` is [available on DockerHub](https://hub.docker.com/r/cloudflare/cloudflared)
* You can install on Windows machines with the [steps here](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/#windows)
* To build from source, install the required version of go, mentioned in the [Development](#development) section below. Then you can run `make cloudflared`.
```bash
# Download and install the latest release
LATEST=$(curl -s https://api.github.com/repos/cafe-x-technologies/cloudflared/releases/latest | grep tag_name | cut -d '"' -f4)
curl -L -o /tmp/cloudflared.deb "https://github.com/cafe-x-technologies/cloudflared/releases/download/${LATEST}/cloudflared_${LATEST}_mipsel.deb"
sudo dpkg -i /tmp/cloudflared.deb
User documentation for Cloudflare Tunnel can be found at https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/
# Verify installation
cloudflared --version
```
### EdgeRouter Lite / ER-4 / ER-6P / ER-12 (MIPS64 big-endian)
## Creating Tunnels and routing traffic
```bash
# Download and install the latest release
LATEST=$(curl -s https://api.github.com/repos/cafe-x-technologies/cloudflared/releases/latest | grep tag_name | cut -d '"' -f4)
curl -L -o /tmp/cloudflared.deb "https://github.com/cafe-x-technologies/cloudflared/releases/download/${LATEST}/cloudflared_${LATEST}_mips64.deb"
sudo dpkg -i /tmp/cloudflared.deb
Once installed, you can authenticate `cloudflared` into your Cloudflare account and begin creating Tunnels to serve traffic to your origins.
# Verify installation
cloudflared --version
```
* Create a Tunnel with [these instructions](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/)
* Route traffic to that Tunnel:
* Via public [DNS records in Cloudflare](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/dns/)
* Or via a public hostname guided by a [Cloudflare Load Balancer](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/public-load-balancers/)
* Or from [WARP client private traffic](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/)
### Manual binary install (any architecture)
```bash
# Example for mipsle (EdgeRouter X)
LATEST=$(curl -s https://api.github.com/repos/cafe-x-technologies/cloudflared/releases/latest | grep tag_name | cut -d '"' -f4)
curl -L -o /tmp/cloudflared "https://github.com/cafe-x-technologies/cloudflared/releases/download/${LATEST}/cloudflared-linux-mipsle"
chmod +x /tmp/cloudflared
sudo mv /tmp/cloudflared /usr/local/bin/cloudflared
```
## TryCloudflare
## Quick Install — Other platforms
Want to test Cloudflare Tunnel before adding a website to Cloudflare? You can do so with TryCloudflare using the documentation [available here](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/).
For standard platforms (amd64, arm64, macOS), you can use the official Cloudflare installation methods or download binaries from our [Releases](https://github.com/cafe-x-technologies/cloudflared/releases) page.
## Deprecated versions
See the [official cloudflared documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/) for more installation options.
Cloudflare currently supports versions of cloudflared that are **within one year** of the most recent release. Breaking changes unrelated to feature availability may be introduced that will impact versions released more than one year ago. You can read more about upgrading cloudflared in our [developer documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/update-cloudflared/).
## How the Sync Works
For example, as of January 2023 Cloudflare will support cloudflared version 2023.1.1 to cloudflared 2022.1.1.
```
┌──────────────────────────┐
│ cloudflare/cloudflared │ Upstream (official)
│ New release tagged │
└────────────┬─────────────┘
│ ⏰ Checked every 6 hours
▼
┌──────────────────────────┐
│ sync-upstream-release │ GitHub Actions workflow
│ .yml │
├───────────────────────────┤
│ 1. Detect new release tag │
│ 2. Build 9 arch binaries │
│ 3. Package 5 .deb files │
│ 4. Create GitHub Release │
└────────────┬──────────────┘
▼
┌──────────────────────────┐
│ cafe-x-technologies/ │ This fork
│ cloudflared/releases │ With MIPS + all platforms
└───────────────────────────┘
```
The workflow can also be **manually triggered** from the [Actions tab](https://github.com/cafe-x-technologies/cloudflared/actions/workflows/sync-upstream-release.yml) with options to:
- Specify a particular upstream tag to sync
- Force re-release an existing tag
## Running cloudflared as a Service on EdgeOS
After installing, you can set up cloudflared as a tunnel service:
```bash
# Authenticate (follow the URL that appears)
cloudflared tunnel login
# Create a tunnel
cloudflared tunnel create my-tunnel
# Configure your tunnel (edit the config file)
sudo mkdir -p /etc/cloudflared
sudo cat > /etc/cloudflared/config.yml << 'EOF'
tunnel: <YOUR-TUNNEL-ID>
credentials-file: /root/.cloudflared/<YOUR-TUNNEL-ID>.json
ingress:
- hostname: myapp.example.com
service: http://localhost:8080
- service: http_status:404
EOF
# Run the tunnel
cloudflared tunnel run my-tunnel
```
To run on boot, create a systemd service or add to EdgeOS task-scheduler.
## Development
### Requirements
- [GNU Make](https://www.gnu.org/software/make/)
- [capnp](https://capnproto.org/install.html)
- [go >= 1.24](https://go.dev/doc/install)
- Optional tools:
- [capnpc-go](https://pkg.go.dev/zombiezen.com/go/capnproto2/capnpc-go)
- [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports)
- [golangci-lint](https://github.com/golangci/golangci-lint)
- [gomocks](https://pkg.go.dev/go.uber.org/mock)
This fork tracks upstream and adds MIPS architecture support to the `Makefile`.
### Build
To build cloudflared locally run `make cloudflared`
### Cross-compile for EdgeOS
### Test
To locally run the tests run `make test`
```bash
# EdgeRouter X (mipsle, softfloat)
make cloudflared TARGET_OS=linux TARGET_ARCH=mipsle TARGET_MIPS=softfloat
### Linting
To format the code and keep a good code quality use `make fmt` and `make lint`
# EdgeRouter Lite/4/6P/12 (mips64)
make cloudflared TARGET_OS=linux TARGET_ARCH=mips64
### Mocks
After changes on interfaces you might need to regenerate the mocks, so run `make mock`
# Build .deb package
make cloudflared-deb TARGET_OS=linux TARGET_ARCH=mipsle TARGET_MIPS=softfloat
```
### Build & test (standard)
```bash
make cloudflared # Build for current platform
make test # Run tests
make lint # Run linters
```
For full development documentation, see the [upstream README](https://github.com/cloudflare/cloudflared#development).
## Upstream Project
This is a fork of [**cloudflare/cloudflared**](https://github.com/cloudflare/cloudflared) — the official Cloudflare Tunnel client.
- 📖 [Cloudflare Tunnel Documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/)
- 📦 [Official Releases](https://github.com/cloudflare/cloudflared/releases)
- 🐳 [Docker Image](https://hub.docker.com/r/cloudflare/cloudflared)
## License
Same as upstream — [Apache License 2.0](LICENSE)