diff --git a/docs/http/_http_header_templates.mdx b/docs/http/_http_header_templates.mdx index 140d4559bb..b40097652d 100644 --- a/docs/http/_http_header_templates.mdx +++ b/docs/http/_http_header_templates.mdx @@ -42,44 +42,65 @@ These variables are only populated when using the Compression module. #### Connection Variables {#conn} -| | | -| ---------------------- | ----------------------------------------------------------------------------------------------- | -| `${.conn.bytes_in}` | The number of bytes arriving at an endpoint from the frontend. | -| `${.conn.bytes_out}` | The number of bytes leaving an endpoint to the frontend. | -| `${.conn.client_ip}` | The source IP of the TCP connection to the ngrok edge. | -| `${.conn.duration}` | The total duration (in seconds) of the TCP connection between the ngrok endpoint and the agent. | -| `${.conn.end_ts}` | The timestamp when the TCP connection to the ngrok edge is closed. | -| `${.conn.id}` | The ngrok ID for this TCP connection. | -| `${.conn.server_ip}` | The IP address of the server that received the request. | -| `${.conn.server_name}` | The hostname associated with this connection. | -| `${.conn.server_port}` | The port that the connection for this request came in on. | -| `${.conn.start_ts}` | The timestamp when the TCP connection to the ngrok edge is established. | +| | | +| --------------------- | ---------------------------------------------------------- | +| `${conn.bytes_in}` | The number of bytes entering the endpoint from the client. | +| `${conn.bytes_out}` | The number of bytes leaving an endpoint to the client. | +| `${conn.client_ip}` | Source IP of the connection to the ngrok endpoint. | +| `${conn.end_ts}` | Timestamp when the connection to ngrok was closed. | +| `${conn.server_ip}` | The IP that this connection was established on. | +| `${conn.server_port}` | The port that this connection was established on. | +| `${conn.start_ts}` | Timestamp when the connection to ngrok was started. | #### Geo IP Variables {#ngrok-geo} The source of this data is subject to change. It is currently provided by [MaxMind GeoIP](https://www.maxmind.com/en/home). -| | | -| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- | -| `${.ngrok.geo.country_code}` | This is the two-letter ISO country code based on the client IP. | -| `${.ngrok.geo.lat_long_radius_km}` | This is the radius in kilometers around the latitude and longitude where the client IP is likely to originate. | -| `${.ngrok.geo.latitude}` | This is the approximate latitude based on the client IP. | -| `${.ngrok.geo.longitude}` | This is the approximate longitude based on the client IP. | - -#### HTTP Variables {#http} - -| | | -| ------------------------------- | --------------------------------------------------------------------------- | -| `${.http.request_id}` | The unique ngrok-assigned ID of this request. | -| `${.http.request.method}` | The request method, normalized to uppercase. | -| `${.http.request.url.host}` | The host component of the request URL. | -| `${.http.request.url.path}` | The path component of the request URL | -| `${.http.request.url.query}` | The query string component of the request URL | -| `${.http.request.url.raw}` | The full URL of the request including scheme, host, path, and query string. | -| `${.http.request.url.scheme}` | The scheme component of the request URL. | -| `${.http.request.user_agent}` | The value of the User-Agent header in the request received by ngrok edge. | -| `${.http.request.version}` | The HTTP version used in the request. | -| `${.http.response.status_code}` | The status code of the response returned by the ngrok edge. | +| | | +| -------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `${conn.geo.city}` | The name of the city, in EN, where the `conn.client_ip` is likely to originate. | +| `${conn.geo.country}` | The name of the country, in EN, where the `conn.client_ip` is likely to originate. | +| `${conn.geo.country_code}` | The two-letter ISO country code where the `conn.client_ip` is likely to originate. | +| `${conn.geo.latitude}` | The approximate latitude where the `conn.client_ip` is likely to originate. | +| `${conn.geo.longitude}` | The approximate longitude where the `conn.client_ip` is likely to originate. | +| `${conn.geo.radius}` | The radius in kilometers around the latitude and longitude where the `conn.client_ip` is likely to originate. | +| `${conn.geo.subdivision}` | The name of the subdivision, in EN, where the `conn.client_ip` is likely to originate. | + +#### HTTP Request and Response Variables {#http} + +| | | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `${req.content_length}` | The content length of the body in bytes. This may not be present if the request does not contain a body or if the client does not specify a content length because they are streaming the body. | +| `${req.content_type}` | The media type set in the Content-Type header for this request as a string. | +| `${req.content_type.parameters}` | The parameters set in the Content-Type header as a key value map. | +| `${req.content_type.raw}` | The Content-Type header for this request as a string. | +| `${req.cookies}` | The key value map of HTTP cookie objects provided in the request. | +| `${req.headers}` | The request headers parsed as a map of lower-case names to values. | +| `${req.host}` | The host header field value for this request. | +| `${req.location}` | The location header value of the request. | +| `${req.method}` | The request method. | +| `${req.trailers}` | The request trailers parsed as a map of lower-case names to values. | +| `${req.url}` | The normalized full URL for this request. | +| `${req.url.authority}` | The authority portion of the URL. | +| `${req.url.host}` | The host for this request. | +| `${req.url.path}` | The path for this request including the leading forward slash. | +| `${req.url.query}` | The full query string for this request excluding the leading question mark. | +| `${req.url.query_params}` | The request query string parsed as a map of names to values. | +| `${req.url.raw_path}` | The un-normalized path including the leading slash for this request. | +| `${req.url.scheme}` | The scheme for this request. | +| `${req.url.uri}` | The URI (path and query) portion of the URL. | +| `${req.url.user}` | The user:password portion of the URL. | +| `${req.user_agent}` | The user-agent header value for this request. | +| `${req.version}` | The HTTP version for this request. | +| `${res.content_length}` | The length of the content associated with the response. | +| `${res.content_type}` | The media type set in the Content-Type header for this response as a string. | +| `${res.content_type.parameters}` | The parameters set in the Content-Type header for this response as a key value map. | +| `${res.content_type.raw}` | The Content-Type header for this response as a string. | +| `${res.cookies}` | The key value map of HTTP cookie objects provided in the response. | +| `${res.headers}` | The response headers parsed as a map of lower-case names to values. | +| `${res.location}` | The location header value of this response. | +| `${res.status_code}` | The status code of this response. | +| `${res.trailers}` | The response trailers parsed as a map of lower-case names to values. | #### IP Restrictions Variables {#ip-restrictions} @@ -94,11 +115,36 @@ These variables are only populated when using the IP Restrictions module. These variables are only populated when using the Mutual TLS module. -| | | -| ----------------------------------- | ----------------------------------------------------------------------------------------- | -| `${.tls.client_cert.serial_number}` | The serial number of the client's leaf TLS certificate in the Mutual TLS handshake. | -| `${.tls.client_cert.subject.cn}` | The subject common name of the client's leaf TLS certificate in the Mutual TLS handshake. | -| `${.tls.client_cert.subject}` | The subject of the client's leaf TLS certificate in the Mutual TLS handshake | +| | | +| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `${conn.tls.client.extensions}` | Additional information added to the certificate. | +| `${conn.tls.client.issuer}` | The issuing authority of the certificate as a string roughly following the RFC 2253 Distinguished Names syntax. | +| `${conn.tls.client.issuer.common_name}` | Common name of the issuing authority, usually the domain name. | +| `${conn.tls.client.issuer.country}` | Country name(s) where the issuing authority is located. | +| `${conn.tls.client.issuer.locality}` | Locality or city of the issuing authority. | +| `${conn.tls.client.issuer.organization}` | Name(s) of the organization that issued the certificate. | +| `${conn.tls.client.issuer.organizational_unit}` | Division of the organization responsible for the certificate. | +| `${conn.tls.client.issuer.postal_code}` | Postal code of the issuing authority. | +| `${conn.tls.client.issuer.province}` | Province or state of the issuing authority. | +| `${conn.tls.client.issuer.street_address}` | Street address of the issuing authority. | +| `${conn.tls.client.san}` | Subject alternative names of the client certificate. | +| `${conn.tls.client.san.dns_names}` | DNS names in the subject alternative names. | +| `${conn.tls.client.san.email_addresses}` | Email addresses in the subject alternative names. | +| `${conn.tls.client.san.ip_addresses}` | IP addresses in the subject alternative names. | +| `${conn.tls.client.san.uris}` | URIs in the subject alternative names. | +| `${conn.tls.client.serial_number}` | Unique identifier for the certificate. | +| `${conn.tls.client.signature_algorithm}` | Algorithm used to sign the certificate. | +| `${conn.tls.client.subject}` | The entity to whom the certificate is issued as a string roughly following the RFC 2253 Distinguished Names syntax. | +| `${conn.tls.client.subject.common_name}` | Common name of the subject, usually the domain name. | +| `${conn.tls.client.subject.country}` | Country name(s) where the subject of the certificate is located. | +| `${conn.tls.client.subject.locality}` | Locality or city where the subject is located. | +| `${conn.tls.client.subject.organization}` | Name(s) of the organization to which the subject belongs. | +| `${conn.tls.client.subject.organizational_unit}` | Division of the organization to which the subject belongs. | +| `${conn.tls.client.subject.postal_code}` | Postal code where the subject is located. | +| `${conn.tls.client.subject.province}` | Province or state where the subject is located. | +| `${conn.tls.client.subject.street_address}` | Street address where the subject is located. | +| `${conn.tls.client.validity.not_after}` | Expiration date and time when the certificate is no longer valid. | +| `${conn.tls.client.validity.not_before}` | Start date and time when the certificate becomes valid. | #### ngrok Variables {#ngrok-variables} @@ -144,10 +190,39 @@ These variables are only populated when using the SAML module. These variables are only populated on requests to HTTPS endpoints. -| | | -| ---------------------- | --------------------------------------------------------------------------- | -| `${.tls.cipher_suite}` | The cipher suite selected during the TLS handshake. | -| `${.tls.version}` | The version of the TLS protocol used between the client and the ngrok edge. | +| | | +| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `${conn.tls.cipher_suite}` | The cipher suite selected during the TLS handshake. | +| `${conn.tls.server.extensions}` | Additional information added to the certificate. | +| `${conn.tls.server.issuer}` | The issuing authority of the certificate as a string roughly following the RFC 2253 Distinguished Names syntax. | +| `${conn.tls.server.issuer.common_name}` | Common name of the issuing authority, usually the domain name. | +| `${conn.tls.server.issuer.country}` | Country name(s) where the issuing authority is located. | +| `${conn.tls.server.issuer.locality}` | Locality or city of the issuing authority. | +| `${conn.tls.server.issuer.organization}` | Name(s) of the organization that issued the certificate. | +| `${conn.tls.server.issuer.organizational_unit}` | Division of the organization responsible for the certificate. | +| `${conn.tls.server.issuer.postal_code` | Postal code of the issuing authority. | +| `${conn.tls.server.issuer.province` | Province or state of the issuing authority. | +| `${conn.tls.server.issuer.street_address` | Street address of the issuing authority. | +| `${conn.tls.server.san}` | Subject alternative names of the ngrok server's leaf TLS certificate. | +| `${conn.tls.server.san.dns_names}` | DNS names in the subject alternative names of the ngrok server's leaf TLS certificate. | +| `${conn.tls.server.san.email_addresses}` | Email addresses in the subject alternative names of the ngrok server's leaf TLS certificate. | +| `${conn.tls.server.san.ip_addresses}` | IP addresses in the subject alternative names of the ngrok server's leaf TLS certificate. | +| `${conn.tls.server.san.uris}` | URIs in the subject alternative names of the ngrok server's leaf TLS certificate. | +| `${conn.tls.server.serial_number}` | Unique identifier for the certificate. | +| `${conn.tls.server.signature_algorithm}` | Algorithm used to sign the certificate. | +| `${conn.tls.server.subject}` | The entity to whom the certificate is issued as a string roughly following the RFC 2253 Distinguished Names syntax. | +| `${conn.tls.server.subject.common_name}` | Common name of the subject, usually the domain name. | +| `${conn.tls.server.subject.country}` | Country name(s) where the subject of the certificate is located. | +| `${conn.tls.server.subject.locality}` | Locality or city where the subject is located. | +| `${conn.tls.server.subject.organization}` | Name(s) of the organization to which the subject belongs. | +| `${conn.tls.server.subject.organizational_unit}` | Division of the organization to which the subject belongs. | +| `${conn.tls.server.subject.postal_code}` | Postal code where the subject is located. | +| `${conn.tls.server.subject.province}` | Province or state where the subject is located. | +| `${conn.tls.server.subject.street_address}` | Street address where the subject is located. | +| `${conn.tls.server.validity.not_after}` | Expiration date and time when the certificate is no longer valid. | +| `${conn.tls.server.validity.not_before}` | Start date and time when the certificate becomes valid. | +| `${conn.tls.sni}` | The hostname included in the ClientHello message via the SNI extension. | +| `${conn.tls.version}` | The version of the TLS protocol used between the client and the ngrok edge. | #### Webhook Verification Variables {#webhook-verification} diff --git a/docs/http/request-headers.mdx b/docs/http/request-headers.mdx index 0381ef4c90..882841575f 100644 --- a/docs/http/request-headers.mdx +++ b/docs/http/request-headers.mdx @@ -64,7 +64,7 @@ For example to include geographical data about the client IP that initiated the request, you may construct a header value like so. ```bash -ngrok http 80 --request-header-add 'country: ${.ngrok.geo.country_code}' +ngrok http 80 --request-header-add 'country: ${conn.geo.country_code}' ``` If you are specifying variable interpolation from the command line, make sure @@ -245,7 +245,7 @@ with `Ctrl+C` and then restart ngrok with a new command. ngrok http https://httpbin.org \ --domain your-domain.ngrok.app \ --request-header-remove='user-agent' \ - --request-header-add='country: ${.ngrok.geo.country_code}' + --request-header-add='country: ${conn.geo.country_code}' ``` Then curl your endpoint again to see how the request headers have been updated: diff --git a/examples/actions/add-headers.mdx b/examples/actions/add-headers.mdx index 9416c68765..be0e2013f3 100644 --- a/examples/actions/add-headers.mdx +++ b/examples/actions/add-headers.mdx @@ -4,7 +4,7 @@ export const type = "add-headers"; export const config = { headers: { "is-ngrok": "1", - country: "${.ngrok.geo.country_code}", + country: "${conn.geo.country_code}", }, }; diff --git a/examples/agent-cli/http-request-headers.mdx b/examples/agent-cli/http-request-headers.mdx index 4146565f3b..21da658c71 100644 --- a/examples/agent-cli/http-request-headers.mdx +++ b/examples/agent-cli/http-request-headers.mdx @@ -1,6 +1,6 @@ ```bash ngrok http 80 \ --request-header-add='is-ngrok: 1' \ - --request-header-add='country: ${.ngrok.geo.country_code}' \ + --request-header-add='country: ${conn.geo.country_code}' \ --request-header-remove='referrer' ``` diff --git a/examples/agent-config/http-request-headers.mdx b/examples/agent-config/http-request-headers.mdx index 659e35f93b..6efb1b9eab 100644 --- a/examples/agent-config/http-request-headers.mdx +++ b/examples/agent-config/http-request-headers.mdx @@ -4,6 +4,6 @@ tunnels: proto: http addr: 80 request_header: - add: ["is-ngrok: 1", "country: ${.ngrok.geo.country_code}"] + add: ["is-ngrok: 1", "country: ${conn.geo.country_code}"] remove: ["referrer"] ``` diff --git a/examples/go-sdk/http-request-headers.mdx b/examples/go-sdk/http-request-headers.mdx index 58db0cc065..b41b6a39ae 100644 --- a/examples/go-sdk/http-request-headers.mdx +++ b/examples/go-sdk/http-request-headers.mdx @@ -11,7 +11,7 @@ func ngrokListener(ctx context.Context) (net.Listener, error) { return ngrok.Listen(ctx, config.HTTPEndpoint( config.WithRequestHeader("is-ngrok", "1"), - config.WithRequestHeader("country", "${.ngrok.geo.country_code}"), + config.WithRequestHeader("country", "${conn.geo.country_code}"), config.WithRemoveRequestHeader("referrer"), ), ngrok.WithAuthtokenFromEnv(), diff --git a/examples/javascript-sdk/http-request-headers.mdx b/examples/javascript-sdk/http-request-headers.mdx index ebd3c9cadc..b0d0c79e10 100644 --- a/examples/javascript-sdk/http-request-headers.mdx +++ b/examples/javascript-sdk/http-request-headers.mdx @@ -5,7 +5,7 @@ const ngrok = require("@ngrok/ngrok"); const listener = await ngrok.forward({ addr: 8080, authtoken_from_env: true, - request_header_add: ["is-ngrok:1", "country:${.ngrok.geo.country_code}"], + request_header_add: ["is-ngrok:1", "country:${conn.geo.country_code}"], request_header_remove: "referrer", }); diff --git a/examples/k8s/http-request-headers.mdx b/examples/k8s/http-request-headers.mdx index 1ebc408c2d..e9047bbb2c 100644 --- a/examples/k8s/http-request-headers.mdx +++ b/examples/k8s/http-request-headers.mdx @@ -8,7 +8,7 @@ modules: request: add: is-ngrok: "1" - country: "${.ngrok.geo.country_code}" + country: "${conn.geo.country_code}" remove: ["referrer"] --- apiVersion: networking.k8s.io/v1 diff --git a/examples/python-sdk/http-request-headers.mdx b/examples/python-sdk/http-request-headers.mdx index 57c5d83363..9e234fd009 100644 --- a/examples/python-sdk/http-request-headers.mdx +++ b/examples/python-sdk/http-request-headers.mdx @@ -2,7 +2,7 @@ import ngrok listener = ngrok.forward("localhost:8080", authtoken_from_env=True, - request_header_add=["is-ngrok:1", "country:${.ngrok.geo.country_code}"], + request_header_add=["is-ngrok:1", "country:${conn.geo.country_code}"], request_header_remove="referrer") print(f"Ingress established at: {listener.url()}"); diff --git a/examples/rust-sdk/http-request-headers.mdx b/examples/rust-sdk/http-request-headers.mdx index c7b789fd28..a76068987f 100644 --- a/examples/rust-sdk/http-request-headers.mdx +++ b/examples/rust-sdk/http-request-headers.mdx @@ -10,7 +10,7 @@ async fn listen_ngrok() -> anyhow::Result { let tun = sess .http_endpoint() .request_header("is-ngrok", "1") - .request_header("country", "${.ngrok.geo.country_code}") + .request_header("country", "${conn.geo.country_code}") .remove_request_header("referrer") .listen() .await?; diff --git a/examples/ssh/http-request-headers.mdx b/examples/ssh/http-request-headers.mdx index 9a9e6d339a..9a041518c7 100644 --- a/examples/ssh/http-request-headers.mdx +++ b/examples/ssh/http-request-headers.mdx @@ -1,6 +1,6 @@ ```bash ssh -R 443:localhost:80 v2@connect.ngrok-agent.com http \ --request-header-add='is-ngrok: 1' \ - --request-header-add='country: ${.ngrok.geo.country_code}' \ + --request-header-add='country: ${conn.geo.country_code}' \ --request-header-remove='referrer' ``` diff --git a/src/components/VariableInterpolation.tsx b/src/components/VariableInterpolation.tsx index cdcdc7e667..72e6aca4d1 100644 --- a/src/components/VariableInterpolation.tsx +++ b/src/components/VariableInterpolation.tsx @@ -3,7 +3,7 @@ import ConfigExample from "../../src/components/ConfigExample.tsx"; export const config = { headers: { - country: "${.ngrok.geo.country_code}", + country: "${conn.geo.country_code}", }, };