DOCSEARCHbyAlgolia
Submit Docs

cloudflared - Cloudflare Tunnel Client

repository·master·Indexed 12 days ago

https://github.com/cloudflare/cloudflared

A command-line client and daemon for Cloudflare Tunnel that creates secure connections between the Cloudflare network and local origins. It allows users to expose services without opening firewall ports, proxy protocols like SSH over WebSockets via Cloudflare Access, and manage tunnels, hostnames, IP routes, and virtual networks using the cfapi.Client.

Tokens
19.2K
Snippets
60
Records
103
Agent score
97%

What's inside cloudflared

  1. What is cloudflared?

    master

    cloudflared is the command-line client for Cloudflare Tunnel. It acts as a tunneling daemon that proxies traffic from the Cloudflare network to your origins (e.g., a webserver).

    By sitting between the Cloudflare network and your origin, it allows you to receive traffic without opening holes in your firewall, keeping your origin as closed as possible.

    Key Use Cases:

    • Proxying to origins: Use cloudflared tunnel help for commands related to serving traffic to your origins.
    • Accessing Tunnel origins via TCP: Use cloudflared access help to access protected origins for Layer 4 traffic (e.g., SSH, RDP).
    • Private traffic via WARP: Use the WARP client to access private origins behind Tunnels for Layer 4 traffic without needing cloudflared access commands on the client side.

  2. Install cloudflared

    master

    You can install cloudflared using several methods depending on your operating system:

    • macOS: Use Homebrew or download the latest Darwin amd64 release.
    • Linux: Use standalone binaries, Debian packages, or RPM packages.
    • Windows: Follow the specific Windows installation steps in the Cloudflare documentation.
    • Docker: Use the official image available on DockerHub.
    • Build from source: Install the required Go version (see Development section) and run make cloudflared.

  3. Set up the cloudflared component tests environment

    master

    To run the component tests, you must prepare a Python environment and a valid cloudflared configuration.

    1. Python Environment

    Install Python 3.10 or later and the required dependencies from requirements.txt using a virtual environment:

    python3 -m venv ./.venv
source ./.venv/bin/activate
python3 -m pip install -r requirements.txt

    2. Configuration File

    Create a YAML configuration file. This file must specify the cloudflared_binary, the tunnel ID, the credentials_file path, the origincert path, and an ingress rule set.

    3. DNS Routing

    You must route the hostname used in your ingress rules to the tunnel using the cloudflared tunnel route dns command.

    4. Handling Local Services

    If cloudflared is already running as a system service on your machine, you can avoid conflicts by either stopping the service or ignoring the service tests using the --ignore test_service.py flag during test execution.

    # Example config.yaml
cloudflared_binary: "cloudflared"
tunnel: "3d539f97-cd3a-4d8e-c33b-65e9099c7a8d"
credentials_file: "/Users/tunnel/.cloudflared/3d539f97-cd3a-4d8e-c33b-65e9099c7a8d.json"
origincert: "/Users/tunnel/.cloudflared/cert.pem"
ingress:
- hostname: named-tunnel-component-tests.example.com
  service: hello_world
- service: http_status:404

# DNS Routing command
cloudflared tunnel route dns 3d539f97-cd3a-4d8e-c33b-65e9099c7a8d named-tunnel-component-tests.example.com

  4. Create Tunnels and route traffic

    master

    After installing cloudflared, follow these steps to serve traffic to your origins:

    1. Authenticate: Authenticate cloudflared into your Cloudflare account.
    2. Create a Tunnel: Follow the instructions to create a remote tunnel.
    3. Route Traffic: You can route traffic to your Tunnel via:
      • Public DNS records in Cloudflare.
      • A public hostname guided by a Cloudflare Load Balancer.
      • Private traffic from a WARP client.

  5. Run cloudflared component tests

    master

    Component tests are executed using pytest. You must provide the path to your configuration file via the COMPONENT_TESTS_CONFIG environment variable.

    Running all tests

    Execute pytest from within the component-tests directory.

    Running specific files

    Pass the filenames as arguments to pytest.

    Running specific tests

    Use the -k flag to filter by test names.

    Live Logging

    By default, the log level is WARN. To see logs in real-time in your terminal, use the -o log_cli=true flag. You can adjust the verbosity using --log-cli-level.

    Example: Running tests with INFO level live logging:

    COMPONENT_TESTS_CONFIG=path/to/config.yaml pytest -o log_cli=true --log-cli-level=INFO
    # Run all tests with INFO level live logging
COMPONENT_TESTS_CONFIG=config.yaml pytest -o log_cli=true --log-cli-level=INFO

# Run specific tests by name
COMPONENT_TESTS_CONFIG=config.yaml pytest file.py -k "test_name_1" -k "test_name_2"

  6. Build and develop cloudflared from source

    master

    To develop on cloudflared, ensure you have the following requirements installed:

    Requirements:

    • GNU Make
    • capnp
    • go >= 1.26
    • (Optional) capnpc-go, goimports, golangci-lint, gomocks

    Common Development Commands:

    • Build the binary: make cloudflared
    • Run tests: make test
    • Format code: make fmt
    • Lint code: make lint
    • Regenerate mocks: make mocks
    • Install git pre-push hooks: make install-hooks (runs make fmt-check lint test before pushing)
    make cloudflared
make test
make fmt
make lint
make mocks
make install-hooks

  8. Use the cloudflared CLI

    master

    The cloudflared command-line tool connects your machine or user identity to Cloudflare's global network. It is used to authenticate sessions for Cloudflare Access, route web traffic to your machine, and configure access control.

    Usage Syntax: cloudflared [global options] [command] [command options]

    Core Commands:

    • tunnel: Manage and run Cloudflare Tunnels (subcommands available).
    • access: Manage Cloudflare Access sessions (subcommands available).
    • update: Update the cloudflared agent.
    • version: Check the installed version.
    • tail: Access logs/streams (subcommands available).
    • management: Management operations (subcommands available).

  9. Proxy protocols like SSH over Cloudflare Access

    master

    The ssh command allows you to proxy other protocols (such as SSH) over WebSockets. This is useful for placing Cloudflare Access in front of non-HTTP services.

    Depending on how you invoke the command, it operates in two modes:

    1. Server Mode: Starts a WebSocket proxy server.
    2. Client Mode: Copies data from stdin to stdout, allowing it to be piped into or out of other processes.

    When using the ssh command, you can provide authentication headers and connection overrides to manage how the traffic is routed and authenticated.

  10. Locate and use tunnel credentials

    master

    To run a tunnel, cloudflared needs a credentials file (a .json file) containing the TunnelID, TunnelSecret, AccountTag, and Endpoint.

    You can specify the credentials in several ways:

    1. Via CLI Flag: Use the --cred-file flag to provide a direct path to the .json credentials file. This path supports ~ expansion.
    2. Via JSON Content: Use the --cred-contents flag to pass the raw JSON string of the credentials directly.
    3. Automatic Discovery: If no flag is provided, cloudflared attempts to find the credentials file by searching for a file associated with the tunnel ID, often located in the same directory as your origin certificate (cert.pem).

    Note: Do not confuse the tunnel credentials file (.json) with the origin certificate (.pem) generated by cloudflared tunnel login. Using a .pem file where a .json is expected will result in an error.

  11. Identify tunnels by ID or Name

    master

    Most cloudflared tunnel commands accept either a UUID or a human-readable name as an identifier.

    When you provide an identifier, cloudflared resolves it using this priority:

    1. UUID Check: If the input is a valid UUID, it is used directly.
    2. Credentials Lookup: If the input is a name, cloudflared checks your local credentials files to see if a TunnelID is mapped to that name.
    3. API Lookup: If not found locally, cloudflared queries the Cloudflare API to find an active (non-deleted) tunnel matching that name.

  12. How auto-updates work in cloudflared

    master

    When running as a service (and not via a package manager or on Windows), cloudflared can periodically check for and apply updates automatically.

    Lifecycle of an Auto-Update:

    1. Check: The AutoUpdater periodically checks the update URL (default frequency is 24 hours).
    2. Download & Apply: If a new version is found, it is downloaded and applied.
    3. Restart:
      • For standard services, the process restarts to use the new version.
      • For SysV managed services, the updater explicitly attempts to start a new process via the listeners service to ensure the service remains alive after the old process exits.

    Requirements for Auto-Updates to function:

    • Must not be running in a standard terminal/shell (must be a service).
    • Must not be installed via a package manager.
    • Must not be running on Windows.
    • updateDisabled must be false and a non-zero frequency must be configured.