From bbe325bf12f5860be58d7f3b3d2782e3cea90d97 Mon Sep 17 00:00:00 2001 From: "Kristopher Paulsen (K.C.)" Date: Mon, 9 Sep 2024 15:22:53 -0400 Subject: [PATCH] simpler docs (#921) Improved the docs around v3 config to: - Make it more obvious that many fields are now nested under `agent:` - Remove fields which should not be included in `agent configurations`, but are instead top level fields (eg. `version`) - Simplfy examples - Modify examples that include code snippets to explicitly nest relevant fields under `agent` - Remove the "full example config" and replace with various smaller configuration examples. --- docs/agent/config/_agent-configurations.mdx | 234 ------- docs/agent/config/v2.mdx | 237 ++++++- docs/agent/config/v3.mdx | 716 +++++++++----------- 3 files changed, 536 insertions(+), 651 deletions(-) delete mode 100644 docs/agent/config/_agent-configurations.mdx diff --git a/docs/agent/config/_agent-configurations.mdx b/docs/agent/config/_agent-configurations.mdx deleted file mode 100644 index 56864ed32..000000000 --- a/docs/agent/config/_agent-configurations.mdx +++ /dev/null @@ -1,234 +0,0 @@ -## Agent Configuration - -The following is a list of options that can be configured at the root of your configuration file and specify the behavior of the agent. - -| Name | Description | -| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [api_key](#api_key) | Specifies the ngrok API key used to connect to the ngrok API. This is only needed when using the `ngrok api` command and should not be confused with the authtoken. | -| [authtoken](#authtoken) | Specifies the authentication token (authtoken) used to connect to the ngrok service. | -| [connect_interface](#connect_interface) | Set the specific network interface for ngrok to use. This is only supported on Linux platforms. | -| [connect_timeout](#connect_timeout) | How long to wait when establishing an agent session connection to the ngrok service. The default is 10s. | -| [console_ui](#console_ui) | Enable/disable the console UI | -| [console_ui_color](#console_ui_color) | Set the background color of the console UI | -| [crl_noverify](#crl_noverify) | Disables verifying Certificate Revocation List | -| [dns_resolver_ips](#dns_resolver_ips) | Consult these DNS servers for tunnel session DNS resolution. | -| [heartbeat_interval](#heartbeat_interval) | How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. Default is 10s. | -| [heartbeat_tolerance](#heartbeat_tolerance) | Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. Default is 15s. | -| [inspect_db_size](#inspect_db_size) | The size in bytes of the upper limit on memory to allocate to save requests over HTTP tunnels for inspection and replay. | -| [log_level](#log_level) | Logging level of detail. In increasing order of verbosity, possible values are: `crit`, `warn`, `error`, `info`, and `debug`. | -| [log_format](#log_format) | Format of written log records. | -| [log](#log) | Write logs to this target destination. | -| [metadata](#metadata) | Opaque, user-supplied string that will be returned as part of the ngrok API response to the [list online sessions](/api/resources/tunnel-sessions) resource for all tunnels started by this agent. | -| [proxy_url](#proxy_url) | URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection. | -| [region](#region) _(Deprecated)_ | Choose the region where the ngrok agent will connect to host its tunnels. | -| [remote_management](#remote_management) | Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update). Defaults to `true`. | -| [root_cas](#root_cas) | The root certificate authorities used to validate the TLS connection to the ngrok server. | -| [server_addr](#server_addr) | This is the URL of the ngrok server to connect to. You should only set this if you are using a custom ingress URL. | -| [tunnels](#tunnels) | A map of names to tunnel definitions. See [V2 agent config tunnel definitions](/docs/agent/config/v2/#tunnel-configurations) for more details. | -| [update_channel](#update_channel) | The update channel determines the stability of released builds to update to. Use `stable` for all production deployments. | -| [update_check](#update_check) | This tells the ngrok agent if it should check for updates. Defaults to `true`. | -| [version](#version) | Specifies the version of the config file to use. | -| [web_addr](#web_addr) | Network address to bind on for serving the local web interface and api. | -| [web_allow_hosts](#web_allow_hosts) | Host headers to allow access for on the local web interface and api, can be a combination of IP's, CIDR ranges, and/or hostname suffixes. | - -### `api_key` - -This option specifies the API key used to access the ngrok API through the [`ngrok api`](/agent/cli#ngrok-api) command. This is only needed when using the [ngrok API](/api) and not the local ngrok agent API (available at `localhost:4040/api`). You can generate an API Key in the [ngrok Dashboard](https://dashboard.ngrok.com/api) and install it using the `ngrok config add-api-key` command. - -##### ngrok.yml specifying an API key - -```yaml -api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN -``` - -### `authtoken` - -This option specifies the authentication token (sometimes called tunnel credential) used to authenticate this agent when it connects to the ngrok service. After you've created an ngrok account, your dashboard will display the authtoken assigned to your account. - -Your authtoken will work on multiple machines if you are just developing. When you want to deploy many agents on many devices, you can generate a unique authtoken for each device in the ngrok Dashboard or via the `ngrok api credentials` command. - -##### ngrok.yml specifying an authtoken - -```yaml -authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p -``` - -### `connect_interface` - -Sets the specific network interface that the ngrok agent should use. This is only supported on Linux platforms. - -### `connect_timeout` - -How long to wait when establishing an agent session connection to the ngrok service. This is specified as a duration, with the default being 10s. - -### `console_ui` - -This option allows you to enable or disable the console UI that is displayed in your terminal window after starting ngrok. - -| | | | -| ------- | ------- | ---------------------------------------------------------------- | -| `true` | | Enable the console UI | -| `false` | | Disable the console UI | -| `iftty` | default | Enable the UI only if standard out is a TTY (not a file or pipe) | - -### `console_ui_color` - -The command sets the background color when displaying the console UI in the terminal. To choose a color other than black, set the value to transparent and change the background of your terminal window. - -| | | | -| ------------- | ------- | ----------------------------------------------------------- | -| `transparent` | | Don't set a background color when displaying the console UI | -| `black` | default | Set the console UI's background to black | - -### `crl_noverify` - -This option will skip verifying with the Certificate Revocation List if set to `true`. This defaults to `false`. - -### `dns_resolver_ips` - -Consult these DNS servers for tunnel session DNS resolution. By default, the ngrok agent will use the local system DNS servers to resolve. - -### `heartbeat_interval` - -How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. The default is 10s. - -### `heartbeat_tolerance` - -Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. The default is 15s. - -### `inspect_db_size` - -This is the upper limit in bytes on memory to allocate when saving requests over HTTP tunnels for inspection and reply. The default is 0, which means 50MB. - -| | | | -| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | -| positive integers | | size in bytes of the upper limit on memory to allocate to save requests over HTTP tunnels for inspection and replay. | -| `0` | default | use the default allocation limit, 50MB | -| `-1` | | disable the inspection database; this has the effective behavior of disabling inspection for all tunnels | - -### `log_level` - -This is the logging level of detail. In increasing order of verbosity, possible values are: `crit`, `warn`, `error`, `info`, and `debug`. - -### `log_format` - -This is the format of written log records. - -| | | | -| -------- | ------- | -------------------------------------------------------------------------------- | -| `logfmt` | | human and machine friendly key/value pairs | -| `json` | | newline-separated JSON objects | -| `term` | default | custom colored human format if standard out is a TTY, otherwise same as `logfmt` | - -### `log` - -This is the destination where ngrok should write the logs. - -| | | | -| ------------ | ------- | -------------------------------------- | -| `stdout` | | write to standard out | -| `stderr` | | write to standard error | -| `false` | default | disable logging | -| other values | | write log records to file path on disk | - -```yaml -log: /var/log/ngrok.log -``` - -### `metadata` - -This is a user-supplied custom string that will be returned as part of the ngrok API response to the [list online sessions resource](/api/resources/tunnel-sessions) for all tunnels started by this agent. This is a useful mechanism to identify tunnels by your own device or customer identifier. Maximum 4096 characters. - -```yaml -metadata: bad8c1c0-8fce-11e4-b4a9-0800200c9a66 -``` - -### `proxy_url` - -This is the URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection. Many HTTP proxies have connection size and duration limits that will cause ngrok to fail. Like many other networking tools, ngrok will also respect the environment variable `http_proxy` and `http_proxy_env` if it is set. - -### `region` - -_Deprecated_ This is the region where the ngrok agent will connect to. You can only choose one region per agent session. Choosing the region closest to you usually improves latency and performance. By default, the ngrok agent attempts to choose the best region for you. - -| Region Code | Region Name | -| ----------- | -------------------------- | -| `ap` | Asia/Pacific (Singapore) | -| `au` | Australia (Sydney) | -| `eu` | Europe (Frankfurt) | -| `in` | India (Mumbai) | -| `jp` | Japan (Tokyo) | -| `sa` | South America (São Paulo) | -| `us` | United States (Ohio) | -| `us-cal-1` | United States (California) | - -### `remote_management` - -Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update) via the [ngrok API](/api/resources/tunnel-sessions#restart-tunnel-agent) or the [ngrok Dashboard](https://dashboard.ngrok.com/tunnels/agents). Defaults to `true`. - -### `root_cas` - -This is the root certificate authorities used to validate the TLS connection to the ngrok server. - -| | | | -| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `trusted` | default | use only the trusted certificate root for the ngrok.com tunnel service | -| `host` | | use the root certificates trusted by the host's operating system. This is helpful for working with machine-in-the-middle (MITM) proxies doing deep packet inspection (DPI). | -| other values | | path to a certificate PEM file on disk with certificate authorities to trust | - -### `server_addr` - -This is the URL of the ngrok server to connect to. You should set this if you are using a custom ingress URL. - -### `tunnels` - -This is a map of names to tunnel definitions. See [tunnel definitions](#tunnel-configurations) for more details. - -### `update_channel` - -The update channel determines the stability of released builds to update to. Use 'stable' for all production deployments. - -| | | | -| ---------- | ------- | --------------------------------------------------------------------------------------------------------- | -| `stable` | default | These are builds that are ready to be used in production. | -| `unstable` | | update to new nightly builds when available which could be broken. This should not be used in production. | -| `beta` | | update to new beta builds when available which could be broken. This should not be used in production. | - -### `update_check` - -This tells the ngrok agent if it should check for updates. Defaults to `true`. - -### `version` - -Specifies the version of the config file to use. - -### `web_addr` - -This is the network address to bind on for serving the local agent web interface and API. - -| Network address | | Bind to this network address | -| ---------------- | ------- | ---------------------------- | -| `127.0.0.1:4040` | default | default network address | -| `false` | | disable the web UI | - -### `web_allow_hosts` - -These are a list of specifiers for what Host headers will be allowed to make requests agains the local agent web interface and API. Any port is stripped off the Host header before matching is performed. - -| Allow string | | Example Host headers that would match | -| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| | default | requests to localhost-bound web interface or API endpoints are checked to have a localhost-like Host (localhost, 127.0.0.1, ::1, etc.) | -| 8.8.8.8 | | an IP matches Host header (8.8.8.8) | -| 1:2:3:4:5:6:7:8 | | an IPv6 matches Host header (1:2:3:4:5:6:7:8) | -| 10.0.0.0/8 | | a CIDR range matches a Host header that is an IP address in that range (10.0.0.1 or 10.1.2.3) | -| 1:2:3:4:5:6:7:8/16 | | a CIDR range matches a Host header that is an IPv6 address in that range (1:2:3:4:5:6:7:0) | -| example.com | | a hostname without preceding period will match Host header exactly (example.com) | -| .example.com | | a hostname with a preceding period Host header suffix (sub.example.com or foo.example.com) | - -##### Allow an IP address and a Domain as Host headers - -```yaml -web_allow_hosts: - - 8.8.8.8 - - example.com -``` diff --git a/docs/agent/config/v2.mdx b/docs/agent/config/v2.mdx index 8ad050fa2..e224c8218 100644 --- a/docs/agent/config/v2.mdx +++ b/docs/agent/config/v2.mdx @@ -4,8 +4,6 @@ title: "Version 2" ## Full Example -import AgentConfigurations from "./_agent-configurations.mdx"; - Below is a comprehensive configuration file for ngrok with detailed documentation for each option. To activate a specific option or tunnel, simply uncomment the relevant lines by removing the `#` at the beginning of the line. @@ -621,4 +619,237 @@ Edges automatically create an `edge` label, for example: `edge=edghts_2gYaK9XAVa ::: - +## Agent Configuration + +The following is a list of options that can be configured at the root of your configuration file and specify the behavior of the agent. + +| Name | Description | +| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [api_key](#api_key) | Specifies the ngrok API key used to connect to the ngrok API. This is only needed when using the `ngrok api` command and should not be confused with the authtoken. | +| [authtoken](#authtoken) | Specifies the authentication token (authtoken) used to connect to the ngrok service. | +| [connect_interface](#connect_interface) | Set the specific network interface for ngrok to use. This is only supported on Linux platforms. | +| [connect_timeout](#connect_timeout) | How long to wait when establishing an agent session connection to the ngrok service. The default is 10s. | +| [console_ui](#console_ui) | Enable/disable the console UI | +| [console_ui_color](#console_ui_color) | Set the background color of the console UI | +| [crl_noverify](#crl_noverify) | Disables verifying Certificate Revocation List | +| [dns_resolver_ips](#dns_resolver_ips) | Consult these DNS servers for tunnel session DNS resolution. | +| [heartbeat_interval](#heartbeat_interval) | How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. Default is 10s. | +| [heartbeat_tolerance](#heartbeat_tolerance) | Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. Default is 15s. | +| [inspect_db_size](#inspect_db_size) | The size in bytes of the upper limit on memory to allocate to save requests over HTTP tunnels for inspection and replay. | +| [log_level](#log_level) | Logging level of detail. In increasing order of verbosity, possible values are: `crit`, `warn`, `error`, `info`, and `debug`. | +| [log_format](#log_format) | Format of written log records. | +| [log](#log) | Write logs to this target destination. | +| [metadata](#metadata) | Opaque, user-supplied string that will be returned as part of the ngrok API response to the [list online sessions](/api/resources/tunnel-sessions) resource for all tunnels started by this agent. | +| [proxy_url](#proxy_url) | URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection. | +| [region](#region) _(Deprecated)_ | Choose the region where the ngrok agent will connect to host its tunnels. | +| [remote_management](#remote_management) | Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update). Defaults to `true`. | +| [root_cas](#root_cas) | The root certificate authorities used to validate the TLS connection to the ngrok server. | +| [server_addr](#server_addr) | This is the URL of the ngrok server to connect to. You should only set this if you are using a custom ingress URL. | +| [tunnels](#tunnels) | A map of names to tunnel definitions. See [V2 agent config tunnel definitions](/docs/agent/config/v2/#tunnel-configurations) for more details. | +| [update_channel](#update_channel) | The update channel determines the stability of released builds to update to. Use `stable` for all production deployments. | +| [update_check](#update_check) | This tells the ngrok agent if it should check for updates. Defaults to `true`. | +| [version](#version) | Specifies the version of the config file to use. | +| [web_addr](#web_addr) | Network address to bind on for serving the local web interface and api. | +| [web_allow_hosts](#web_allow_hosts) | Host headers to allow access for on the local web interface and api, can be a combination of IP's, CIDR ranges, and/or hostname suffixes. | + +### `api_key` + +This option specifies the API key used to access the ngrok API through the [`ngrok api`](/agent/cli#ngrok-api) command. This is only needed when using the [ngrok API](/api) and not the local ngrok agent API (available at `localhost:4040/api`). You can generate an API Key in the [ngrok Dashboard](https://dashboard.ngrok.com/api) and install it using the `ngrok config add-api-key` command. + +##### ngrok.yml specifying an API key + +```yaml +api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN +``` + +### `authtoken` + +This option specifies the authentication token (sometimes called tunnel credential) used to authenticate this agent when it connects to the ngrok service. After you've created an ngrok account, your dashboard will display the authtoken assigned to your account. + +Your authtoken will work on multiple machines if you are just developing. When you want to deploy many agents on many devices, you can generate a unique authtoken for each device in the ngrok Dashboard or via the `ngrok api credentials` command. + +##### ngrok.yml specifying an authtoken + +```yaml +authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p +``` + +### `connect_interface` + +Sets the specific network interface that the ngrok agent should use. This is only supported on Linux platforms. + +### `connect_timeout` + +How long to wait when establishing an agent session connection to the ngrok service. This is specified as a duration, with the default being 10s. + +### `console_ui` + +This option allows you to enable or disable the console UI that is displayed in your terminal window after starting ngrok. + +| | | | +| ------- | ------- | ---------------------------------------------------------------- | +| `true` | | Enable the console UI | +| `false` | | Disable the console UI | +| `iftty` | default | Enable the UI only if standard out is a TTY (not a file or pipe) | + +### `console_ui_color` + +The command sets the background color when displaying the console UI in the terminal. To choose a color other than black, set the value to transparent and change the background of your terminal window. + +| | | | +| ------------- | ------- | ----------------------------------------------------------- | +| `transparent` | | Don't set a background color when displaying the console UI | +| `black` | default | Set the console UI's background to black | + +### `crl_noverify` + +This option will skip verifying with the Certificate Revocation List if set to `true`. This defaults to `false`. + +### `dns_resolver_ips` + +Consult these DNS servers for tunnel session DNS resolution. By default, the ngrok agent will use the local system DNS servers to resolve. + +### `heartbeat_interval` + +How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. The default is 10s. + +### `heartbeat_tolerance` + +Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. The default is 15s. + +### `inspect_db_size` + +This is the upper limit in bytes on memory to allocate when saving requests over HTTP tunnels for inspection and reply. The default is 0, which means 50MB. + +| | | | +| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | +| positive integers | | size in bytes of the upper limit on memory to allocate to save requests over HTTP tunnels for inspection and replay. | +| `0` | default | use the default allocation limit, 50MB | +| `-1` | | disable the inspection database; this has the effective behavior of disabling inspection for all tunnels | + +### `log_level` + +This is the logging level of detail. In increasing order of verbosity, possible values are: `crit`, `warn`, `error`, `info`, and `debug`. + +### `log_format` + +This is the format of written log records. + +| | | | +| -------- | ------- | -------------------------------------------------------------------------------- | +| `logfmt` | | human and machine friendly key/value pairs | +| `json` | | newline-separated JSON objects | +| `term` | default | custom colored human format if standard out is a TTY, otherwise same as `logfmt` | + +### `log` + +This is the destination where ngrok should write the logs. + +| | | | +| ------------ | ------- | -------------------------------------- | +| `stdout` | | write to standard out | +| `stderr` | | write to standard error | +| `false` | default | disable logging | +| other values | | write log records to file path on disk | + +```yaml +log: /var/log/ngrok.log +``` + +### `metadata` + +This is a user-supplied custom string that will be returned as part of the ngrok API response to the [list online sessions resource](/api/resources/tunnel-sessions) for all tunnels started by this agent. This is a useful mechanism to identify tunnels by your own device or customer identifier. Maximum 4096 characters. + +```yaml +metadata: bad8c1c0-8fce-11e4-b4a9-0800200c9a66 +``` + +### `proxy_url` + +This is the URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection. Many HTTP proxies have connection size and duration limits that will cause ngrok to fail. Like many other networking tools, ngrok will also respect the environment variable `http_proxy` and `http_proxy_env` if it is set. + +### `region` + +_Deprecated_ This is the region where the ngrok agent will connect to. You can only choose one region per agent session. Choosing the region closest to you usually improves latency and performance. By default, the ngrok agent attempts to choose the best region for you. + +| Region Code | Region Name | +| ----------- | -------------------------- | +| `ap` | Asia/Pacific (Singapore) | +| `au` | Australia (Sydney) | +| `eu` | Europe (Frankfurt) | +| `in` | India (Mumbai) | +| `jp` | Japan (Tokyo) | +| `sa` | South America (São Paulo) | +| `us` | United States (Ohio) | +| `us-cal-1` | United States (California) | + +### `remote_management` + +Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update) via the [ngrok API](/api/resources/tunnel-sessions#restart-tunnel-agent) or the [ngrok Dashboard](https://dashboard.ngrok.com/tunnels/agents). Defaults to `true`. + +### `root_cas` + +This is the root certificate authorities used to validate the TLS connection to the ngrok server. + +| | | | +| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `trusted` | default | use only the trusted certificate root for the ngrok.com tunnel service | +| `host` | | use the root certificates trusted by the host's operating system. This is helpful for working with machine-in-the-middle (MITM) proxies doing deep packet inspection (DPI). | +| other values | | path to a certificate PEM file on disk with certificate authorities to trust | + +### `server_addr` + +This is the URL of the ngrok server to connect to. You should set this if you are using a custom ingress URL. + +### `tunnels` + +This is a map of names to tunnel definitions. See [tunnel definitions](#tunnel-configurations) for more details. + +### `update_channel` + +The update channel determines the stability of released builds to update to. Use 'stable' for all production deployments. + +| | | | +| ---------- | ------- | --------------------------------------------------------------------------------------------------------- | +| `stable` | default | These are builds that are ready to be used in production. | +| `unstable` | | update to new nightly builds when available which could be broken. This should not be used in production. | +| `beta` | | update to new beta builds when available which could be broken. This should not be used in production. | + +### `update_check` + +This tells the ngrok agent if it should check for updates. Defaults to `true`. + +### `version` + +Specifies the version of the config file to use. + +### `web_addr` + +This is the network address to bind on for serving the local agent web interface and API. + +| Network address | | Bind to this network address | +| ---------------- | ------- | ---------------------------- | +| `127.0.0.1:4040` | default | default network address | +| `false` | | disable the web UI | + +### `web_allow_hosts` + +These are a list of specifiers for what Host headers will be allowed to make requests agains the local agent web interface and API. Any port is stripped off the Host header before matching is performed. + +| Allow string | | Example Host headers that would match | +| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| | default | requests to localhost-bound web interface or API endpoints are checked to have a localhost-like Host (localhost, 127.0.0.1, ::1, etc.) | +| 8.8.8.8 | | an IP matches Host header (8.8.8.8) | +| 1:2:3:4:5:6:7:8 | | an IPv6 matches Host header (1:2:3:4:5:6:7:8) | +| 10.0.0.0/8 | | a CIDR range matches a Host header that is an IP address in that range (10.0.0.1 or 10.1.2.3) | +| 1:2:3:4:5:6:7:8/16 | | a CIDR range matches a Host header that is an IPv6 address in that range (1:2:3:4:5:6:7:0) | +| example.com | | a hostname without preceding period will match Host header exactly (example.com) | +| .example.com | | a hostname with a preceding period Host header suffix (sub.example.com or foo.example.com) | + +##### Allow an IP address and a Domain as Host headers + +```yaml +web_allow_hosts: + - 8.8.8.8 + - example.com +``` diff --git a/docs/agent/config/v3.mdx b/docs/agent/config/v3.mdx index fa7feac70..ca054658b 100644 --- a/docs/agent/config/v3.mdx +++ b/docs/agent/config/v3.mdx @@ -2,435 +2,106 @@ title: "Version 3" --- -import AgentConfigurations from "./_agent-configurations.mdx"; - ## Breaking Changes -The `agent:` key is now **required** in the v3 configuration file as a parent field, and [agent specific fields](/docs/agent/config/v3/#agent-configuration) are nested underneath. +- [Agent specific fields](/docs/agent/config/v3/#agent-configuration) are no longer top level-keys, but instead nested under the **required** `agent` field. +- There are now four top-level keys: `version`, `agent`, `endpoints`, and `tunnels`. +- `tunnels` are deprecated in favor of `endpoints`. ```yaml -# example +version: 3 agent: - authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p # example authtoken - # fields from "Agent Configuration"... + authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p + # add nested "Agent Configuration" fields here + # ... +endpoints: ... +tunnels: # deprecated ``` -_For a complete list of fields, checkout [agent configuration](/docs/agent/config/v3/#agent-configuration)._ - -## Full Example - -Below is an example configuration file with all the options filled in. -To activate a specific option or endpoint, simply uncomment the relevant lines by removing the `#` at the beginning of the line. +For a complete list of nested `agent` fields, check out [agent configuration](/docs/agent/config/v3/#agent-configuration). -```yaml -# ngrok Agent Configuration File v3 -# https://ngrok.com/docs/agent/config/ - -# ###################################################################### -# # Agent Configuration # -# ###################################################################### +## Example Configuration Files -# ---------------------------------------------------------------------- -# | Version (required) | -# ---------------------------------------------------------------------- +Below are a collection of different agent configurations to serve as examples for your `ngrok.yml` file. The [next section](/docs/agent/config/v3/#endpoint-configurations) explains how to start some or all of your configured endpoints from the CLI. -# Specifies the version of the config file to use. Valid options are 2 or 3. +### Basic +```yaml version: 3 - -# ---------------------------------------------------------------------- -# | Agent with authtoken (required) | -# ---------------------------------------------------------------------- - -# Specifies the authentication token (authtoken) used to communicate to the -# ngrok service. -# -# (1) You can get your default authtoken through the dashboard: -# https://dashboard.ngrok.com/get-started/your-authtoken -# -# (2) You can view and generate authtokens through the dashboard -# https://dashboard.ngrok.com/tunnels/authtokens - agent: - authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p # example authtoken - -# ---------------------------------------------------------------------- -# | API Key | -# ---------------------------------------------------------------------- - -# The ngrok API key used to connect to the ngrok API. -# -# (!) This is only needed when using the ngrok api command and should -# not be confused with the authtoken. -# -# (1) You can obtain and manage your API Keys through the dashboard: -# https://dashboard.ngrok.com/api-keys - -# api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN - -# ---------------------------------------------------------------------- -# | Connect Timeout | -# ---------------------------------------------------------------------- - -# How long to wait when establishing an agent session connection to the -# ngrok service. -# -# Accepts duration, the default is 10s - -# connect_timeout: 10s - -# ---------------------------------------------------------------------- -# | Console UI | -# ---------------------------------------------------------------------- - -# Enable or disable the console UI in the terminal. -# -# Options: -# true - Enable the console UI. -# false - Disable the console UI, use structured log format. -# iftty - (Default) Enable UI only if standard out is a TTY. - -# console_ui: iftty - -# ---------------------------------------------------------------------- -# | Console UI Color | -# ---------------------------------------------------------------------- - -# Sets the console UI background color in the terminal. -# -# To use a color other than black, set to `transparent` and adjust your -# terminal's background. - -# console_ui_color: transparent - -# ---------------------------------------------------------------------- -# | CRL No Verify | -# ---------------------------------------------------------------------- - -# Skip Certificate Revocation List (CRL) verification if set to true. -# -# Accepts a boolean. Default is `false`. - -# crl_noverify: false - -# ---------------------------------------------------------------------- -# | DNS Resolver IPs | -# ---------------------------------------------------------------------- - -# List of DNS servers for resolving tunnel session DNS. -# -# Defaults to using the local system DNS servers. - -# dns_resolver_ips: -# - 1.1.1.1 -# - 8.8.8.8 - -# ---------------------------------------------------------------------- -# | Heartbeat Interval | -# ---------------------------------------------------------------------- - -# How often the ngrok agent should heartbeat to the ngrok servers defined -# as a duration. -# -# Accepts a duration (e.g., 10s, 1m). The default value is `10s`. - -# heartbeat_interval: 10s - -# ---------------------------------------------------------------------- -# | Heartbeat Tolerance | -# ---------------------------------------------------------------------- - -# This setting defines the maximum duration to wait for a heartbeat -# response from the server before reconnecting the agent tunnel session. -# -# Accepts a duration (e.g., 10s, 1m). The default value is `15s`. - -# heartbeat_tolerance: 15s - -# ---------------------------------------------------------------------- -# | Inspect DB Size | -# ---------------------------------------------------------------------- - -# This is the upper limit in bytes on memory to allocate when saving -# requests over HTTP endpoints for inspection and reply. -# -# Accepts a numeric value. The default is `0`, equivalent to 50MB. -# -# (!) To disable inspection for all endpoints, set the value to `-1`. - -# inspect_db_size: 52428800 # 50MB - -# ---------------------------------------------------------------------- -# | Log Level | -# ---------------------------------------------------------------------- - -# Sets the log detail level. Higher verbosity with each level. -# -# Allowed values: -# crit - Critical issues. -# warn - Warnings. -# error - Errors. -# info - (Default) Informational messages. -# debug - Detailed debugging info. - -# log_level: info - -# ---------------------------------------------------------------------- -# | Log Format | -# ---------------------------------------------------------------------- - -# Specifies the format of log records. -# -# Allowed values: -# logfmt - (Default) Human and machine-friendly key/value pairs. -# json - Newline-separated JSON objects. -# term - Colored format for TTY; otherwise, same as logfmt. + authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p +endpoints: + - name: basic + url: basic.ngrok.app + upstream: + url: 8080 +``` -# log_format: json +### Multiple endpoints -# ---------------------------------------------------------------------- -# | Log | -# ---------------------------------------------------------------------- +```yaml +version: 3 +agent: + authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p +endpoints: + - name: foo + description: foo123 + metadata: foo123 + url: foo.ngrok.io + upstream: + url: 8080 + protocol: http1 + - name: bar + url: bar.ngrok.io + upstream: + url: 8080 +``` -# This is the destination where ngrok should write the logs. -# -# Allowed values: -# stdout - write to standard out -# stderr - write to standard error (default) -# false - disable logging -# - write log records to file path on disk +### Endpoint with an traffic policy (inline) -# log: /var/log/ngrok.log +```yaml +version: 3 +agent: + authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p +endpoints: + - name: foo + description: foo123 + metadata: foo123 + url: foo.ngrok.io + traffic_policy: + inbound: + - actions: + - type: custom-response + config: + status_code: 200 + content: hello, traffic policy! + headers: + content-type: text/plain + upstream: + url: 8080 + protocol: http1 +``` -# ---------------------------------------------------------------------- -# | Metadata | -# ---------------------------------------------------------------------- - -# Custom string included in the ngrok API response for endpoints. -# -# Maximum 4096 characters. - -# metadata: '{"serial": "00012xa-33rUtz9", "comment": "For customer alan@example.com"}' - -# ---------------------------------------------------------------------- -# | Proxy URL | -# ---------------------------------------------------------------------- - -# URL of an HTTP or SOCKS5 proxy for endpoint connections. -# -# (!) ngrok will also respect the `http_proxy`, `http_proxy_env`, and `socks5_proxy` -# environment variables. - -# proxy_url: socks5://localhost:9150 - -# ---------------------------------------------------------------------- -# | Remote Management | -# ---------------------------------------------------------------------- - -# Allows remote management of the ngrok agent (stop, restart, update) via -# the ngrok API or Dashboard. -# -# Defaults to `true`. - -# remote_management: false - -# ---------------------------------------------------------------------- -# | Root CAs | -# ---------------------------------------------------------------------- - -# Root certificate authorities used to validate TLS connections to the -# ngrok server. -# -# Allowed values: -# trusted - Use only the trusted certificate root for ngrok.com. -# host - Use the root certificates trusted by the host's OS (useful for MITM proxies with DPI). -# - Path to a PEM file with additional trusted certificate authorities. - -# root_cas: trusted - -# ---------------------------------------------------------------------- -# | Server Address | -# ---------------------------------------------------------------------- - -# This is the URL of the ngrok server to connect to. -# -# (!) You should only set this value if you are using a Custom Agent -# Ingress URL. -# -# https://ngrok.com/docs/agent/ingress/#customize-agent-ingress-address - -# connect_url: tunnel.us.ingress.example.com:443 - -# ---------------------------------------------------------------------- -# | Update Channel | -# ---------------------------------------------------------------------- - -# Determines the stability of builds for updates. -# -# (!) Use `stable` for any production deployments. -# -# Allowed values: -# stable - (Default) Production-ready builds. -# unstable - Nightly builds; may be unstable. Not for production. -# beta - Beta builds; may be unstable. Not for production. - -# update_channel: stable - -# ---------------------------------------------------------------------- -# | Update Check | -# ---------------------------------------------------------------------- - -# Controls whether the ngrok agent checks for updates. -# -# Defaults to true. - -# update_check: false - -# ---------------------------------------------------------------------- -# | Web Address | -# ---------------------------------------------------------------------- - -# Network address to bind for the local agent web interface and API. -# -# https://ngrok.com/docs/agent/web-inspection-interface/ -# https://ngrok.com/docs/agent/api/ - -# web_addr: localhost:4040 - -# ---------------------------------------------------------------------- -# | Web Allow Hosts | -# ---------------------------------------------------------------------- - -# List of allowed Host headers for requests to the local agent web -# interface and API. The port is stripped from the Host header before -# matching. -# -# Allowed formats: -# 8.8.8.8 - Matches exact IP in Host header (e.g., 8.8.8.8). -# 1:2:3:4:5:6:7:8 - Matches exact IPv6 in Host header. -# 10.0.0.0/8 - Matches any IP within a CIDR range. -# example.com - Matches exact hostname. -# .example.com - Matches subdomains (e.g., sub.example.com). -# -# The default only allows localhost-like Hosts (localhost, 127.0.0.1, -# ::1, etc.). - -# web_allow_hosts: -# - 8.8.8.8 -# - example.com - -# ###################################################################### -# # Endpoints Configuration # -# ###################################################################### - -# Define individual endpoints and their configurations. -# -# Each entry under 'endpoints' represents an endpoint that can be -# started using the 'ngrok start' command: -# https://ngrok.com/docs/agent/cli/#ngrok-start -# -# To start all endpoints at once, use: -# ngrok start --all -# -# List of common configuration fields: -# https://ngrok.com/docs/agent/config/v3/#common-endpoint-configuration-properties -# -# List of HTTP configuration fields: -# https://ngrok.com/docs/agent/config/v3/#http-configuration -# -# List of TCP configuration fields: -# https://ngrok.com/docs/agent/config/v3/#tcp-configuration -# -# List of TLS endpoint configuration fields: -# https://ngrok.com/docs/agent/config/v3/#tls-configuration +### Endpoint with a traffic policy (file path) +```yaml +version: 3 +agent: + authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p endpoints: - - # -------------------------------------------------------------------- - # | Basic Endpoint Example | - # -------------------------------------------------------------------- - - # Endpoint configuration for a website protected by basic authentication - # with a custom host header. - # - # Start with after uncommenting: - # ngrok start example-website - - # upstream protocol allows for nuanced protocol versions: http1, http2 (default http1) - - # - name: example-website - # metadata: foo123 - # url: example-website.ngrok.app - # upstream: - # url: 8080 - # protocol: http1 - - # -------------------------------------------------------------------- - # | End-to-End TLS Endpoint | - # -------------------------------------------------------------------- - - # Endpoint configuration for end-to-end TLS connections. - # - # Start with after uncommenting: - # ngrok start example-e2e-tls - - # - name: example-e2e-tls - # url: "tls://myapp.example.com" - # upstream: - # url: 9000 - - # -------------------------------------------------------------------- - # | Endpoint with Traffic Policy | - # -------------------------------------------------------------------- - - # Endpoint with a Traffic Policy. - # - # Start with after uncommenting: - # ngrok start example-traffic-policy - # - # More info: - # https://ngrok.com/docs/http/traffic-policy/ - # https://ngrok.com/docs/tls/traffic-policy/ - # https://ngrok.com/docs/tcp/traffic-policy/ - - # - name: example-traffic-policy - # description: example traffic policy - # metadata: it's a traffic policy! - # url: myapp.ngrok.app - # traffic_policy: - # inbound: - # - actions: - # - type: custom-response - # config: - # status_code: 200 - # content: hello, traffic policy! - # headers: - # content-type: text/plain - # upstream: - # url: 8080 - # protocol: http1 - - # -------------------------------------------------------------------- - # | SSH Access Endpoint | - # -------------------------------------------------------------------- - - # Endpoint for SSH access. - # - # Start with: - # ngrok start example-ssh-access - - # - name: example-ssh-access - # url: "tcp://1.tcp.ngrok.io:12345" - # upstream: - # url: 22 - # protocol: tcp + - name: bar + url: bar.ngrok.io + traffic_policy_file: /path/to/your/traffic-policy.yml + upstream: + url: 8080 + protocol: http2 ``` ## Endpoint configurations -> **Looking for Tunnel configurations?** +> **Looking for _Tunnel_ configurations?** > -> Tunnel configurations are still supported in the new `Version 3` configuration file format. However, they're being _deprecated_ in favor of endpoints, which provide a simpler and more powerful way of managing ingress. If you wish to see documentation on how to enable and configure tunnels, refer to the [Version 2 Tunnel Configuration](/docs/agent/config/v2#tunnel-configurations) section. +> Tunnel configurations are still supported in the new `Version 3` configuration file format. However, they're being _deprecated_ in favor of endpoints, which provide a simpler and more powerful way of managing ingress. If you wish to see documentation on how to enable and configure tunnels, refer to the [version 2 tunnel configuration](/docs/agent/config/v2#tunnel-configurations) section. The most common use of the configuration file is to define endpoint configurations. Defining endpoint configurations is useful because you may then @@ -438,7 +109,7 @@ start pre-configured endpoints by name from your command line without rememberin all of the right arguments every time. You may also use this method to start as many endpoints as you like from a single ngrok agent. -Endpoints are defined as mapping of name -> configuration under the `endpoints:` +Endpoints are defined as mapping of name -> configuration under the `endpoints` property in your configuration file. ##### Define two endpoints named 'httpbin' and 'demo' @@ -447,8 +118,12 @@ property in your configuration file. endpoints: - name: httpbin url: https://alan-httpbin.ngrok.dev + upstream: + url: 8080 - name: demo url: https://demo.inconshreveable.com + upstream: + url: 8181 ``` ##### Start the endpoint named 'httpbin' @@ -461,10 +136,10 @@ Each endpoint you define is a map of configuration option names to values. The n _eg:_ -- `--description` becomes `description:` -- `--url` becomes `url:` +- `--description` becomes `description` +- `--url` becomes `url` -All endpoints must define a specific `url:` that tells the agent where to send the traffic. Other properties are available and many are protocol-specific. +All endpoints must define a specific `url` that tells the agent where to send the traffic. Other properties are available and many are protocol-specific. ##### Start all endpoints defined in the configuration file @@ -476,7 +151,7 @@ You can configure a single ngrok agent to start multiple endpoints to different ##### Common Endpoint Configuration Properties -| | | | +| Name | Required | Description | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | required | forward traffic to this network address. This can be a _domain_ `example.ngrok.app`, an _origin_ `https://example.ngrok.app`, or a _scheme_ shorthand `https://` | | `metadata` | Optional | arbitrary user-defined metadata that will appear in the ngrok service API when listing endpoint sessions | @@ -484,7 +159,7 @@ You can configure a single ngrok agent to start multiple endpoints to different ### HTTP Configuration -| | | | +| Name | Type | Description | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `circuit_breaker` | Float | Reject requests when 5XX responses exceed this ratio | | `compression` | `true`, `false` | gzip compress HTTP responses from your web service | @@ -506,7 +181,7 @@ You can configure a single ngrok agent to start multiple endpoints to different | [`policy.outbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | | [`policy.outbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | | `proto` | `http` | The endpoint protocol name. This defines the type of endpoint you would like to start. | -| `proxy_proto` | String | The version of [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to use with this endpoint, empty if not using. Example values are 1 or 2. | +| `proxy_protocol` | String | The version of [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to use with this endpoint, empty if not using. Example values are 1 or 2. | | `request_header.add` | Array of `key:value` Strings | The headers to add to the request in the key:value format. | | `request_header.remove` | Array of Strings | The header keys to remove from the request. | | `response_header.add` | Array of Strings | The headers to add to the response in the key:value format. | @@ -527,7 +202,7 @@ You can configure a single ngrok agent to start multiple endpoints to different ### TCP Configuration -| | | | +| Name | Type | Description | | ---------------------------------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ip_restriction.allow_cidrs` | Array of CIDRs | Rejects connections that do not match the given CIDRs | | `ip_restriction.deny_cidrs` | Array of CIDRs | Rejects connections that match the given CIDRs and allows all other CIDRs. | @@ -553,7 +228,7 @@ You can configure a single ngrok agent to start multiple endpoints to different ### TLS Configuration -| | | | +| Name | Type | Description | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mutual_tls_cas` | Valid system path | The path to the TLS certificate authority to verify client certs for mutual TLS. You will also need to specify `key` and `crt` to enable mutual TLS. | | `crt` | Valid system path | PEM TLS certificate at this path to terminate TLS traffic before forwarding locally. Requires `--key` to also be specified. | @@ -581,4 +256,217 @@ You can configure a single ngrok agent to start multiple endpoints to different | [`traffic_policy.outbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | The type of action that should be executed when this outbound policy rule is activated | | [`traffic_policy.outbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | The configuration required for the specific type of action specified | - +## Agent Configuration + +The following is a list of fields nested under `agent` in your configuration file which customize the agent behavior. + +| Name | Description | +| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [api_key](#api_key) | Specifies the ngrok API key used to connect to the ngrok API. This is only needed when using the `ngrok api` command and should not be confused with the authtoken. | +| [authtoken](#authtoken) | Specifies the authentication token (authtoken) used to connect to the ngrok service. | +| [connect_interface](#connect_interface) | Set the specific network interface for ngrok to use. This is only supported on Linux platforms. | +| [connect_timeout](#connect_timeout) | How long to wait when establishing an agent session connection to the ngrok service. The default is 10s. | +| [console_ui](#console_ui) | Enable/disable the console UI | +| [console_ui_color](#console_ui_color) | Set the background color of the console UI | +| [crl_noverify](#crl_noverify) | Disables verifying Certificate Revocation List | +| [dns_resolver_ips](#dns_resolver_ips) | Consult these DNS servers for tunnel session DNS resolution. | +| [heartbeat_interval](#heartbeat_interval) | How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. Default is 10s. | +| [heartbeat_tolerance](#heartbeat_tolerance) | Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. Default is 15s. | +| [inspect_db_size](#inspect_db_size) | The size in bytes of the upper limit on memory to allocate to save requests over HTTP tunnels for inspection and replay. | +| [log_level](#log_level) | Logging level of detail. In increasing order of verbosity, possible values are: `crit`, `warn`, `error`, `info`, and `debug`. | +| [log_format](#log_format) | Format of written log records. | +| [log](#log) | Write logs to this target destination. | +| [metadata](#metadata) | Opaque, user-supplied string that will be returned as part of the ngrok API response to the [list online sessions](/api/resources/tunnel-sessions) resource for all endpoints started by this agent. | +| [proxy_url](#proxy_url) | URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection. | +| [remote_management](#remote_management) | Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update). Defaults to `true`. | +| [root_cas](#root_cas) | The root certificate authorities used to validate the TLS connection to the ngrok server. | +| [connect_url](#connect_url) | This is the URL of the ngrok server to connect to. You should only set this if you are using a custom ingress URL. | +| [endpoints](#endpoint-configurations) | A map of names to endpoint definitions. See [endpoint configurations](/docs/agent/config/v3/#endpoint-configurations) for more details. | +| [update_channel](#update_channel) | The update channel determines the stability of released builds to update to. Use `stable` for all production deployments. | +| [update_check](#update_check) | This tells the ngrok agent if it should check for updates. Defaults to `true`. | +| [web_addr](#web_addr) | Network address to bind on for serving the local web interface and api. | +| [web_allow_hosts](#web_allow_hosts) | `Host` headers to allow access for on the local web interface and api, can be a combination of IP's, CIDR ranges, and/or hostname suffixes. | + +### `api_key` + +This option specifies the API key used to access the ngrok API through the [`ngrok api`](/agent/cli#ngrok-api) command. This is only needed when using the [ngrok API](/api) and not the local ngrok agent API (available at `localhost:4040/api`). You can generate an API Key in the [ngrok Dashboard](https://dashboard.ngrok.com/api) and install it using the `ngrok config add-api-key` command. + +##### ngrok.yml specifying an API key + +```yaml +agent: + api_key: 24yRd5U3DestCQapJrrVHLOqiAC_7RviwRqpd3wc9dKLujQZN +``` + +### `authtoken` + +This option specifies the authentication token (sometimes called tunnel credential) used to authenticate this agent when it connects to the ngrok service. After you've created an ngrok account, your dashboard will display the authtoken assigned to your account. + +Your authtoken will work on multiple machines if you are just developing. When you want to deploy many agents on many devices, you can generate a unique authtoken for each device in the ngrok Dashboard or via the `ngrok api credentials` command. + +##### ngrok.yml specifying an authtoken + +```yaml +agent: + authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p +``` + +### `connect_interface` + +Sets the specific network interface that the ngrok agent should use. This is only supported on Linux platforms. + +### `connect_timeout` + +How long to wait when establishing an agent session connection to the ngrok service. This is specified as a duration, with the default being 10s. + +### `console_ui` + +This option allows you to enable or disable the console UI that is displayed in your terminal window after starting ngrok. + +| Parameter | Default | Description | +| --------- | ------- | ---------------------------------------------------------------- | +| `true` | | Enable the console UI | +| `false` | | Disable the console UI | +| `iftty` | default | Enable the UI only if standard out is a TTY (not a file or pipe) | + +### `console_ui_color` + +The command sets the background color when displaying the console UI in the terminal. To choose a color other than black, set the value to transparent and change the background of your terminal window. + +| Parameter | Default | Description | +| ------------- | ------- | ----------------------------------------------------------- | +| `transparent` | | Don't set a background color when displaying the console UI | +| `black` | default | Set the console UI's background to black | + +### `crl_noverify` + +This option will skip verifying with the Certificate Revocation List if set to `true`. This defaults to `false`. + +### `dns_resolver_ips` + +Consult these DNS servers for tunnel session DNS resolution. By default, the ngrok agent will use the local system DNS servers to resolve. + +### `heartbeat_interval` + +How often the ngrok agent should heartbeat to the ngrok servers defined as a duration. The default is 10s. + +### `heartbeat_tolerance` + +Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a duration. The default is 15s. + +### `inspect_db_size` + +This is the upper limit in bytes on memory to allocate when saving requests over HTTP endpoints for inspection and reply. The default is 0, which means 50MB. + +| Parameter | Default | Description | +| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | +| positive integers | | size in bytes of the upper limit on memory to allocate to save requests over HTTP endpoints for inspection and replay. | +| `0` | default | use the default allocation limit, 50MB | +| `-1` | | disable the inspection database; this has the effective behavior of disabling inspection for all tunnels | + +### `log_level` + +This is the logging level of detail. In increasing order of verbosity, possible values are: `crit`, `warn`, `error`, `info`, and `debug`. + +### `log_format` + +This is the format of written log records. + +| Parameter | Default | Description | +| --------- | ------- | -------------------------------------------------------------------------------- | +| `logfmt` | | human and machine friendly key/value pairs | +| `json` | | newline-separated JSON objects | +| `term` | default | custom colored human format if standard out is a TTY, otherwise same as `logfmt` | + +### `log` + +This is the destination where ngrok should write the logs. + +| Parameter | Default | Description | +| ------------ | ------- | -------------------------------------- | +| `stdout` | | write to standard out | +| `stderr` | | write to standard error | +| `false` | default | disable logging | +| other values | | write log records to file path on disk | + +```yaml +agent: + log: /var/log/ngrok.log +``` + +### `metadata` + +This is a user-supplied custom string that will be returned as part of the ngrok API response to the [list online sessions resource](/api/resources/tunnel-sessions) for all endpoints started by this agent. This is a useful mechanism to identify endpoints by your own device or customer identifier. Maximum 4096 characters. + +```yaml +agent: + metadata: bad8c1c0-8fce-11e4-b4a9-0800200c9a66 +``` + +### `proxy_url` + +This is the URL of an HTTP or SOCKS5 proxy to use for establishing the tunnel connection. Many HTTP proxies have connection size and duration limits that will cause ngrok to fail. Like many other networking tools, ngrok will also respect the environment variable `http_proxy` and `http_proxy_env` if it is set. + +### `remote_management` + +Set this to `true` to allow the ngrok agent to be remotely managed (stop, restart, update) via the [ngrok API](/api/resources/tunnel-sessions#restart-tunnel-agent) or the [ngrok Dashboard](https://dashboard.ngrok.com/tunnels/agents). Defaults to `true`. + +### `root_cas` + +This is the root certificate authorities used to validate the TLS connection to the ngrok server. + +| Parameter | Default | Description | +| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `trusted` | default | use only the trusted certificate root for the ngrok.com tunnel service | +| `host` | | use the root certificates trusted by the host's operating system. This is helpful for working with machine-in-the-middle (MITM) proxies doing deep packet inspection (DPI). | +| other values | | path to a certificate PEM file on disk with certificate authorities to trust | + +### `connect_url` + +This is the URL of the ngrok server to connect to. You should set this if you are using a custom ingress URL. + +### `update_channel` + +The update channel determines the stability of released builds to update to. Use 'stable' for all production deployments. + +| Parameter | Default | Description | +| ---------- | ------- | --------------------------------------------------------------------------------------------------------- | +| `stable` | default | These are builds that are ready to be used in production. | +| `unstable` | | update to new nightly builds when available which could be broken. This should not be used in production. | +| `beta` | | update to new beta builds when available which could be broken. This should not be used in production. | + +### `update_check` + +This tells the ngrok agent if it should check for updates. Defaults to `true`. + +### `web_addr` + +This is the network address to bind on for serving the local agent web interface and API. + +| Network address | | Bind to this network address | +| ---------------- | ------- | ---------------------------- | +| `127.0.0.1:4040` | default | default network address | +| `false` | | disable the web UI | + +### `web_allow_hosts` + +These are a list of specifiers for what `Host` headers will be allowed to make requests agains the local agent web interface and API. Any port is stripped off the `Host` header before matching is performed. + +| Allow string | | Example `Host` headers that would match | +| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| | default | requests to localhost-bound web interface or API endpoints are checked to have a localhost-like `Host` (localhost, 127.0.0.1, ::1, etc.) | +| `8.8.8.8` | | an IP matches `Host` header (`8.8.8.8`) | +| `1:2:3:4:5:6:7:8` | | an IPv6 matches `Host` header (`1:2:3:4:5:6:7:8`) | +| `10.0.0.0/8` | | a CIDR range matches a `Host` header that is an IP address in that range (`10.0.0.1 or 10.1.2.3`) | +| `1:2:3:4:5:6:7:8/16` | | a CIDR range matches a `Host` header that is an IPv6 address in that range (`1:2:3:4:5:6:7:0`) | +| `example.com` | | a hostname without preceding period will match `Host` header exactly (`example.com`) | +| `.example.com` | | a hostname with a preceding period `Host` header suffix (`sub.example.com` or `foo.example.com`) | + +##### Allow an IP address and a domain as `Host` headers + +```yaml +agent: + web_allow_hosts: + - 8.8.8.8 + - example.com +```