Interface Config

Configuration object to pass to ngrok.forward()

interface Config {
    addr?: string | number;
    allow_user_agent?: string | string[];
    app_protocol?: string;
    auth?: string | string[];
    authtoken?: string;
    authtoken_from_env?: boolean;
    basic_auth?: string | string[];
    binPath?: string;
    circuit_breaker?: number;
    compression?: boolean;
    configPath?: string;
    crt?: string;
    deny_user_agent?: string | string[];
    domain?: string;
    force_new_session?: boolean;
    forwards_to?: string;
    host?: string;
    host_header?: string;
    hostname?: string;
    inspect?: string;
    ip_restriction_allow_cidrs?: string | string[];
    ip_restriction_deny_cidrs?: string | string[];
    key?: string;
    labels?: string | string[];
    metadata?: string;
    mutual_tls_cas?: string | string[];
    name?: string;
    oauth_allow_domains?: string | string[];
    oauth_allow_emails?: string | string[];
    oauth_client_id?: string;
    oauth_client_secret?: string;
    oauth_provider?: string;
    oauth_scopes?: string | string[];
    oidc_allow_domains?: string | string[];
    oidc_allow_emails?: string | string[];
    oidc_client_id?: string;
    oidc_client_secret?: string;
    oidc_issuer_url?: string;
    oidc_scopes?: string | string[];
    onLogEvent?: (data: string) => void;
    onStatusChange?: (status: string) => void;
    policy?: string;
    port?: number;
    proto?: string;
    proxy_proto?: string;
    region?: string;
    remote_addr?: string;
    request_header_add?: string | string[];
    request_header_remove?: string | string[];
    response_header_add?: string | string[];
    response_header_remove?: string | string[];
    root_cas?: string;
    schemes?: string | string[];
    server_addr?: string;
    session_ca_cert?: string;
    session_metadata?: string;
    subdomain?: string;
    terminate_at?: string;
    traffic_policy?: string;
    verify_upstream_tls?: boolean;
    verify_webhook_provider?: string;
    verify_webhook_secret?: string;
    web_addr?: string;
    websocket_tcp_converter?: boolean;
}

Index

Properties

addr? allow_user_agent? app_protocol? auth? authtoken? authtoken_from_env? basic_auth? binPath? circuit_breaker? compression? configPath? crt? deny_user_agent? domain? force_new_session? forwards_to? host? host_header? hostname? inspect? ip_restriction_allow_cidrs? ip_restriction_deny_cidrs? key? labels? metadata? mutual_tls_cas? name? oauth_allow_domains? oauth_allow_emails? oauth_client_id? oauth_client_secret? oauth_provider? oauth_scopes? oidc_allow_domains? oidc_allow_emails? oidc_client_id? oidc_client_secret? oidc_issuer_url? oidc_scopes? onLogEvent? onStatusChange? policy? port? proto? proxy_proto? region? remote_addr? request_header_add? request_header_remove? response_header_add? response_header_remove? root_cas? schemes? server_addr? session_ca_cert? session_metadata? subdomain? terminate_at? traffic_policy? verify_upstream_tls? verify_webhook_provider? verify_webhook_secret? web_addr? websocket_tcp_converter?

Properties

`Optional`addr

addr?: string | number

Port, network address, url, or named pipe. Defaults to 80. Examples: "80", "localhost:8080", "https://192.168.1.100:8443", "unix:/tmp/my.sock", "pipe://./my-pipe"

`Optional`allow_user_agent

allow_user_agent?: string | string[]

A set of regular expressions used to match User-Agents that will be allowed. On request, the User Agent Filter module will check the incoming User-Agent header value against the list of defined allow and deny regular expression rules. See User Agent Filter_ in the ngrok docs for additional details.

.. _User Agent Filter: https://ngrok.com/docs/cloud-edge/modules/user-agent-filter/

`Optional`app_protocol

app_protocol?: string

The L7 application protocol to use for this edge, e.g. "http2" or "http1".

`Optional`auth

auth?: string | string[]

`Optional`authtoken

authtoken?: string

Configures the session to authenticate with the provided authtoken. You can find your existing authtoken or create a new one in the ngrok dashboard.

See the authtoken parameter in the ngrok docs for additional details.

`Optional`authtoken_from_env

authtoken_from_env?: boolean

Shortcut for calling [SessionBuilder::authtoken] with the value of the NGROK_AUTHTOKEN environment variable.

`Optional`basic_auth

basic_auth?: string | string[]

Credentials for basic authentication, with username and password colon separated.

`Optional`binPath

binPath?: string

Unused, will warn and be ignored

`Optional`circuit_breaker

circuit_breaker?: number

Reject requests when 5XX responses exceed this ratio. Disabled when 0. See Circuit Breaker in the ngrok docs for additional details.

`Optional`compression

compression?: boolean

Enable gzip compression for HTTP responses. See Compression in the ngrok docs for additional details.

`Optional`configPath

configPath?: string

Unused, will warn and be ignored

`Optional`crt

crt?: string

The certificate to use for TLS termination at the ngrok edge in PEM format. Only used if "proto" is "tls". See TLS Termination in the ngrok docs for additional details.

`Optional`deny_user_agent

deny_user_agent?: string | string[]

A set of regular expressions used to match User-Agents that will be denied. On request, the User Agent Filter module will check the incoming User-Agent header value against the list of defined allow and deny regular expression rules. See User Agent Filter_ in the ngrok docs for additional details.

.. _User Agent Filter: https://ngrok.com/docs/cloud-edge/modules/user-agent-filter/

`Optional`domain

domain?: string

The domain to request for this edge, any valid domain or hostname that you have previously registered with ngrok. If using a custom domain, this requires registering in the ngrok dashboard and setting a DNS CNAME value.

`Optional`force_new_session

force_new_session?: boolean

Force a new session connection to be made.

`Optional`forwards_to

forwards_to?: string

Returns a human-readable string presented in the ngrok dashboard and the API.

`Optional`host

host?: string

The hostname for the listener to forward to. Only used if addr is not defined.

`Optional`host_header

host_header?: string

Unused, will warn and be ignored

`Optional`hostname

hostname?: string

Synonym for domain

`Optional`inspect

inspect?: string

Unused, will warn and be ignored

`Optional`ip_restriction_allow_cidrs

ip_restriction_allow_cidrs?: string | string[]

Restriction placed on the origin of incoming connections to the edge to only allow these CIDR ranges.

`Optional`ip_restriction_deny_cidrs

ip_restriction_deny_cidrs?: string | string[]

Restriction placed on the origin of incoming connections to the edge to deny these CIDR ranges.

`Optional`key

key?: string

The certificate to use for TLS termination at the ngrok edge in PEM format. Only used if "proto" is "tls". See TLS Termination in the ngrok docs for additional details.

`Optional`labels

labels?: string | string[]

Add label, value pairs for this listener, colon separated.

`Optional`metadata

metadata?: string

Listener-specific opaque metadata. Viewable via the API.

`Optional`mutual_tls_cas

mutual_tls_cas?: string | string[]

Certificates to use for client authentication at the ngrok edge. Only used if "proto" is "tls" or "http". See Mutual TLS in the ngrok docs for additional details.

`Optional`name

name?: string

Unused, will warn and be ignored

`Optional`oauth_allow_domains

oauth_allow_domains?: string | string[]

OAuth configuration of domains to allow. See OAuth in the ngrok docs for additional details.

`Optional`oauth_allow_emails

oauth_allow_emails?: string | string[]

OAuth configuration of email addresses to allow. See OAuth in the ngrok docs for additional details.

`Optional`oauth_client_id

oauth_client_id?: string

OAuth configuration of client ID. Required for scopes. See OAuth in the ngrok docs for additional details.

`Optional`oauth_client_secret

oauth_client_secret?: string

OAuth configuration of client secret. Required for scopes. See OAuth in the ngrok docs for additional details.

`Optional`oauth_provider

oauth_provider?: string

OAuth configuration of the provider, e.g. "google". See OAuth in the ngrok docs for additional details.

`Optional`oauth_scopes

oauth_scopes?: string | string[]

OAuth configuration of scopes. See OAuth in the ngrok docs for additional details.

`Optional`oidc_allow_domains

oidc_allow_domains?: string | string[]

OIDC configuration of domains to allow. See OpenID Connect in the ngrok docs for additional details.

`Optional`oidc_allow_emails

oidc_allow_emails?: string | string[]

OIDC configuration of email addresses to allow. See OpenID Connect in the ngrok docs for additional details.

`Optional`oidc_client_id

oidc_client_id?: string

OIDC configuration of client ID. See OpenID Connect in the ngrok docs for additional details.

`Optional`oidc_client_secret

oidc_client_secret?: string

OIDC configuration of client secret. See OpenID Connect in the ngrok docs for additional details.

`Optional`oidc_issuer_url

oidc_issuer_url?: string

OIDC configuration of the issuer URL. See OpenID Connect in the ngrok docs for additional details.

`Optional`oidc_scopes

oidc_scopes?: string | string[]

OIDC configuration of scopes. See OpenID Connect in the ngrok docs for additional details.

`Optional`onLogEvent

onLogEvent?: (data: string) => void

Returns log messages from the ngrok library.

`Optional`onStatusChange

onStatusChange?: (status: string) => void

'closed' - connection is lost, 'connected' - reconnected

`Optional`policy

policy?: string

DEPRECATED: use TrafficPolicy instead.

`Optional`port

port?: number

The port for the listener to forward to. Only used if addr is not defined.

`Optional`proto

proto?: string

The type of listener to use, one of http|tcp|tls|labeled, defaults to http.

`Optional`proxy_proto

proxy_proto?: string

The version of PROXY protocol to use with this listener "1", "2", or "" if not using.

`Optional`region

region?: string

Unused, will warn and be ignored

`Optional`remote_addr

remote_addr?: string

The TCP address to request for this edge. These addresses can be reserved in the ngrok dashboard to use across sessions. For example: remote_addr("2.tcp.ngrok.io:21746") Only used if proto is "tcp".

`Optional`request_header_add

request_header_add?: string | string[]

Adds a header to all requests to this edge. See Request Headers in the ngrok docs for additional details.

`Optional`request_header_remove

request_header_remove?: string | string[]

Removes a header from requests to this edge. See Request Headers in the ngrok docs for additional details.

`Optional`response_header_add

response_header_add?: string | string[]

Adds a header to all responses coming from this edge. See Response Headers in the ngrok docs for additional details.

`Optional`response_header_remove

response_header_remove?: string | string[]

Removes a header from responses from this edge. See Response Headers in the ngrok docs for additional details.

`Optional`root_cas

root_cas?: string

Sets the file path to a default certificate in PEM format to validate ngrok Session TLS connections. Setting to "trusted" is the default, using the ngrok CA certificate. Setting to "host" will verify using the certificates on the host operating system. A client config set via tls_config after calling root_cas will override this value.

Corresponds to the root_cas parameter in the ngrok docs

`Optional`schemes

schemes?: string | string[]

The scheme that this edge should use. "HTTPS" or "HTTP", defaults to "HTTPS". If multiple are given only the last one is used.

`Optional`server_addr

server_addr?: string

Configures the network address to dial to connect to the ngrok service. Use this option only if you are connecting to a custom agent ingress.

See the server_addr parameter in the ngrok docs for additional details.

`Optional`session_ca_cert

session_ca_cert?: string

Configures the TLS certificate used to connect to the ngrok service while establishing the session. Use this option only if you are connecting through a man-in-the-middle or deep packet inspection proxy. Pass in the bytes of the certificate to be used to validate the connection, then override the address to connect to via the server_addr call.

Roughly corresponds to the root_cas parameter in the ngrok docs.

`Optional`session_metadata

session_metadata?: string

Configures the opaque, machine-readable metadata string for this session. Metadata is made available to you in the ngrok dashboard and the Agents API resource. It is a useful way to allow you to uniquely identify sessions. We suggest encoding the value in a structured format like JSON.

See the metdata parameter in the ngrok docs for additional details.

`Optional`subdomain

subdomain?: string

Unused, use domain instead, will warn and be ignored

`Optional`terminate_at

terminate_at?: string

Unused, will warn and be ignored

`Optional`traffic_policy

traffic_policy?: string

The Traffic Policy to use for this endpoint.

`Optional`verify_upstream_tls

verify_upstream_tls?: boolean

Whether to disable certificate verification for this listener

`Optional`verify_webhook_provider

verify_webhook_provider?: string

WebhookVerification configuration, the provider to use. See Webhook Verification in the ngrok docs for additional details.

`Optional`verify_webhook_secret

verify_webhook_secret?: string

WebhookVerification configuration, the secret to use. See Webhook Verification in the ngrok docs for additional details.

`Optional`web_addr

web_addr?: string

Unused, will warn and be ignored

`Optional`websocket_tcp_converter

websocket_tcp_converter?: boolean

Convert incoming websocket connections to TCP-like streams.

Interface Config

Index

Properties

Properties

Optionaladdr

Optionalallow_user_agent

Optionalapp_protocol

Optionalauth

Optionalauthtoken

Optionalauthtoken_from_env

Optionalbasic_auth

OptionalbinPath

Optionalcircuit_breaker

Optionalcompression

OptionalconfigPath

Optionalcrt

Optionaldeny_user_agent

Optionaldomain

Optionalforce_new_session

Optionalforwards_to

Optionalhost

Optionalhost_header

Optionalhostname

Optionalinspect

Optionalip_restriction_allow_cidrs

Optionalip_restriction_deny_cidrs

Optionalkey

Optionallabels

Optionalmetadata

Optionalmutual_tls_cas

Optionalname

Optionaloauth_allow_domains

Optionaloauth_allow_emails

Optionaloauth_client_id

Optionaloauth_client_secret

Optionaloauth_provider

Optionaloauth_scopes

Optionaloidc_allow_domains

Optionaloidc_allow_emails

Optionaloidc_client_id

Optionaloidc_client_secret

Optionaloidc_issuer_url

Optionaloidc_scopes

OptionalonLogEvent

OptionalonStatusChange

Optionalpolicy

Optionalport

Optionalproto

Optionalproxy_proto

Optionalregion

Optionalremote_addr

Optionalrequest_header_add

Optionalrequest_header_remove

Optionalresponse_header_add

Optionalresponse_header_remove

Optionalroot_cas

Optionalschemes

Optionalserver_addr

Optionalsession_ca_cert

Optionalsession_metadata

Optionalsubdomain

Optionalterminate_at

Optionaltraffic_policy

Optionalverify_upstream_tls

Optionalverify_webhook_provider

Optionalverify_webhook_secret

Optionalweb_addr

Optionalwebsocket_tcp_converter

Settings

On This Page

`Optional`addr

`Optional`allow_user_agent

`Optional`app_protocol

`Optional`auth

`Optional`authtoken

`Optional`authtoken_from_env

`Optional`basic_auth

`Optional`binPath

`Optional`circuit_breaker

`Optional`compression

`Optional`configPath

`Optional`crt

`Optional`deny_user_agent

`Optional`domain

`Optional`force_new_session

`Optional`forwards_to

`Optional`host

`Optional`host_header

`Optional`hostname

`Optional`inspect

`Optional`ip_restriction_allow_cidrs

`Optional`ip_restriction_deny_cidrs

`Optional`key

`Optional`labels

`Optional`metadata

`Optional`mutual_tls_cas

`Optional`name

`Optional`oauth_allow_domains

`Optional`oauth_allow_emails

`Optional`oauth_client_id

`Optional`oauth_client_secret

`Optional`oauth_provider

`Optional`oauth_scopes

`Optional`oidc_allow_domains

`Optional`oidc_allow_emails

`Optional`oidc_client_id

`Optional`oidc_client_secret

`Optional`oidc_issuer_url

`Optional`oidc_scopes

`Optional`onLogEvent

`Optional`onStatusChange

`Optional`policy

`Optional`port

`Optional`proto

`Optional`proxy_proto

`Optional`region

`Optional`remote_addr

`Optional`request_header_add

`Optional`request_header_remove

`Optional`response_header_add

`Optional`response_header_remove

`Optional`root_cas

`Optional`schemes

`Optional`server_addr

`Optional`session_ca_cert

`Optional`session_metadata

`Optional`subdomain

`Optional`terminate_at

`Optional`traffic_policy

`Optional`verify_upstream_tls

`Optional`verify_webhook_provider

`Optional`verify_webhook_secret

`Optional`web_addr

`Optional`websocket_tcp_converter