added docs, improved logging (still need to write a proper logging library), minor bugs

Author: jpillora

README.md

@@ -1,8 +1,6 @@
 # chisel
 
-Chisel is TCP proxy tunnelled over HTTP and Websockets
-
-![how it works](https://docs.google.com/drawings/d/1p53VWxzGNfy8rjr-mW8pvisJmhkoLl82vAgctO_6f1w/pub?w=960&h=720)
+Chisel is TCP proxy tunnelled over HTTP WebSockets. Similar to [crowbar](https://github.com/q3k/crowbar) though achieves **much** higher [performance](#Performance). **Warning** this is beta software.
 
 ### Install
 
@@ -11,46 +9,43 @@ Server
 ```
 $ go get -v github.com/jpillora/chisel/chiseld
 $ chiseld --help
-
-	Usage: chiseld [--host 0.0.0.0] [--port 8080] [--auth str]
-
-	host defines the HTTP listening host – the
-	network interface (defaults to 0.0.0.0). You
-	may also set the HOST environment variable.
-
-	port defines the HTTP listening port (defaults
-	to 8080). You may also set the PORT environment
-	variable.
-
-	auth specifies the exact authentication string
-	the client must provide to attain access. You
-	may also set the AUTH environment variable.
 ```
 
 Forwarder
 
 ```
 $ go get -v github.com/jpillora/chisel/chisel-forward
-$ chisel-forward --help
+```
 
-	Usage: chisel-forward [--auth str] server remote [remote] [remote] ...
+### Demo
 
-	where 'server' is the URL to the chiseld server
+A Heroku app is running `chiseld` on the public HTTP port. This app
+is also running a file server on 3000 (which is normally inaccessible
+due to Heroku's firewall). However, if we tunnel in with:
 
-	where 'remote' is a remote connection via the server, in the form
-		example.com:3000 (which means http://0.0.0.0:3000 => http://example.com:3000)
-		3000:google.com:80 (which means http://0.0.0.0:3000 => http://google.com:80)
+```
+$ chisel-forward --auth foobar https://chisel-demo.herokuapp.com/ 3000
 ```
 
+Then open [http://localhost:3000/](http://localhost:3000/), we should
+see a directory listing of this app's root.
+
 ### Usage
 
+Both command-line programs have useful help text, see `chiseld --help` and `chisel-forward --help`.
+
+Eventually, a programmatic API will be documented and available.
+
+### Security
+
+Currently, secure communications are attained by hosting your HTTP server behind a TLS proxy. Thereby upgrading your server to HTTPS. In the future, the server will allow your to pass in TLS credentials and make use of Go's TLS (HTTPS) server.
 
 ### Performance
 
 With crowbar, I was getting extremely slow transfer times
 
 ```
-#tab 1 (basic file server)
+#tab 1 (local file server)
 $ serve -p 4000
 
 #tab 2 (tunnel server)
@@ -65,9 +60,9 @@ $ time curl -s "127.0.0.1:3000/largefile.bin" > /dev/null
        74.74 real         2.37 user         6.74 sys
 ```
 
-Here, `largefile.bin` (~200MB) is transferred in 1m14s over localhost (also has high CPU utilisation).
+Here, `largefile.bin` (~200MB) is transferred in 1m14s (along with high CPU utilisation).
 
-Enter `chisel`, lets swap in `chiseld` and `chisel-forward`:
+Enter `chisel`, lets swap in `chiseld` and `chisel-forward`
 
 ```
 #tab 2 (tunnel server)
@@ -77,14 +72,29 @@ $ chiseld --auth foo
 $ chisel-forward --auth foo http://localhost:8080 3000:4000
 2015/02/27 16:13:43 Connected to http://localhost:8080
 2015/02/27 16:13:43 Proxy 0.0.0.0:3000 => 0.0.0.0:4000 enabled
+```
 
+And now we'll run the test again
+
+```
 #tab 4 (transfer test)
 $ time curl -s "127.0.0.1:3000/largefile.bin" > /dev/null
        0.60 real         0.05 user         0.14 sys
 ```
 
 Here, the same file was transferred in 0.6s
 
+### Overview
+
+![overview](https://docs.google.com/drawings/d/1p53VWxzGNfy8rjr-mW8pvisJmhkoLl82vAgctO_6f1w/pub?w=960&h=720)
+
+### Todo
+
+* User file with list of whitelisted remotes
+* TLS server configuration
+* Expose a stats page for proxy throughput
+* Tests along with benchmarks
+
 #### MIT License
 
 Copyright © 2014 Jaime Pillora <[email protected]>

chisel-forward/client/client.go

@@ -3,11 +3,12 @@ package client
 import (
 	"errors"
 	"fmt"
-	"log"
 	"net"
 	"net/url"
 	"regexp"
 	"strings"
+	"sync"
+	"time"
 
 	"github.com/hashicorp/yamux"
 	"github.com/jpillora/chisel"
@@ -79,16 +80,27 @@ func (c *Client) Start() error {
 		return err
 	}
 
+	//closed state
 	markClosed := make(chan bool)
-	isClosed := false
+	var o sync.Once
+	closed := func() {
+		close(markClosed)
+	}
+	go func() {
+		for {
+			if session.IsClosed() {
+				o.Do(closed)
+				break
+			}
+			time.Sleep(time.Second)
+		}
+	}()
 
 	//proxies all use this function
 	openStream := func() (net.Conn, error) {
 		stream, err := session.Open()
 		if err != nil {
-			if !isClosed {
-				close(markClosed)
-			}
+			o.Do(closed)
 			return nil, err
 		}
 		return stream, nil
@@ -101,9 +113,8 @@ func (c *Client) Start() error {
 		c.proxies = append(c.proxies, proxy)
 	}
 
-	log.Printf("Connected to %s\n", c.config.Server)
+	fmt.Printf("Connected to %s\n", c.config.Server)
 	<-markClosed
-	isClosed = true
-	log.Printf("Disconnected\n")
+	fmt.Printf("Disconnected\n")
 	return nil
 }

chisel-forward/client/proxy.go

@@ -2,7 +2,6 @@ package client
 
 import (
 	"encoding/binary"
-	"log"
 	"net"
 
 	"github.com/jpillora/chisel"
@@ -27,15 +26,15 @@ func (p *Proxy) start() {
 
 	l, err := net.Listen("tcp4", p.remote.LocalHost+":"+p.remote.LocalPort)
 	if err != nil {
-		log.Printf("Proxy %s failed: %s", p.remote, err)
+		chisel.Printf("Proxy [%d] Failed to start: %s", p.id, err)
 		return
 	}
 
-	log.Printf("Proxy %s enabled", p.remote)
+	chisel.Printf("Proxy [%d] Enabled (%s)", p.id, p.remote)
 	for {
 		src, err := l.Accept()
 		if err != nil {
-			log.Println(err)
+			chisel.Printf("%s", err)
 			return
 		}
 		go p.accept(src)
@@ -46,11 +45,11 @@ func (p *Proxy) accept(src net.Conn) {
 	p.count++
 	c := p.count
 
-	log.Printf("[#%d] accept conn %d", p.id, c)
+	chisel.Printf("Proxy [%d] Connection [%d] Open", p.id, c)
 
 	dst, err := p.openStream()
 	if err != nil {
-		log.Println(err)
+		chisel.Printf("%s", err)
 		return
 	}
 
@@ -60,7 +59,7 @@ func (p *Proxy) accept(src net.Conn) {
 	dst.Write(b)
 
 	//then pipe
-	chisel.Pipe(src, dst)
+	s, r := chisel.Pipe(src, dst)
 
-	log.Printf("[#%d] close conn %d", p.id, c)
+	chisel.Printf("Proxy [%d] Connection [%d] Closed (sent %d received %d)", p.id, c, s, r)
 }

chisel-forward/main.go

@@ -6,18 +6,34 @@ import (
 	"log"
 	"os"
 
+	"github.com/jpillora/chisel"
 	"github.com/jpillora/chisel/chisel-forward/client"
 )
 
 const help = `
 
-	Usage: chisel-forward [--auth str] server remote [remote] [remote] ...
+	Usage: chisel-forward [--auth AUTH] server remote [remote] [remote] ...
 
-	where 'server' is the URL to the chiseld server
+	auth specifies the optional authenication string
+	used by the server.
 
-	where 'remote' is a remote connection via the server, in the form
-		example.com:3000 (which means http://0.0.0.0:3000 => http://example.com:3000)
-		3000:google.com:80 (which means http://0.0.0.0:3000 => http://google.com:80)
+	server is the URL to the chiseld server.
+
+	remote is a remote connection via the server, which
+	comes in the form:
+		<local-host>:<local-port>:<remote-host>:<remote-port>
+
+		* Only remote-port is required.
+		* local-port defaults to remote-port.
+		* local-host defaults to 0.0.0.0 (all interfaces).
+		* remote-host defaults to localhost.
+
+		example remotes
+
+			3000
+			example.com:3000
+			3000:google.com:80
+			192.168.0.5:3000:google.com:80
 
 	Read more:
 	https://github.com/jpillora/chisel
@@ -38,6 +54,8 @@ func main() {
 	server := args[0]
 	remotes := args[1:]
 
+	chisel.Debug = true
+
 	c, err := client.NewClient(*auth, server, remotes)
 	if err != nil {
 		log.Fatal(err)

chiseld/main.go

@@ -3,13 +3,15 @@ package main
 import (
 	"flag"
 	"fmt"
+	"log"
 	"os"
 
+	"github.com/jpillora/chisel"
 	"github.com/jpillora/chisel/chiseld/server"
 )
 
 const help = `
-	Usage: chiseld [--host 0.0.0.0] [--port 8080] [--auth str]
+	Usage: chiseld [--host 0.0.0.0] [--port 8080] [--auth AUTH] [--proxy PROXY]
 
 	host defines the HTTP listening host – the
 	network interface (defaults to 0.0.0.0). You
@@ -23,6 +25,10 @@ const help = `
 	the client must provide to attain access. You
 	may also set the AUTH environment variable.
 
+	proxy specifies the default proxy target to use
+	when chiseld receives a normal HTTP request. You
+	may also set the PROXY environment variable.
+
 	Read more:
 	https://github.com/jpillora/chisel
 
@@ -33,6 +39,7 @@ func main() {
 	hostf := flag.String("host", "", "")
 	portf := flag.String("port", "", "")
 	authf := flag.String("auth", "", "")
+	proxyf := flag.String("proxy", "", "")
 	flag.Usage = func() {
 		fmt.Fprintf(os.Stderr, help)
 		os.Exit(1)
@@ -60,5 +67,19 @@ func main() {
 		auth = os.Getenv("AUTH")
 	}
 
-	server.NewServer(auth).Start(host, port)
+	proxy := *proxyf
+	if proxy == "" {
+		proxy = os.Getenv("PROXY")
+	}
+
+	chisel.Debug = true
+
+	s, err := server.NewServer(auth, proxy)
+	if err != nil {
+		log.Fatal(err)
+	}
+	err = s.Start(host, port)
+	if err != nil {
+		log.Fatal(err)
+	}
 }

chiseld/server/endpoint.go

@@ -1,45 +1,47 @@
 package server
 
 import (
-	"log"
 	"net"
 
 	"github.com/jpillora/chisel"
 )
 
 type Endpoint struct {
-	id      int
-	count   int
-	addr    string
-	session chan net.Conn
+	w        *WebSocket
+	id       int
+	count    int
+	addr     string
+	sessions chan net.Conn
 }
 
-func NewEndpoint(id int, addr string) *Endpoint {
+func NewEndpoint(w *WebSocket, id int, addr string) *Endpoint {
 	return &Endpoint{
-		id:      id,
-		addr:    addr,
-		session: make(chan net.Conn),
+		w:        w,
+		id:       id,
+		addr:     addr,
+		sessions: make(chan net.Conn),
 	}
 }
 
 func (e *Endpoint) start() {
+	chisel.Printf("Websocket [%d] Proxy [%d] Activate (%s)", e.w.id, e.id, e.addr)
 	//waiting for incoming streams
-	for stream := range e.session {
+	for stream := range e.sessions {
 		go e.pipe(stream)
 	}
 }
 
 func (e *Endpoint) pipe(src net.Conn) {
 	dst, err := net.Dial("tcp", e.addr)
 	if err != nil {
-		log.Println(err)
+		chisel.Printf("%s", err)
 		src.Close()
 		return
 	}
 
 	e.count++
 	c := e.count
-	log.Printf("[#%d] openned connection %d", e.id, c)
+	chisel.Printf("Websocket [%d] Proxy [%d] Connection [%d] Open", e.w.id, e.id, c)
 	chisel.Pipe(src, dst)
-	log.Printf("[#%d] closed connection %d", e.id, c)
+	chisel.Printf("Websocket [%d] Proxy [%d] Connection [%d] Closed", e.w.id, e.id, c)
 }