diff --git a/docs/agent/config/v3.mdx b/docs/agent/config/v3.mdx index fa7feac70..191c91071 100644 --- a/docs/agent/config/v3.mdx +++ b/docs/agent/config/v3.mdx @@ -10,422 +10,95 @@ The `agent:` key is now **required** in the v3 configuration file as a parent fi ```yaml # example +verison: 3 agent: - authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p # example authtoken - # fields from "Agent Configuration"... + authtoken: + # ... fields from "Agent Configuration"... +endpoints: # ... ``` _For a complete list of fields, checkout [agent configuration](/docs/agent/config/v3/#agent-configuration)._ -## Full Example +## Example Configs -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. +Below are a collection of different agent configurations. Simply copy each one, and replace any placeholder or example values with your own! +
+Basic ```yaml # ngrok Agent Configuration File v3 # https://ngrok.com/docs/agent/config/ -# ###################################################################### -# # Agent Configuration # -# ###################################################################### - -# ---------------------------------------------------------------------- -# | Version (required) | -# ---------------------------------------------------------------------- - -# Specifies the version of the config file to use. Valid options are 2 or 3. - 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 +endpoints: + - name: basic + url: basic.ngrok.app + upstream: + url: 8080 +``` +
-# ---------------------------------------------------------------------- -# | 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. - -# log_format: json - -# ---------------------------------------------------------------------- -# | Log | -# ---------------------------------------------------------------------- - -# 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 +
+Multiple Endpoints +```yaml +# ngrok Agent Configuration File v3 +# https://ngrok.com/docs/agent/config/ -# log: /var/log/ngrok.log +version: 3 +agent: + authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p # example authtoken +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 +``` +
-# ---------------------------------------------------------------------- -# | 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 +
+Endpoints with Traffic Policy (file _and_ inline) +```yaml +# ngrok Agent Configuration File v3 +# https://ngrok.com/docs/agent/config/ +version: 3 +agent: + authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p # example authtoken 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: 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 + - name: bar + url: bar.ngrok.io + traffic_policy_file: /path/to/your/traffic-policy.yml + upstream: + url: 8080 ``` +
+ ## Endpoint configurations > **Looking for Tunnel configurations?**