websockify

README

Websockify for Caddy

Easily integrate "websockify" into your Caddy setup with a single directive.

What is Websockify?

It is very simple: Proxy TCP connections over WebSockets.

First implementations were used by noVNC project to bring native VNC from TCP to WebSockets. Later, WebSockets were used to circumvent Great FireWall of China, as its traffic behind TLS was indistinguishable from innocent HTTPS traffic.

It can be used to serve streaming connections to target TCP/Unix sockets through CDNs (such as CloudFlare). Useful for hiding your TCP endpoints behind CDNs and WAFs, adding another layer of security.

How has it become possible?

Through wsproxy and Gorilla's Websocket implementation. wsproxy implements a standalone websockify client and server, which can be used in conjunction with this module as its client.

What are the limitations?

Gorilla's Websocket implementation is limited to HTTP/1.1 and this is mostly because of how HTTP/2 has been implemented in Go standard library.

How can I use it?

You need to build Caddy yourself and include this plugin in it. This is as easy as executing the following lines:

go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
xcaddy build --with github.com/hadi77ir/caddy-websockify

Then either launch it directly:

./caddy websockify -listen ':80' 'tcp://127.0.0.1:1080'

or configure using a Caddyfile:

mywebsite.com {
  websockify /ssh-ws tcp://127.0.0.1:22
}

A fully-fledged example

Your Caddyfile for a website with:

• WordPress installation at /var/www/wordpress/
• PHP-FPM socket at /run/php/php-version-fpm.sock
• SSH at 127.0.0.1:22
• VMess at 127.0.0.1:8080
• MTProto at 127.0.0.1:9090
• API server at 127.0.0.1:2080

may look like this:

tls myemail@mail.local
example.com {
	root * /var/www/wordpress
	websockify /ssh-ws tcp://127.0.0.1:22
	websockify /vmess tcp://127.0.0.1:8080
	websockify /mtproto tcp://127.0.0.1:9090
	reverse_proxy /api/* 127.0.0.1:2080
	encode gzip
	php_fastcgi unix//run/php/php-version-fpm.sock
	file_server
}

For more information on configuration via Caddyfile, visit official documentation.

License

Apache 2.0 License

   Copyright 2023 Mohammad Hadi Hosseinpour
   Copyright 2015 Matthew Holt and The Caddy Authors
   

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

Documentation

Index

• Constants
• func ConnCopy(dst, src net.Conn, logger *zap.Logger, copyDone chan struct{})
• func DuplexCopy(conn, rConn net.Conn, logger *zap.Logger)
• type ErrorSetterFunc
• type ProxyHandler
  • func (*ProxyHandler) CaddyModule() caddy.ModuleInfo
  • func (s *ProxyHandler) Provision(ctx caddy.Context) error
  • func (s *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (s *ProxyHandler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Constants

const ErrorSetterCtxKey = "handler_error_setter_ws"

Functions

func ConnCopy

func ConnCopy(dst, src net.Conn, logger *zap.Logger, copyDone chan struct{})

func DuplexCopy

func DuplexCopy(conn, rConn net.Conn, logger *zap.Logger)

Types

type ErrorSetterFunc

type ErrorSetterFunc func(status int, err error)

type ProxyHandler

type ProxyHandler struct {

	// Header fields to set on the response; overwrites any existing
	// header fields of the same names after normalization.
	Headers http.Header `json:"headers,omitempty"`

	// Upstream addresses to establish connections. Supports TCP and Unix
	// domain sockets. Must contain at least one element.
	// Examples: "127.0.0.1:1080", "unix:/run/server.sock"
	Upstream []string `json:"upstream,omitempty"`
	// contains filtered or unexported fields
}

ProxyHandler implements a simple responder for Websocket requests which bidirectionally copies the stream between both parties.

func (*ProxyHandler) CaddyModule

func (*ProxyHandler) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*ProxyHandler) Provision

func (s *ProxyHandler) Provision(ctx caddy.Context) error

Provision sets up ProxyHandler.

func (*ProxyHandler) ServeHTTP

func (s *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

func (*ProxyHandler) UnmarshalCaddyfile

func (s *ProxyHandler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the handler from Caddyfile tokens. Syntax:

websockify [<matcher>] <upstream> [<upstream>]