Configuration file

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.

​​ File structure

The structure of a configuration file will be different depending on the type of resource you want to expose to the Internet.

​​ Top-level configurations

When creating a configuration file, it is best practice to list tunnel and 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 UUID
credentials-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 true:

tunnel: The tunnel UUID
credentials-file: /path/your-tunnels-credentials-file.json
warp-routing:
    enabled: true

​​ Ingress rules

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:

1. cd into your system’s default directory for cloudflared.
2. Open vim and type in the necessary keys and values.
3. Name and save your file by typing :wq config.yaml and 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.yaml or config.yml file in the default cloudflared directory.

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.

1. Have a cloudflared instance running with the original version of the configuration file.
2. Start a cloudflared replica running with the updated version of the configuration file.
3. Wait for the replica to be fully running and usable.
4. Stop the first instance of cloudflared.

Your cloudflared will now be running with the updated version of your configuration file.