Merge branch 'main' into update-err-ngrok-3208-docs-new

docs/agent/changelog.md

@@ -6,6 +6,36 @@ title: Changelog
 
 ## v3
 
+### ngrok Agent 3.16.0 - \[2024-09-09\]
+
+- Releasing the features originally released by 3.15.0
+  - Added `--url` agent CLI flag for creation of HTTP(S), TLS, and TCP protocol endpoints.
+  - Deprecated `--domain`, `--scheme`, and `--remote-addr` agent CLI flags, which have been replaced by `--url`.
+  - Added `--metadata` and `--description` agent CLI flags when using `--url`.
+  - Added `endpoints:` as a new field used for [endpoint creation](/docs/agent/config/v3/#full-example).
+  - A new `agent:` field has been added to the agent configuration format for V3.
+    - v3 supports _both_ tunnels and endpoints. Tunnels are now considered deprecated when using config v3.
+    - Some agent configuration fields have been renamed in v3.
+    - v2 is still supported, but does not support the new `endpoints:` , or `agent:` fields.
+  - Added support for [endpoint fields](/docs/api/resources/endpoints/#list-endpoints) in ngrok's `api`.
+- Update `config` commands to support new configuration version 3, including `upgrade`, `add-authtoken`, and `add-api-key`
+
+### ngrok Agent 3.15.1 - \[2024-08-29\]
+
+- Restores the functionality and compatibility for version 3.14.0 due to bugs in the previous release. An updated version with the changes from 3.15.0 will be released early next week.
+
+### \[UNSTABLE\] ngrok Agent 3.15.0 - \[2024-08-29\]
+
+- Added `--url` agent CLI flag for creation of HTTP(S), TLS, and TCP protocol endpoints.
+- Deprecated `--domain`, `--scheme`, and `--remote-addr` agent CLI flags, which have been replaced by `--url`.
+- Added `--metadata` and `--description` agent CLI flags when using `--url`.
+- Added `endpoints:` as a new field used for [endpoint creation](/docs/agent/config/v3/#full-example).
+- A new `agent:` field has been added to the agent configuration format for V3.
+  - v3 supports _both_ tunnels and endpoints. Tunnels are now considered deprecated when using config v3.
+  - Some agent configuration fields have been renamed in v3.
+  - v2 is still supported, but does not support the new `endpoints:` , or `agent:` fields.
+- Added support for [endpoint fields](/docs/api/resources/endpoints/#list-endpoints) in ngrok's `api`.
+
 ### ngrok Agent 3.14.0 - \[2024-08-01\]
 
 - Added support for `traffic_policy` field in agent config for Traffic Policy configuration.

docs/agent/cli.mdx

@@ -371,8 +371,8 @@ ngrok http [address:port | port] [flags]
 ```sh
 ngrok http 8080                             # forwards provided ngrok URL to port 80
 ngrok http example.com:9000                 # forward traffic to example.com:9000
-ngrok http --domain=bar.ngrok.dev 80        # request subdomain name: 'bar.ngrok.dev'
-ngrok http --domain=www.ex.com 1234         # request tunnel 'www.ex.com' (DNS CNAME)
+ngrok http --url=bar.ngrok.dev 80        # request subdomain name: 'bar.ngrok.dev'
+ngrok http --url=www.ex.com 1234         # request tunnel 'www.ex.com' (DNS CNAME)
 ngrok http --basic-auth='falken:joshua' 80  # enforce basic auth on tunnel endpoint
 ngrok http --host-header=ex.com 80          # rewrite the Host header to 'ex.com'
 ngrok http file:///var/log                  # serve local files in /var/log
@@ -391,7 +391,7 @@ ngrok http https://localhost:8443           # forward to a local https server
 | `--circuit-breaker float`            | reject requests when 5XX responses exceed this ratio                                                               |
 | `--compression`                      | gzip compress http responses from your web service                                                                 |
 | `--config strings`                   | path to config files; they are merged if multiple                                                                  |
-| `--domain string`                    | host tunnel on a custom domain                                                                                     |
+| `--url string`                       | host tunnel on a custom domain                                                                                     |
 | `-h`, `--help`                       | help for this command                                                                                              |
 | `--host-header string`               | set Host header; if `rewrite` use local address hostname                                                           |
 | `--inspect`                          | enable/disable http introspection (default true)                                                                   |
@@ -412,7 +412,6 @@ ngrok http https://localhost:8443           # forward to a local https server
 | `--request-header-remove strings`    | header field to remove from request if present                                                                     |
 | `--response-header-add strings`      | header key:value to add to response                                                                                |
 | `--response-header-remove strings`   | header field to remove from response if present                                                                    |
-| `--scheme strings`                   | which scheme to listen on (default `https`)                                                                        |
 | `--traffic-policy-file string`       | path to traffic policy configuration YAML or JSON file (See [Traffic Policy](/http/traffic-policy/?cty=agent-cli)) |
 | `--ua-filter-allow strings`          | a list of regular expressions for user-agents to allow                                                             |
 | `--ua-filter-deny strings`           | a list of regular expressions for user-agents to deny                                                              |
@@ -536,7 +535,7 @@ The `ngrok tls` command starts a TLS tunnel listening for traffic on port 443 wi
 
 The ngrok server does not terminate TLS connections forwarded with this command. Any underlying protocol may be used. You may optionally specify a TLS key/cert pair which will be used to terminate the traffic at the ngrok agent before it is forwarded. If not specified, the traffic will be forwarded still encrypted.
 
-Using this command is only recommended with the `--domain` option. Other uses will work, but will always result in certificate mismatch warnings.
+Using this command is only recommended with the `--url` option. Other uses will work, but will always result in certificate mismatch warnings.
 
 ### Usage
 
@@ -548,7 +547,7 @@ ngrok tls [address:port | port] [flags]
 
 ```sh
 # forward TLS traffic for www.example.com to port 443 (requires CNAME)
-ngrok tls --domain=www.example.com 443
+ngrok tls --url=www.example.com 443
 ```
 
 ```sh
@@ -558,7 +557,7 @@ ngrok tls 1234
 
 ```sh
 # terminate TLS traffic for t.co before forwarding
-ngrok tls --domain=t.co --crt=/path/to/t.co.crt --key=/path/to/t.co.key 443
+ngrok tls --url=t.co --crt=/path/to/t.co.crt --key=/path/to/t.co.key 443
 ```
 
 ### Flags
@@ -570,7 +569,7 @@ ngrok tls --domain=t.co --crt=/path/to/t.co.crt --key=/path/to/t.co.key 443
 | `--cidr-deny strings`               | reject connections that match the given CIDRs                                                                           |
 | `--config strings`                  | path to config files; they are merged if multiple                                                                       |
 | `--crt string`                      | path to a TLS certificate for TLS termination                                                                           |
-| `--domain string`                   | host tunnel on a custom domain                                                                                          |
+| `--url string`                      | host tunnel on a custom domain                                                                                          |
 | `-h`, `--help`                      | help for this command                                                                                                   |
 | `--key string`                      | path to a TLS key for TLS termination                                                                                   |
 | `--log string`                      | path to log file, `stdout`, `stderr` or `false` (default `false`)                                                       |

docs/agent/config/index.mdx

@@ -0,0 +1,42 @@
+---
+title: Configuration File
+---
+
+# ngrok Agent Configuration File
+
+## Overview
+
+The ngrok agent supports an optional, YAML configuration file which provides
+you with the power to run multiple tunnels simultaneously as well as to tweak
+some of its more advanced settings.
+
+## Default Locations
+
+The default location of the ngrok agent's configuration file varies based on your operating system. The easiest way to find the configuration file location is to run:
+
+```sh
+ngrok config check
+```
+
+which will validate and print the location of the configuration file.
+
+For the main operating systems we support, their default file locations are:
+
+- Linux: `~/.config/ngrok/ngrok.yml`
+- MacOS (Darwin): `~/Library/Application Support/ngrok/ngrok.yml`
+- Windows: `"%HOMEPATH%\AppData\Local\ngrok\ngrok.yml"`
+
+## Config File Merging
+
+The `--config` flag in the `ngrok` command allows you to specify one or more
+ngrok configuration files to merge when starting the ngrok agent. The rules for
+merging are as follows:
+
+- Values from later configs override those from earlier configs. For example, if config1.yml and config2.yml both set `api_key`, then calling `ngrok http --config config1.yml,config2.yml 80` will use the `api_key` from config2.yml.
+- Lists are overwritten using the last value.
+- Maps, including the `tunnels` map, are merged by key and in the case of a duplicate key, the latter value is taken.
+
+## Configuration File Formats
+
+- [Version 3](/docs/agent/config/v3)
+- [Version 2](/docs/agent/config/v2) (_deprecated_)