The tunnel 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 .
In the absence of a configuration file,
cloudflared will proxy outbound traffic through port
File structure for private networks
tunnel: <Tunnel-UUID>credentials-file: /path/<Tunnel-UUID>.jsonwarp-routing:enabled: true
File structure for public hostnames
If you are exposing local services to the Internet, you can assign a public hostname to each service:
tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551efcredentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.jsoningress:- hostname: gitlab.widgetcorp.techservice: http://localhost:80- hostname: gitlab-ssh.widgetcorp.techservice: ssh://localhost:22- service: http_status:404
Configuration files that contain ingress rules must always include a catch-all rule that concludes the file. In this example,
cloudflared will respond with a
404 status code when the request does not match any of the previous hostnames.
How traffic is matched
cloudflared receives an incoming request, it evaluates each ingress rule from top to bottom to find which rule matches the request. Rules can match either the hostname or path of an incoming request, or both.
If a rule does not specify a hostname, all hostnames will be matched. If a rule does not specify a path, all paths will be matched.
The last ingress rule must be a catch-all rule that matches all traffic.
Here is an example configuration file that specifies several rules:
tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551efcredentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.jsoningress:# Rules map traffic from a hostname to a local service:- hostname: example.comservice: https://localhost:8000# Rules can match the request's path to a regular expression:- hostname: static.example.compath: \.(jpg|png|css|js)$service: https://localhost:8001# Rules can match the request's hostname to a wildcard character:- hostname: "*.example.com"service: https://localhost:8002# An example of a catch-all rule:- service: https://localhost:8003
In addition to HTTP,
cloudflared supports protocols like SSH, RDP, arbitrary TCP services, and Unix sockets. You can also route traffic to the built-in
Hello World test server or respond to traffic with an HTTP status.
tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551efcredentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.jsoningress:# Example of a request over TCP:- hostname: example.comservice: tcp://localhost:8000# Example of an HTTP request over a Unix socket:- hostname: staging.example.comservice: unix:/home/production/echo.sock# Example of a request mapping to the Hello World test server:- hostname: test.example.comservice: hello_world# Example of a rule responding to traffic with an HTTP status:- service: http_status:404
In the following example, the top-level configuration
connectTimeout: 30s sets a 30-second connection timeout for all services within that instance of
cloudflared. The ingress rule for
service: localhost:8002 then configures an exception to the top-level configuration by setting
connectTimeout for that service at
10s. The 30-second connection timeout still applies to all other services.
tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551efcredentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.jsonoriginRequest: # Top-level configurationconnectTimeout: 30singress:# The localhost:8000 service inherits all root-level configuration.# In other words, it will use a connectTimeout of 30 seconds.- hostname: example.comservice: localhost:8000- hostname: example2.comservice: localhost:8001# The localhost:8002 service overrides some root-level config.- service: localhost:8002originRequest:connectTimeout: 10sdisableChunkedEncoding: true# Some built-in services such as `http_status` do not use any configuration.# The service below will simply respond with HTTP 404.- service: http_status:404
Validate ingress rules
To validate the ingress rules in your configuration file, run:
$ cloudflared tunnel ingress validate
This will ensure that the set of ingress rules specified in your config file is valid.
Test ingress rules
To verify that
cloudflared will proxy the right traffic to the right local service, use
cloudflared tunnel ingress rule. This checks a URL against every rule, from first to last, and shows the first rule that matches. For example:
$ cloudflared tunnel ingress rule https://foo.example.comUsing rules from /usr/local/etc/cloudflared/config.ymlMatched rule #3hostname: *.example.comservice: https://localhost:8000
Update a configuration file
- 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.