Merge branch 'main' into mandy/device-gateway-sdk

ngrok · Aug 2, 2024 · a153916 · a153916
2 parents 62c9961 + f9d7482
commit a153916
Show file tree

Hide file tree

Showing 15 changed files with 261 additions and 98 deletions.
diff --git a/.github/workflows/pr.yml → .github/workflows/ci-checks.yml b/.github/workflows/pr.yml → .github/workflows/ci-checks.yml
@@ -1,13 +1,9 @@
-name: Demo ngrok docs
+name: CI Checks
 
-on:
-  pull_request:
-    branches:
-      - main
+on: push
 
 jobs:
-  deploy:
-    name: Demo ngrok docs
+  ci-checks:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -21,9 +17,9 @@ jobs:
       - name: 'Create env file'
         run: |
           echo DEPLOY_ENV=dev > .env
-      - name: Install dependencies
+      - name: Install Dependencies 📥
         run: pnpm install --frozen-lockfile
-      - name: Typecheck
+      - name: Type Check 🧹
         run: pnpm run typecheck
-      - name: Build website
+      - name: Build website 📦
         run: pnpm run build
diff --git a/docs/agent/changelog.md b/docs/agent/changelog.md
@@ -6,13 +6,21 @@ title: Changelog
 
 ## v3
 
+### ngrok Agent 3.14.0 - \[2024-08-01\]
+
+- Added support for `traffic_policy` field in agent config for Traffic Policy configuration.
+- Deprecated `policy`
+- Added `EndpointTrafficPolicy` module to Edge API.
+
 ### ngrok Agent 3.13.0 - \[2024-07-15\]
 
 - In some cases, adds additional headers on error responses to ngrok that can be used to customize the content.
 
 ### ngrok Agent 3.12.1 - \[2024-07-11\]
 
 - Fixed a bug in `ngrok diagnose` that would cause a panic if a server IP and the agent had TLS connectivity issues.
+- Added `--traffic-policy-file` flag that accepts Traffic Policy configuration for HTTP, TCP, or TLS traffic.
+- Deprecated `--policy-file` flag
 
 ### ngrok Agent 3.12.0 - \[2024-06-27\]
 

diff --git a/docs/agent/config.mdx b/docs/agent/config.mdx
diff --git a/docs/agent/index.mdx b/docs/agent/index.mdx
@@ -329,7 +329,7 @@ authority. The ngrok agent verifies the returned certificate against
 certificate authorities bundled into the agent itself.
 
 Lastly, the ngrok agent makes a request to `crl.ngrok-agent.com` to verify that the
-certificate returned by the ngrok service has not been revoked.
+certificate returned by the ngrok service has not been revoked. It is possible to skip this step by setting `crl_noverify: true` in your configuration file.
 
 ### Heartbeats
 

diff --git a/docs/agent/version-support-policy.mdx b/docs/agent/version-support-policy.mdx
@@ -44,6 +44,7 @@ Extended support beyond LTS is available to customers on a commercial basis. It
 
 | Support Status | Release | Release Date | Latest | Active Support | End of Life |
 | -------------- | ------- | ------------ | ------ | -------------- | ----------- |
+| Active         | 3.14x   | 2024-08-01   | 3.14.0 | 2025-08-01     | 2025-10-01  |
 | Active         | 3.13x   | 2024-07-18   | 3.13.0 | 2025-07-18     | 2025-09-18  |
 | Active         | 3.12x   | 2024-06-27   | 3.12.1 | 2025-06-27     | 2025-08-27  |
 | Active         | 3.11x   | 2024-06-13   | 3.11.0 | 2025-06-13     | 2025-08-13  |

diff --git a/docs/errors/details/_err_ngrok_3200.md b/docs/errors/details/_err_ngrok_3200.md
@@ -4,13 +4,16 @@ This error occurs when there is no active tunnel using the hostname you are tryi
 
 If you are the ngrok Administrator for this account, please verify that the ngrok Agent is running and that the subdomain/hostname is correct.
 
+If you are not the ngrok Administrator and are a visitor to the ngrok URL, you may need to contact the endpoint owner through other means.
+ngrok is unable to assist with end user content as all content is neither hosted or maintained by ngrok. ngrok is unable to provide user details per the ngrok privacy policy.
+
 ### The most common causes of this error are:
 
-- The ngrok Agent is no longer running, or you forgot to start the Agent. Verify that the Agent is running and showing the expected "Forwarding" address.
-- The Agent session has timed out or stopped. Restart the ngrok Agent to restart the Agent and tunnel sessions.
-- The endpoint domain/hostname has changed. If you are on the Free plan or have not set the `--domain` flag to set the domain on the tunnel, please be aware that the forwarding address will change each time the Agent and session are restarted. If you previously obtained a forwarding URL from an agent session but have since closed that session or closed the client window, the URL will change when a new Agent session starts.
-- You have made a typo in the endpoint address you have entered in the browser. Verify that the tunnel hostname is correct. Incorrectly entering the address (a typo) in a browser address bar can also result in this error.
-- A network issue exists between the device the Agent is running on and ngrok. Your ngrok agent might have trouble reaching the ngrok service. Try running the [`ngrok diagnose`](/docs/agent/cli/#ngrok-diagnose) command to check for connectivity issues.
-- You are attempting to run `--scheme http` on your agent using a domain that only supports https. All of the `.app` and `.dev` domains are HSTS or "HTTP Strict Transport Security" domains. Paid plan accounts are able to start http scheme tunnels on the `ngrok.io` domain, which is not HSTS enforced.
+- **Agent Not Running** The ngrok Agent is no longer running, or you forgot to start the Agent. Verify that the Agent is running and showing the expected "Forwarding" address.
+- **Session Timed Out or Stopped** The Agent session has timed out or stopped. Restart the ngrok Agent to restart the Agent and tunnel sessions.
+- **Endpoint Domain or Hostname Change** The endpoint domain or hostname has changed. If you are on the Free plan or have not set the `--domain` flag to set the domain on the tunnel, please be aware that the forwarding address will change each time the Agent and session are restarted. If you previously obtained a forwarding URL from an agent session but have since closed that session or closed the client window, the URL will change when a new Agent session starts.
+- **Typo in Endpoint Address** You have made a typo in the endpoint address you have entered in the browser. Verify that the tunnel hostname is correct. Incorrectly entering the address (a typo) in a browser address bar can also result in this error.
+- **Network Issues** A network issue exists between the device the Agent is running on and ngrok. Your ngrok agent might have trouble reaching the ngrok service. Try running the [`ngrok diagnose`](/docs/agent/cli/#ngrok-diagnose) command to check for connectivity issues.
+- **Incorrect Scheme** You are attempting to run `--scheme http` on your agent using a domain that only supports https. All of the `.app` and `.dev` domains are HSTS or "HTTP Strict Transport Security" domains. Paid plan accounts are able to start http scheme tunnels on the `ngrok.io` domain, which is not HSTS enforced.
 
-If you are the Administrator for this account, and none of these steps work for you or you have additional questions, drop us a note at at [[email protected]](mailto:[email protected]?subject=Help%20with%20ngrok%203200%20error).
+If you are the Administrator for this ngrok account, and none of these steps work for you or you have additional questions, drop us a note at at [[email protected]](mailto:[email protected]?subject=Help%20with%20ngrok%203200%20error).
diff --git a/docs/errors/details/_err_ngrok_6024.md b/docs/errors/details/_err_ngrok_6024.md
@@ -0,0 +1,16 @@
+### Additional Information
+
+## Are you the developer?
+
+We display this page to prevent abuse. Visitors to your site will only see it once.
+If you are attempting to access an endpoint programmatically and are still encountering this error, the interstitial page can be bypassed.
+
+## To remove this page:
+
+- Set and send an ngrok-skip-browser-warning request header with any value.
+- Or, set and send a custom/non-standard browser User-Agent request header.
+- Or, please [upgrade](https://dashboard.ngrok.com/billing) to any paid ngrok account.
+
+For more information and examples, please see the interstitial explanation [here](https://ngrok.com/docs/guides/limits/#why-is-there-an-interstitial-in-front-of-my-html-content).
+
+If you are the Administrator for this account, and none of these steps work for you or you have additional questions, drop us a note at at [[email protected]](mailto:[email protected]?subject=Help%20with%20ngrok%203200%20error).
diff --git a/docs/errors/index.md b/docs/errors/index.md
@@ -56,3 +56,7 @@ listed here to help make your troubleshooting easier.
 
 Consult the [Errors Reference Documentation](/docs/errors/reference) for a
 complete list of all of ngrok's error codes.
+
+## Customize Error Pages for your Traffic
+
+To access and provide feedback on a development preview of custom error pages [Fill out the form](https://ngrok.com/new-features/custom-error-pages?ref=errordoc).
diff --git a/docs/guides/device-gateway/linux.md b/docs/guides/device-gateway/linux.md
@@ -86,7 +86,9 @@ ngrok tcp 22 --cidr-allow ALLOWED_IP_ADDRESS_CIDR
 Alternatively, you can create an IP policy in the ngrok dashboard (under [Security > IP Restrictions](https://dashboard.ngrok.com/security/ip-restrictions)), and leverage the same policy to control access to your entire device fleet.
 :::
 
-## Step 4: Configure ngrok to recover on outages
+## Step 4: Run ngrok as a service so you don't need to manually restart
+
+Read more about the `ngrok service`command which allows you to run and control an ngrok service on the operating system. [Run ngrok as a service.](/agent/cli/#ngrok-service)).
 
 The ngrok agent works with native OS services like `systemd`. This helps you ensure that the ngrok service is available even after the machine restarts. Before we do this though, it's useful to reserve a TCP address in the ngrok dashboard which allows you to reuse the same address each time the device is restarted.
 

diff --git a/docs/guides/limits.md b/docs/guides/limits.md
@@ -77,4 +77,47 @@ If the interstitial interferes with your project, you can bypass it in a few way
 - Change your user agent by setting the `User-Agent` header to something non-standard, such as `MyApp/0.0.1`, to bypass the warning.
 - Upgrading to any of our paid plans will also bypass the warning.
 
+### Code Examples
+
+Axios
+
+```
+axios.get(url, { 'headers': { 'ngrok-skip-browser-warning': '1' } })
+  .then((response => {
+    console.log(response.data);
+  })
+  .catch((error) => {
+    console.log(error);
+  });
+```
+
+Fetch
+
+```
+const response = await fetch(URL, {
+  headers: {
+    "ngrok-skip-browser-warning": "1",
+  },
+  // ...
+});
+```
+
+SuperAgent
+
+```
+ request
+       .get('/endpoint')
+       .set('ngrok-skip-browser-warning', '1')
+       .then(callback);
+```
+
+JQuery
+
+```
+ request
+       .get('/endpoint')
+       .set('ngrok-skip-browser-warning', '1')
+       .then(callback);
+```
+
 If you are a developer trying to access your own endpoint, you can use a browser extension to customize your browser's user agent value. Here is an [example for Chrome](https://chromewebstore.google.com/detail/requestly-intercept-modif/mdnleldcmiljblolnjhpnblkcekpdkpa?hl=en-US).
diff --git a/docs/guides/running-behind-firewalls.md b/docs/guides/running-behind-firewalls.md
@@ -43,3 +43,7 @@ Setting up a custom ingress domain can be useful because it ensures that no one
 
 - Set up a [custom ingress domain in your ngrok Dashboard](https://dashboard.ngrok.com/tunnels/ingress)
 - Edit your ngrok agent configuration file with a [`server_addr`](/agent/config/#server_addr) parameter, set to the custom ingress domain of your choosing
+
+### Certificate Revocation List
+
+One of the steps in agent connection is [checking the certificate revocation list](/agent/#tls-verification). This requires an outbound connection on port 80 to the CRL URL (`crl.ngrok.com` for agent versions 3.9.0 and before, `crl.ngrok-agent.com` for agent version 3.10.0 and after).If you are unable to connect to this URL, it is possible to skip the CRL check by setting `crl_noverify: true` in your configuration file. However, disabling the CRL check does expose you to the possibility of using a certificate that has been revoked which could mean that a third party could intercept and view your traffic.
diff --git a/docs/http/index.mdx b/docs/http/index.mdx
@@ -807,17 +807,17 @@ via an Agent or Agent SDK.
 - When a Domain is associated with an HTTPS edge, agents may no longer start
   endpoints on that Domain. You can always detach a Domain from your Edge if you want
   to create Endpoints on it from an Agent or Agent SDK.
-- An HTTPS Edges has one or more Routes. Routes have selectors which enable you
+- An HTTPS Edge has one or more Routes. Routes have selectors which enable you
   to process traffic for paths like `/app` or `/static` differently.
 - Each Route can apply different Modules. Routes can also even send traffic to
   different Backends.
 - HTTPS Edges do not create a corresponding HTTP endpoint. Instead, all HTTP
   traffic to domains associated with your HTTPS edges is automatically redirected
   to HTTPS.
-- When you create an HTTPS edge via the dashboard, it will automatically create
+- When you create an HTTPS Edge via the dashboard, it will automatically create
   a new Domain with a random name and assign it to your Edge. If you are on the
   free plan and have created your free domain, it will adopt that domain.
-- When you create an HTTPS edge via the dashboard, it will automatically create
+- When you create an HTTPS Edge via the dashboard, it will automatically create
   a Failover Backend with two entries. First, a tunnel group backend with a
   unique label and second an HTTP Response backend which renders an error if
   there are no tunnels online in the tunnel group.

diff --git a/docs/using-ngrok-with/fastAPI.md b/docs/using-ngrok-with/fastAPI.md
@@ -1,7 +1,62 @@
 ---
-title: Fast API
+title: FastAPI
 ---
 
 # Using ngrok with FastAPI
 
-If you're looking to natively embed the ngrok agent into your Fast API application, you can leverage the [pyngrok project](https://pyngrok.readthedocs.io/en/latest/integrations.html#fastapi) to start a tunnel anytime you start the FastAPI Server via uvicorn.
+You can leverage the [ngrok-python](https://github.com/ngrok/ngrok-python) library to embed the ngrok agent in to FastAPI Applications.
+
+:::warning
+ngrok-python and FastAPI libraries used in this example are sensitive to versions. Use of Virtual Environments is highly recommended
+:::
+
+```sh
+# requirements.txt
+ngrok==1.3.0
+uvicorn==0.29.0
+fastapi==0.111.0
+loguru==0.7.2
+```
+
+```sh
+pip install -r requirements.txt
+```
+
+```python
+# main.py
+from contextlib import asynccontextmanager
+from os import getenv
+
+import ngrok
+import uvicorn
+from fastapi import FastAPI
+from loguru import logger
+
+NGROK_AUTH_TOKEN = getenv("NGROK_AUTH_TOKEN", "")
+NGROK_EDGE = getenv("NGROK_EDGE", "edge:edghts_")
+APPLICATION_PORT = 5000
+
+# ngrok free tier only allows one agent. So we tear down the tunnel on application termination
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info("Setting up Ngrok Tunnel")
+    ngrok.set_auth_token(NGROK_AUTH_TOKEN)
+    ngrok.forward(
+        addr=APPLICATION_PORT,
+        labels=NGROK_EDGE,
+        proto="labeled",
+    )
+    yield
+    logger.info("Tearing Down Ngrok Tunnel")
+    ngrok.disconnect()
+
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}
+
+if __name__ == "__main__":
+    uvicorn.run("main:app", host="127.0.0.1", port=APPLICATION_PORT, reload=True)
+```
diff --git a/docs/whats-new.mdx b/docs/whats-new.mdx
@@ -12,8 +12,14 @@ You can expect this page to update regularly (at least monthly). We'll include t
 - Changes to our API
 - Major security fixes
 
+## August 2024
+
+- 2024-08-01 - Released [ngrok Agent 3.14.0](/agent/changelog/#ngrok-agent-3140---2024-08-01).
+
 ## July 2024
 
+- 2024-07-30 - [ngrok-python 1.4.0 Released](https://github.com/ngrok/ngrok-python/releases/tag/v1.4.0). [Changelog](https://github.com/ngrok/ngrok-python/blob/v1.4.0/CHANGELOG.md)
+- 2024-07-30 - [ngrok-javascript 1.4.0 Released](https://github.com/ngrok/ngrok-javascript/releases/tag/v1.4.0). [Changelog](https://github.com/ngrok/ngrok-javascript/blob/v1.4.0/CHANGELOG.md)
 - 2024-07-15 - Released [ngrok Agent 3.13.0](/agent/changelog/#ngrok-agent-3130---2024-07-15).
 - 2024-07-12 - [ngrok-go 1.10.0 Released](https://github.com/ngrok/ngrok-go/releases/tag/v1.10.0). [Changelog](https://github.com/ngrok/ngrok-go/blob/v1.10.0/CHANGELOG.md)
 - 2024-07-11 - Released [ngrok Agent 3.12.1](/agent/changelog/#ngrok-agent-3121---2024-07-11).

diff --git a/docusaurus.config.ts b/docusaurus.config.ts
@@ -30,8 +30,9 @@ const config = {
 	tagline: "online in one line",
 	url: "https://ngrok.com",
 	baseUrl: "/docs/",
-	onBrokenLinks: "throw",
-	onBrokenMarkdownLinks: "throw",
+	onBrokenAnchors: "warn",
+	onBrokenLinks: "warn",
+	onBrokenMarkdownLinks: "warn",
 	favicon: "img/favicon.ico",
 	trailingSlash: true,