Request Headers
Overview
This module adds and removes headers from HTTP requests before they are sent to your upstream service. This is useful for providing additional data to upstream services about the behavior of the ngrok edge.
Changes made to request headers will not be visible to other modules; they will only be seen by your upstream service.
You may interpolate variables into header values to make them dynamic.
Example Usage
- Agent CLI
- Agent Config
- SSH
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
ngrok http 80 \
--request-header-add='is-ngrok: 1' \
--request-header-add='country: ${conn.geo.country_code}' \
--request-header-remove='referrer'
tunnels:
example:
proto: http
addr: 80
request_header:
add: ["is-ngrok: 1", "country: ${conn.geo.country_code}"]
remove: ["referrer"]
ssh -R 443:localhost:80 v2@connect.ngrok-agent.com http \
--request-header-add='is-ngrok: 1' \
--request-header-add='country: ${conn.geo.country_code}' \
--request-header-remove='referrer'
import (
"context"
"net"
"golang.ngrok.com/ngrok"
"golang.ngrok.com/ngrok/config"
)
func ngrokListener(ctx context.Context) (net.Listener, error) {
return ngrok.Listen(ctx,
config.HTTPEndpoint(
config.WithRequestHeader("is-ngrok", "1"),
config.WithRequestHeader("country", "${conn.geo.country_code}"),
config.WithRemoveRequestHeader("referrer"),
),
ngrok.WithAuthtokenFromEnv(),
)
}
Go Package Docs:
const ngrok = require("@ngrok/ngrok");
(async function () {
const listener = await ngrok.forward({
addr: 8080,
authtoken_from_env: true,
request_header_add: ["is-ngrok:1", "country:${conn.geo.country_code}"],
request_header_remove: "referrer",
});
console.log(`Ingress established at: ${listener.url()}`);
})();
Javascript SDK Docs:
- https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#request_header_add
- https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#request_header_remove
- https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#requestHeader
- https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#removeRequestHeader
import ngrok
listener = ngrok.forward("localhost:8080", authtoken_from_env=True,
request_header_add=["is-ngrok:1", "country:${conn.geo.country_code}"],
request_header_remove="referrer")
print(f"Ingress established at: {listener.url()}");
Python SDK Docs:
- https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.request_header
- [https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.remove_request_header] (https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.remove_request_header)
- https://ngrok.github.io/ngrok-python/index.html#full-configuration
use ngrok::prelude::*;
async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
let sess = ngrok::Session::builder()
.authtoken_from_env()
.connect()
.await?;
let tun = sess
.http_endpoint()
.request_header("is-ngrok", "1")
.request_header("country", "${conn.geo.country_code}")
.remove_request_header("referrer")
.listen()
.await?;
println!("Listening on URL: {:?}", tun.url());
Ok(tun)
}
Rust Crate Docs:
kind: NgrokModuleSet
apiVersion: ingress.k8s.ngrok.com/v1alpha1
metadata:
name: ngrok-module-set
modules:
headers:
request:
add:
is-ngrok: "1"
country: "${conn.geo.country_code}"
remove: ["referrer"]
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
annotations:
k8s.ngrok.com/modules: ngrok-module-set
spec:
ingressClassName: ngrok
rules:
- host: your-domain.ngrok.app
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
Behavior
Variable Interpolation
You may interpolate variables into header values. Variables are interpolated
into headers with JSONPath expressions surrounded by the ${}
syntax.
For example to include geographical data about the client IP that initiated the request, you may construct a header value like so.
ngrok http 80 --request-header-add 'country: ${conn.geo.country_code}'
If you are specifying variable interpolation from the command line, make sure to use single quotes for the command line argument otherwise it is likely that the shell will interpret your variable definition.
Consult the Variables Reference for the available variables.
Automatic Headers
Regardless of whether you enable the request headers module or not, ngrok adds default headers to every HTTP request.
You may remove these default headers with the request headers module. For example:
ngrok http 80 --request-header-remove "X-Forwarded-For,X-Forwarded-Host,X-Forwarded-Proto"
Multiple Header Values
HTTP headers may include the same header multiple times. You may add a header multiple times with different values and it will be added multiple times. For example:
ngrok http 80 --request-header-add "foo: bar" --request-header-add "foo: baz"
will result in a header with multiple values set
GET / HTTP/1.1
host: example.ngrok.app
foo: bar
foo: baz
There is a bug which currently causes the above behavior not to be correct. Only the last header will be used when specifying multiple headers. This behavior will be fixed to match what is documented above.
If you remove a header that has multiple values, all values will be removed.
Replacing Header Values
If you add a header that is already present in the HTTP request, it will add another header. For example, if you run:
ngrok http 80 --request-header-add "foo: new-value"
And the HTTP request was already:
GET / HTTP/1.1
host: example.ngrok.app
foo: original-value
The client will receive the following:
GET / HTTP/1.1
host: example.ngrok.app
foo: original-value
foo: new-value
If you wish to replace a header, you can combine header removal and addition to achieve that effect.
ngrok http 80 --request-header-remove "foo" --request-header-add "foo: new-value"
This will cause the HTTP request in this case to become:
GET / HTTP/1.1
host: example.ngrok.app
foo: new-value
Case Sensitivity
When adding headers, ngrok normalizes all header keys to a lower case representation per the http/2 RFC. See RFC 7540.
When removing headers, ngrok will remove any headers that match with a case-insensitive comparison.
Ordering
Request header changes made by other modules can be overridden by this module because this module is executed immediately before the HTTP request is transmitted to the upstream service.
Special Cases
- You may not add or remove the
user-agent
header. - You may not remove the
host
header without adding it with a different value. - Adding a
host
header will replace the existing value instead of adding a second value. - You may not use this module to add the
ngrok-skip-browser-warning
header to skip the ngrok browser warning on free accounts. For more information about the abuse interstitial, please check out the free plan limits guide.
Reference
Configuration
Parameter | Description |
---|---|
Added Headers | A list of header names to header values. Max 5. |
Removed Headers | A list of header names to remove. Max 5. |
Upstream Headers
This module adds the configured headers to requests sent to the upstream application.
Errors
This module does not return any errors.
Events
This module does not populate any fields in events.
Edges
Request Headers is an HTTPS Edge module which can be applied to Routes.
Pricing
This module is available on all plans.