Configuring tunnels through a YAML file (what we refer to as a configuration file) allows you to have fine-grained control over how an instance of
cloudflared will operate. In your configuration file you can specify top-level properties for your
cloudflared instance, as well as configure origin-specific properties by writing ingress rules and adding parameters to them.
In the absence of a configuration file,
cloudflared will proxy outbound traffic through port 8080.
The structure of a configuration file will be different depending on the type of resource you want to expose to the Internet.
When creating a configuration file, it is best practice to list
credentials-file as your first key/value pairs. Whether you are exposing an application or a network on the Internet, it is common to list these keys as the first ones in your configuration file:
tunnel: The tunnel UUIDcredentials-file: /path/your-tunnels-credentials-file.json
If you’re exposing a private network, you need to add the
warp-routing key and set it to
tunnel: The tunnel UUIDcredentials-file: /path/your-tunnels-credentials-file.jsonwarp-routing:enabled: true
Once your top-level configuration is complete, you can begin addressing origin-specific configurations. By writing ingress rules in the configuration file, you can specify which local services a request should be proxied to. Refer to the ingress rules page for more information on writing ingress rules and how they work.
Creating a configuration file
You can create your configuration file using any text editor. For example, to create a configuration file in the default
cloudflared directory with vim:
cdinto your system’s default directory for
- Open vim and type in the necessary keys and values.
- Name and save your file by typing
:wq config.yamland exit vim.
Confirm that the configuration file has been successfully created by running:
$ cat config.yaml
Naming and storing a configuration file
cloudflared will automatically look for a
config.yml file in the default
You can give your configuration file a custom name and store it in any directory. However, when running tunnel, make sure to add the
--config flag and specify the new path.
$ cloudflared tunnel --config /path/your-config-file.yaml run tunnel-name
Editing a configuration file
When making changes to the configuration file for a given tunnel, we suggest relying on
cloudflared replicas to propagate the new configuration with minimal downtime.
- Have a
cloudflaredinstance running with the original version of the configuration file.
- Start a
cloudflaredreplica running with the updated version of the configuration file.
- Wait for the replica to be fully running and usable.
- Stop the first instance of
cloudflared will now be running with the updated version of your configuration file.