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"