security

authentication available

funnel supports api key-based authentication. enable it with --require-auth to secure your server.

current security features

🔑 token authentication

api key-based authentication for tunnel connections

🔐 tls encryption

automatic https certificates via let's encrypt

🆔 tunnel id validation

basic format validation and uniqueness checking

📋 comprehensive logging

detailed logging for monitoring connections

authentication

funnel supports api key-based authentication to control who can create tunnels on your server.

enabling authentication

start the server with the --require-auth flag:

funnel-server --require-auth

or with docker:

docker run -d --name funnel-server \
  -p 8080:8080 \
  -v funnel-tokens:/var/lib/funnel \
  -e FUNNEL_REQUIRE_AUTH=true \
  ghcr.io/karol-broda/funnel-server:latest

managing tokens

funnel-server token create --name my-laptop

# output:
# Token created for "my-laptop"
#
#   sk_7Fj2kL9xMnPqRsTuVwXyZ0AbCdEfGhIj
#
#   Save this token now - it will NOT be shown again.
#   Token is persisted to disk and survives server restarts.

save your token

the plain token is only shown once. save it immediately - you cannot retrieve it later.

funnel-server token list

# output:
# NAME                 PREFIX       CREATED
# ----                 ------       -------
# my-laptop            sk_7Fj2kL... 2 hours ago
# ci-pipeline          sk_x8Yz9W... 5 days ago

funnel-server token revoke --name my-laptop

# output:
# Token "my-laptop" revoked.

token storage security

location	storage method	security
server (`tokens.json`)	sha-256 hashed	cannot recover plain token if file leaks
client (`config.toml`)	plain text	file saved with 0600 permissions

server-side security

tokens are hashed before storage on the server. even if the token file is compromised, attackers cannot use the hashes to authenticate.

client configuration

clients can save their token to avoid passing it on every command:

# save token to config
funnel config set-token sk_7Fj2kL9xMnPqRsTuVwXyZ0AbCdEfGhIj

# save server url
funnel config set-server https://tunnel.example.com

# now just run without flags
funnel http 3000

plain text warning

the client stores the token in plain text in ~/.config/funnel/config.toml. the file is created with restricted permissions (0600), but ensure your machine is secure.

current limitations

no rate limiting - no built-in protection against abuse
no ip restrictions - accepts connections from any ip address
no user management - tokens are not tied to user accounts

tls encryption

https is supported

the server has built-in support for automatic tls certificate generation using let's encrypt.

enable automatic tls with let's encrypt:

docker run -d --name funnel-server \
  -p 80:8080 \
  -p 443:8443 \
  -v $(pwd)/dns-providers.json:/etc/funnel/dns-providers.json \
  -v funnel-certs:/var/lib/funnel/certs \
  -e FUNNEL_ENABLE_TLS=true \
  -e FUNNEL_LETSENCRYPT_EMAIL=your-email@example.com \
  -e FUNNEL_DNS_PROVIDERS_CONFIG=/etc/funnel/dns-providers.json \
  ghcr.io/karol-broda/funnel-server:latest

requires dns provider configuration for certificate validation.

use your own certificates:

docker run -d --name funnel-server \
  -p 443:8443 \
  -v /path/to/certs:/var/lib/funnel/certs \
  -e FUNNEL_ENABLE_TLS=true \
  ghcr.io/karol-broda/funnel-server:latest

automatic certificate features:

on-demand generation - certificates created on first request
automatic renewal - renewed before expiration
wildcard support - can generate *.domain.com certificates
secure storage - stored in docker volume

deployment security

for additional security beyond token authentication, consider these deployment strategies:

network-level protection

use firewall rules to restrict access:

# allow public access to tunnel traffic
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# restrict websocket connections to trusted networks
sudo ufw allow from 192.168.1.0/24 to any port 8080
sudo ufw deny 8080/tcp

sudo ufw enable

firewall strategy

allow public access to ports 80/443 for tunnel traffic, but restrict the websocket port (8080) to trusted networks only.

reverse proxy with authentication

use nginx or similar to add authentication:

server {
    listen 443 ssl;
    server_name tunnel.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    # require basic auth for websocket connections
    location ~ ^/\?id= {
        auth_basic "Tunnel Access";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
    
    # public access to tunnels
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

basic auth

this adds basic authentication to websocket connections while keeping tunnel traffic public.

vpn or private network

deploy the server in a private network:

use a vpn to access the server
deploy on a private subnet
use ssh tunneling for connections

private deployment

the most secure approach is to deploy in a private network and use vpn/ssh for access.

monitoring

built-in logging

the server provides comprehensive logging for monitoring connections and tunnel activity.

monitor these events:

# view real-time connection logs
docker logs -f funnel-server

# search for specific events
docker logs funnel-server | grep -i "websocket\|tunnel"

key events to monitor:

websocket connection attempts
tunnel creation and removal
failed connection attempts

# monitor certificate activities
docker logs funnel-server | grep -i "certificate\|tls\|acme"

certificate-related events:

certificate generation
renewal activities
tls handshake errors

# monitor errors and failures
docker logs funnel-server | grep -i "error\|failed\|rejected"

important errors:

connection failures
invalid tunnel ids
certificate issues

future security features

roadmap

we plan to add additional security features in future releases.

planned features:

rate limiting - protection against abuse
ip allowlists - built-in ip-based access control
user management - user accounts and permissions
oauth integration - enterprise sso support

# pull latest image
docker pull ghcr.io/karol-broda/funnel-server:latest

# restart with new image
docker stop funnel-server
docker rm funnel-server
docker run -d --name funnel-server [your-config] ghcr.io/karol-broda/funnel-server:latest

Last updated: December 23, 2025

by karol-broda