Newt (Pangolin Tunnel Agent) Playbook

Overview

newt.yml deploys Newt, the tunnel agent for the Pangolin reverse proxy platform. Newt establishes an outbound tunnel from a Docker host back to your Pangolin server, allowing Pangolin to route traffic to services on that host without opening inbound ports.

Architecture

┌─────────────────────────┐         ┌──────────────────────────┐
│  Target Docker Host     │         │  Pangolin Server         │
│                         │         │  pangolin.wulfconsulting  │
│  ┌───────────────────┐  │ tunnel  │  .cloud                  │
│  │ newt container     │──────────▶│                          │
│  │ (fosrl/newt)       │  │        │  Routes traffic to sites │
│  └───────────────────┘  │        │  configured in dashboard  │
│                         │         └──────────────────────────┘
│  /opt/stacks/newt/      │
│  └── compose.yaml       │
└─────────────────────────┘

Playbook structure

Section	Purpose
vars	Sets `newt_stack_dir` (`/opt/stacks/newt`) and the default `pangolin_endpoint`
pre_tasks	Validates that `newt_id`, `newt_secret`, and `pangolin_endpoint` are provided; checks Docker is running
tasks	Creates the stack directory, writes `compose.yaml`, and deploys via `docker_compose_v2`

The compose file defines a single service — the fosrl/newt image configured with three environment variables that authenticate it to the Pangolin server.

Usage

Required extra vars

Variable	Source	Description
`newt_id`	Pangolin dashboard (per-site)	Tunnel identity
`newt_secret`	Pangolin dashboard (per-site)	Tunnel secret

Optional extra vars

Variable	Default	Description
`pangolin_endpoint`	`https://pangolin.wulfconsulting.cloud`	Pangolin server URL

Deploy to a host

ansible-playbook playbooks/newt.yml --limit kaercher02 \
  -e newt_id=kigig6jtds5qr3a \
  -e newt_secret=9qznq1wasaapy0cwpxzzi8sji6z5r4nkukqpkt4k8lyy6jx3

Override the Pangolin endpoint

ansible-playbook playbooks/newt.yml --limit somehost \
  -e newt_id=... \
  -e newt_secret=... \
  -e pangolin_endpoint=https://pangolin.other.domain

Verify the container is running

ansible kaercher02 -a "docker ps --filter name=newt"

Notes

Credentials are runtime-only. newt_id and newt_secret are passed as extra vars and written into the compose file on the target host. They are not stored in the Ansible repo.
One Newt per host. The container name is fixed to newt, so each host runs a single instance. If you need multiple tunnels on one host, duplicate the playbook with a different container name and stack directory.
--limit is required. The playbook targets all hosts, so always use --limit to select which host to deploy to.

3.3 KiB Raw Blame History