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 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 true
:
tunnel: The tunnel UUIDcredentials-file: /path/your-tunnels-credentials-file.jsonwarp-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:
cd
into your system’s default directory forcloudflared
.- Open vim and type in the necessary keys and values.
- 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.
- Have a
cloudflared
instance running with the original version of the configuration file. - Start a
cloudflared
replica 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
.
Your cloudflared
will now be running with the updated version of your configuration file.