DEV Community

ngrok profile image Aaishika S Bhattacharya
Aaishika S Bhattacharya for ngrok

Posted on • Originally published at ngrok.com

The Ultimate Guide to ngrok

#ngrok #webhooks #platform #engineering

Getting started with ngrok is almost suspiciously easy. Which is why the question we hear most often isn’t "where do I start?" but rather “what else can I do with ngrok?” For over a decade, we’ve been serving millions of developers and, through them, millions of users.

Sure, our documentation has all the answers, every CLI flag, every Traffic Policy configuration neatly laid out, but what about the developers who are always on the lookout for a TL;DR? What if you too are not looking for a full solution or a specific use case for your next project, but just want to know… what else you can do with ngrok?

Presenting ngrok's new cheatsheet that walks you through some of our most interesting offerings, designed to scratch that itch of not just serving, but also securing endpoints in as little as two steps. Read on, or download the PDF format, or a crisp two-pager printable.

Installation

macOS 

# Install via Homebrew
brew install ngrok

# Add your authtoken
ngrok config add-authtoken <token>

# Start an endpoint
ngrok http 80
Enter fullscreen mode Exit fullscreen mode

Linux 

# Install via Apt
curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update \
  && sudo apt install ngrok
# OR
# Install via Snap
snap install ngrok

# Add your authtoken
ngrok config add-authtoken <token>

# Start an endpoint
ngrok http 80
Enter fullscreen mode Exit fullscreen mode

Windows 

# Install via WinGet
winget install ngrok -s msstore
# OR
# Install via Scoop
scoop install ngrok

# Add your authtoken
ngrok config add-authtoken <token>

# Start an endpoint
ngrok http 80
Enter fullscreen mode Exit fullscreen mode

Kubernetes 

# Add ngrok Kubernetes Operator to Helm
helm repo add ngrok https://charts.ngrok.com

# Add ngrok API key and authtoken
export NGROK_AUTHTOKEN=YOUR_NGROK_AUTHTOKEN
export NGROK_API_KEY=YOUR_NGROK_API_KEY

helm install ngrok-operator ngrok/ngrok-operator \
  --namespace ngrok-operator \
  --create-namespace \
  --set credentials.apiKey=$NGROK_API_KEY \
  --set credentials.authtoken=$NGROK_AUTHTOKEN
Enter fullscreen mode Exit fullscreen mode

Docker 

# Install via Docker
docker pull ngrok/ngrok

# Run ngrok via Docker
docker run --net=host -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80
Enter fullscreen mode Exit fullscreen mode

SDKs 

# Node.js: https://ngrok.com/downloads/node-js
npm install @ngrok/ngrok

# Go: https://ngrok.com/downloads/go
go get golang.ngrok.com/ngrok/v2

# Python: https://ngrok.com/downloads/python
python3 -m pip install ngrok

# Rust: https://ngrok.com/downloads/rust
# Install ngrok-rust package and the required dependencies
cargo add ngrok -F axum && cargo add axum && cargo add tokio -F rt-multi-thread -F macros
Enter fullscreen mode Exit fullscreen mode

Expose different kinds of servers

API service 

# Example: API service on localhost:8080
ngrok http 8080
Enter fullscreen mode Exit fullscreen mode

Web app 

# Example: On localhost:3000
ngrok http 3000
Enter fullscreen mode Exit fullscreen mode

SSH server 

# Example: On Port 22
ngrok tcp 22
Enter fullscreen mode Exit fullscreen mode

Postgres server 

ngrok tcp 5432
Enter fullscreen mode Exit fullscreen mode

Any service or server on a different machine 

ngrok http http://192.168.1.50:8080
Enter fullscreen mode Exit fullscreen mode

Troubleshoot 

ngrok diagnose

# To test IPv6 connectivity
ngrok diagnose --ipv6 true

# To test connectivity between the ngrok agent and all ngrok points of presence
ngrok diagnose --region all

# For a verbose report
ngrok diagnose -w out.txt #OR
ngrok diagnose --write-report out.txt
Enter fullscreen mode Exit fullscreen mode

Add Authentication with Traffic Policy

Create a Traffic Policy file policy.yaml 

nano policy.yaml
Enter fullscreen mode Exit fullscreen mode

Add the OAuth Action with Google

List of Providers: https://ngrok.com/docs/traffic-policy/actions/oauth/#supported-providers

# policy.yaml
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google # OAuth available with Amazon, Facebook, GitHub, GitLab, Google, LinkedIn, Microsoft, Twitch
Enter fullscreen mode Exit fullscreen mode

Run your endpoint with the Traffic Policy file 

ngrok http 8080 --traffic-policy-file=policy.yaml
Enter fullscreen mode Exit fullscreen mode

Restrict OAuth to specific emails 

# policy.yaml
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
  - expressions:
      - "!(actions.ngrok.oauth.identity.email in ['alice@example.com','bob@example.com'])"
    actions:
      - type: deny
Enter fullscreen mode Exit fullscreen mode

Restrict OAuth to specific domains 

# policy.yaml
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
  - expressions:
      - "!(actions.ngrok.oauth.identity.email.endsWith('@example.com'))"
    actions:
      - type: deny
Enter fullscreen mode Exit fullscreen mode

Verify your webhooks

Add the verify-webhook action for Slack 

# policy.yaml
on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: slack
          secret: $SLACK_TOKEN
Enter fullscreen mode Exit fullscreen mode

CLI Alternative 

ngrok http 3000 \
  --verify-webhook=slack \
  --verify-webhook-secret=$SLACK_TOKEN
Enter fullscreen mode Exit fullscreen mode

Replace provider for any supported provider

List of Supported Providers: https://ngrok.com/docs/traffic-policy/actions/verify-webhook/

# policy.yaml
on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: $PROVIDER # Example: GitHub
          secret: $PROVIDER_TOKEN
Enter fullscreen mode Exit fullscreen mode

Do even more with internal endpoints

Create a Cloud Endpoint 

# Create a private, internal agent endpoint only reachable via forward-internal
ngrok http 8080 --binding=internal --url https://api.internal
Enter fullscreen mode Exit fullscreen mode

Example Traffic Policy File 

# policy.yaml
# Forward to an internal endpoint from a public endpoint
on_http_request:
  - actions:
      - type: forward-internal
        config:
          url: https://api.internal
Enter fullscreen mode Exit fullscreen mode

Start Public Endpoint with forward-internal action 

ngrok http 8080 --url forward-internal-example.ngrok.app --traffic-policy-file policy.yml
Enter fullscreen mode Exit fullscreen mode

Manage traffic in other ways

Add path-based routing 

# policy.yaml
# Route /api/* to api.internal, /app/* to app.internal
on_http_request:
  - expressions:
      - "req.path.startsWith('/api/')"
    actions:
      - type: forward-internal
        config:
          url: https://api.internal
  - expressions:
      - "req.path.startsWith('/app/')"
    actions:
      - type: forward-internal
        config:
          url: https://app.internal
Enter fullscreen mode Exit fullscreen mode

Route traffic by anything 

# policy.yaml
# Host-based and header-based dynamic forwarding to internal endpoints via forward-internal action
on_http_request:
  - expressions:
      - "req.host == 'api.example.com'"
    actions:
      - type: forward-internal
        config: { url: https://api.internal }
  - expressions:
      - "getReqHeader('X-Tenant') != ''"
    actions:
      - type: forward-internal
        config: { url: https://tenant.internal }
Enter fullscreen mode Exit fullscreen mode

Multiplex to Internal Services from a Single Domain 

# policy.yaml
on_http_request:
  - actions:
      - type: forward-internal
        config:
          url: https://${req.host.split(".$NGROK_DOMAIN")[0]}.internal
Enter fullscreen mode Exit fullscreen mode

Add rate limiting 

# policy.yaml
# 10 requests per 60s window per client IP -> 429 on limit
on_http_request:
  - actions:
      - type: rate-limit
        config:
          name: per-ip-60s
          algorithm: sliding_window
          capacity: 10
          rate: "60s"
          bucket_key:
            - conn.client_ip
Enter fullscreen mode Exit fullscreen mode

Block search and AI bots 

# policy.yaml
# Send a robots.txt denying crawlers
on_http_request:
  - expressions:
      - "req.path == '/robots.txt'"
    actions:
      - type: custom-response
        config:
          status_code: 200
          headers:
            Content-Type: "text/plain"
          body: |
            User-agent: *
            Disallow: /
Enter fullscreen mode Exit fullscreen mode 
# policy.yaml
# Deny common bot/AI user agents
on_http_request:
  - expressions:
      - "req.user_agent.raw.matches('(?i)(gptbot|chatgpt-user|ccbot|bingbot|googlebot)')"
    actions:
      - type: deny
Enter fullscreen mode Exit fullscreen mode 
# policy.yaml
# Also add X-Robots-Tag to all responses
on_http_response:
  - actions:
      - type: add-headers
        config:
          headers:
            X-Robots-Tag: "noindex, nofollow, noai, noimageai"
Enter fullscreen mode Exit fullscreen mode

Add headers

Via CLI 

# Common security headers
ngrok http 8080 \
  --request-header-add "X-Frame-Options: DENY" \
  --response-header-add "Referrer-Policy: no-referrer"
Enter fullscreen mode Exit fullscreen mode

Via Traffic Policy 

# policy.yaml
# Add headers on request/response
on_http_request:
  - actions:
      - type: add-headers
        config:
          headers:
            X-Frame-Options: "DENY"
on_http_response:
  - actions:
      - type: add-headers
        config:
          headers:
            Referrer-Policy: "no-referrer"
Enter fullscreen mode Exit fullscreen mode

Restrict access by IPs 

# Allow only 203.0.113.0/24; deny others
ngrok http 8080 --cidr-allow 203.0.113.0/24

# Or explicitly deny CIDRs
ngrok http 8080 --cidr-deny 0.0.0.0/0
Enter fullscreen mode Exit fullscreen mode

Block all the potentially bad things 

# policy.yaml
# Apply OWASP Core Rule Set on requests/responses
on_http_request:
  - actions:
      - type: owasp-crs-request
on_http_response:
  - actions:
      - type: owasp-crs-response
Enter fullscreen mode Exit fullscreen mode

CLI Flags

url 

# Choose a URL instead of random assignment
ngrok http 8080 --url https://baz.ngrok.dev
Enter fullscreen mode Exit fullscreen mode

traffic-policy-file 

# Manipulate traffic to your endpoint with a traffic policy file
ngrok http 8080 --url https://baz.ngrok.dev --traffic-policy-file policy.yaml
Enter fullscreen mode Exit fullscreen mode

traffic-policy-url 

# Manipulate traffic to your endpoint with a traffic policy URL
ngrok http 8080 --url https://baz.ngrok.dev policy --traffic-policy-url https://example.com/policy.yml
Enter fullscreen mode Exit fullscreen mode

pooling-enabled 

# Load Balance (different ports)
ngrok http 8080 --url https://api.example.com --pooling-enabled
ngrok http 8081 --url https://api.example.com --pooling-enabled
Enter fullscreen mode Exit fullscreen mode

What else can I do with ngrok?

Ending Notes

Get started with ngrok absolutely free of charge, sign up today!

Top comments (0)