If no additional parameters are supplied this mod adds cloudflared using the latest release tag to any LSIO docker image, to be installed/updated during container start.

If all additional parameters are supplied this docker mod will also create/configure/route/enable a cloudflare tunnel via cloudflared and the cloudflare v4 API.

This mod supports both locally managed and remotely managed tunnels.

Remotely Managed Tunnel Usage

First create a tunnel on Cloudflare's Zero Trust Dashboard and note the tunnel's token.

Here an example snippet to help you get started using this docker mod.

docker-compose (recommended)

  swag:
    image: lscr.io/linuxserver/nginx
    container_name: nginx
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Europe/London
      DOCKER_MODS: linuxserver/mods:universal-cloudflared
      CF_REMOTE_MANAGE_TOKEN: cbvcnbvcjyrtd5erxjhgvkjhbvmhnfchgfchgjv
    volumes:
      - /path/to/appdata/config:/config
    restart: unless-stopped

Parameters

Container images/mods are configured using parameters passed at runtime (such as those above).

Parameter	Function	Notes
`DOCKER_MODS`	Enable this docker mod with `linuxserver/mods:universal-cloudflared`	If adding multiple mods, enter them in an array separated by `\|`, such as `DOCKER_MODS: linuxserver/mods:universal-cloudflared\|linuxserver/mods:universal-mod2`

Cloudflare tunnel parameters

Parameter	Function	Notes
`CF_REMOTE_MANAGE_TOKEN`	Existing Cloudflare tunnel's token

Once set up, all tunnel config will be handled through the Zero Trust Dashboard

Locally Managed Tunnel Usage

Here an example snippet to help you get started using this docker mod.

docker-compose (recommended)

  swag:
    image: lscr.io/linuxserver/nginx
    container_name: nginx
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Europe/London
      DOCKER_MODS: linuxserver/mods:universal-cloudflared
      CF_ZONE_ID: zone_id
      CF_ACCOUNT_ID: acct_id
      CF_API_TOKEN: token
      CF_TUNNEL_NAME: example
      CF_TUNNEL_PASSWORD: pleasedontusethisexamplepassword
      CF_TUNNEL_CONFIG: |
        ingress:
          - hostname: test.yourdomain.url
            service: http://localhost:80
          - service: http_status:404
    volumes:
      - /path/to/appdata/config:/config
    restart: unless-stopped

Parameters

Container images/mods are configured using parameters passed at runtime (such as those above).

Parameter	Function	Notes
`DOCKER_MODS`	Enable this docker mod with `linuxserver/mods:universal-cloudflared`	If adding multiple mods, enter them in an array separated by `\|`, such as `DOCKER_MODS: linuxserver/mods:universal-cloudflared\|linuxserver/mods:universal-mod2`

Cloudflare tunnel parameters

Parameter	Function	Notes
`CF_ZONE_ID`	Cloudflare zone ID
`CF_ACCOUNT_ID`	Cloudflare account ID
`CF_API_TOKEN`	Cloudflare API token	Must have the `Account.Cloudflare Tunnel:Edit` and `Zone.DNS:Edit` permissions.
`CF_TUNNEL_NAME`	Cloudflare tunnel name
`CF_TUNNEL_PASSWORD`	Cloudflare tunnel password	32 char minimum
`CF_TUNNEL_CONFIG`	Cloudflare tunnel config, please refer to Cloudflare's official tunnel docs.	Do not add `tunnel`/`credentials-file` headers, these are handled automatically.
`FILE__<VARIABLE_NAME>`	Sources content of the file as value in case of multiline content	`FILE__CF_TUNNEL_CONFIG=/config/tunnelconfig.yml`

Alternative yaml formatting

If you're using a method that doesn't allow you to enter a properly formatted yaml into an environment variable (e.g. docker run, or the compose yaml format we recommend in our samples, or a web gui manager) you can alternatively use a yaml file to set the CF_TUNNEL_CONFIG variable.

Create a properly formatted yaml file in the /config folder of your container (e.g. /config/tunnelconfig.yml):

ingress:
  - hostname: test.yourdomain.url
    service: http://localhost:80
  - service: http_status:404

After you have created the file, use the special FILE__ prefix for the environment variable which will source the content of the file as a value for the variable specified (FILE__CF_TUNNEL_CONFIG=/config/tunnelconfig.yml).

Troubleshooting

If you are getting error Json deserialize error: control character (\\u0000-\\u001F) found while parsing, please make sure when copy/pasting environment variables and their value from web sources that they do not contain new line characters.