README
¶
ngrok/Caddy Listener Wrapper
On March 9, 2023, ngrok announced the release of ngrok-go[^1], a Go package for embedding ngrok into a Go application. The package returns a net.Listener. This means it fits right into Caddy's listener_wrapper[^2]. Using this module, when Caddy asks for a listener, it will ask ngrok for the listener, for which ngrok return an ngrok ingress address that is publicly accessible. The public address is printed in logs and avaible on ngrok dashboard.
Currently, the module does not support the extended ngrok options, e.g. allow/deny CIDR. PRs are welcome.
[^1]: Alan Shreve's tweet
[^2]: listener_wrappers Caddyfile docs
Example
Caddyfile
{
servers :80 {
listener_wrappers {
ngrok {
auth_token $NGROK_AUTH_TOKEN
tunnel http {
}
}
}
}
}
:80 {
root * /path/to/site/root
file_server
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type HTTP ¶
type HTTP struct {
// Rejects connections that do not match the given CIDRs
AllowCIDR []string `json:"allow_cidr,omitempty"`
// Rejects connections that match the given CIDRs and allows all other CIDRs.
DenyCIDR []string `json:"deny_cidr,omitempty"`
// the domain for this edge.
Domain string `json:"domain,omitempty"`
// opaque metadata string for this tunnel.
Metadata string `json:"metadata,omitempty"`
// sets the scheme for this edge.
Scheme string `json:"scheme,omitempty"`
// the 5XX response ratio at which the ngrok edge will stop sending requests to this tunnel.
CircuitBreaker float64 `json:"circuit_breaker,omitempty"`
// enables gzip compression.
Compression bool `json:"compression,omitempty"`
// enables the websocket-to-tcp converter.
WebsocketTCPConverter bool `json:"websocket_tcp_converter,omitempty"`
// A map of basicauth, username and password value pairs for this tunnel.
BasicAuth []basicAuthCred `json:"basic_auth,omitempty"`
OIDC *oidc `json:"oidc,omitempty"`
// contains filtered or unexported fields
}
ngrok HTTP tunnel
func (*HTTP) CaddyModule ¶
func (*HTTP) CaddyModule() caddy.ModuleInfo
CaddyModule implements caddy.Module
func (*HTTP) NgrokTunnel ¶
convert to ngrok's Tunnel type
type Labeled ¶
type Labeled struct {
// A map of label, value pairs for this tunnel.
Labels map[string]string `json:"labels,omitempty"`
// opaque metadata string for this tunnel.
Metadata string `json:"metadata,omitempty"`
// contains filtered or unexported fields
}
ngrok Labeled Tunnel
func (*Labeled) CaddyModule ¶
func (*Labeled) CaddyModule() caddy.ModuleInfo
CaddyModule implements caddy.Module
func (*Labeled) NgrokTunnel ¶
convert to ngrok's Tunnel type
type Ngrok ¶
type Ngrok struct {
// The user's ngrok authentication token
AuthToken string `json:"auth_token,omitempty"`
// The ngrok tunnel type and configuration; defaults to 'tcp'
TunnelRaw json.RawMessage `json:"tunnel,omitempty" caddy:"namespace=caddy.listeners.ngrok.tunnels inline_key=type"`
// Opaque, machine-readable metadata string for this session.
// Metadata is made available to you in the ngrok dashboard and the
// Agents API resource. It is a useful way to allow you to uniquely identify
// sessions. We suggest encoding the value in a structured format like JSON.
Metadata string `json:"metadata,omitempty"`
// Region configures the session to connect to a specific ngrok region.
// If unspecified, ngrok will connect to the fastest region, which is usually what you want.
// The [full list of ngrok regions] can be found in the ngrok documentation.
Region string `json:"region,omitempty"`
// Server configures the network address to dial to connect to the ngrok
// service. Use this option only if you are connecting to a custom agent
// ingress.
//
// See the [server_addr parameter in the ngrok docs] for additional details.
Server string `json:"server,omitempty"`
// HeartbeatTolerance configures the duration to wait for a response to a heartbeat
// before assuming the session connection is dead and attempting to reconnect.
//
// See the [heartbeat_tolerance parameter in the ngrok docs] for additional details.
HeartbeatTolerance caddy.Duration `json:"heartbeat_tolerance,omitempty"`
// HeartbeatInterval configures how often the session will send heartbeat
// messages to the ngrok service to check session liveness.
//
// See the [heartbeat_interval parameter in the ngrok docs] for additional details.
HeartbeatInterval caddy.Duration `json:"heartbeat_interval,omitempty"`
// contains filtered or unexported fields
}
Ngrok is a `listener_wrapper` whose address is an ngrok-ingress address
func (*Ngrok) CaddyModule ¶
func (*Ngrok) CaddyModule() caddy.ModuleInfo
type TCP ¶
type TCP struct {
// The remote TCP address to request for this edge
RemoteAddr string `json:"remote_addr,omitempty"`
// opaque metadata string for this tunnel.
Metadata string `json:"metadata,omitempty"`
// Rejects connections that do not match the given CIDRs
AllowCIDR []string `json:"allow_cidr,omitempty"`
// Rejects connections that match the given CIDRs and allows all other CIDRs.
DenyCIDR []string `json:"deny_cidr,omitempty"`
// contains filtered or unexported fields
}
ngrok TCP tunnel
func (*TCP) CaddyModule ¶
func (*TCP) CaddyModule() caddy.ModuleInfo
CaddyModule implements caddy.Module
type TLS ¶
type TLS struct {
// the domain for this edge.
Domain string `json:"domain,omitempty"`
// opaque metadata string for this tunnel.
Metadata string `json:"metadata,omitempty"`
// Rejects connections that do not match the given CIDRs
AllowCIDR []string `json:"allow_cidr,omitempty"`
// Rejects connections that match the given CIDRs and allows all other CIDRs.
DenyCIDR []string `json:"deny_cidr,omitempty"`
// contains filtered or unexported fields
}
ngrok TLS tunnel Note: only available for ngrok Enterprise user
func (*TLS) CaddyModule ¶
func (*TLS) CaddyModule() caddy.ModuleInfo
CaddyModule implements caddy.Module
Source Files
Click to show internal directories.
Click to hide internal directories.