hbone

README

HTTP Based Overlay Network (HBONE)

HTTP Based Overlay Network (HBONE) is the protocol used by Istio for communication between workloads in the mesh. At a high level, the protocol consists of tunneling TCP connections over HTTP/2 CONNECT, over mTLS.

Specification

TODO

Implementations

Clients

CLI

A CLI client is available using the client binary.

Usage examples:

go install ./pkg/test/echo/cmd/client
# Send request to 127.0.0.1:8080 (Note only IPs are supported) via an HBONE proxy on port 15008
client --hbone-client-cert tests/testdata/certs/cert.crt --hbone-client-key tests/testdata/certs/cert.key \
  http://127.0.0.1:8080 \
  --hbone 127.0.0.1:15008

Golang

An (unstable) library to make HBONE connections is available at pkg/hbone.

Usage example:

d := hbone.NewDialer(hbone.Config{
    ProxyAddress: "1.2.3.4:15008",
    Headers: map[string][]string{
        "some-addition-metadata": {"test-value"},
    },
    TLS:          nil, // TLS is strongly recommended in real world
})
client, _ := d.Dial("tcp", testAddr)
client.Write([]byte("hello world"))

Server

Server CLI

A CLI client is available using the server binary.

Usage examples:

go install ./pkg/test/echo/cmd/server
# Serve on port 15008 (default) with TLS
server --tls 15008 --crt tests/testdata/certs/cert.crt --key tests/testdata/certs/cert.key

Server Golang Library

An (unstable) library to run an HBONE server is available at pkg/hbone.

Usage example:

s := hbone.NewServer()
// TLS is strongly recommended in real world
l, _ := net.Listen("tcp", "0.0.0.0:15008")
s.Serve(l)

Documentation

Index

• func NewDoubleHBONEServer(tlsConfig *tls.Config) *http.Server
• func NewServer() *http.Server
• func TLSDialWithDialer(dialer Dialer, network, addr string, config *tls.Config) (*tls.Conn, error)
• type CloseWriter
• type Config
• type Dialer
  • func NewDialer(cfg Config) Dialer
  • func NewDoubleDialer(outerCfg Config, innerTLSConfig *tls.Config) Dialer

Functions

func NewDoubleHBONEServer

func NewDoubleHBONEServer(tlsConfig *tls.Config) *http.Server

func NewServer

func NewServer() *http.Server

func TLSDialWithDialer

func TLSDialWithDialer(dialer Dialer, network, addr string, config *tls.Config) (*tls.Conn, error)

TLSDialWithDialer is an implementation of tls.DialWithDialer that accepts a generic Dialer

Types

type CloseWriter

type CloseWriter interface {
	CloseWrite() error
}

CloseWriter is one of possible interfaces implemented by Out to send a FIN, without closing the input. Some writers only do this when Close is called.

type Config

type Config struct {
	// ProxyAddress defines the address of the HBONE proxy we are connecting to
	ProxyAddress string
	Headers      http.Header
	TLS          *tls.Config
	Timeout      *time.Duration
}

Config defines the configuration for a given dialer. All fields other than ProxyAddress are optional

type Dialer

type Dialer interface {
	proxy.Dialer
	proxy.ContextDialer
}

func NewDialer

func NewDialer(cfg Config) Dialer

NewDialer creates a Dialer that proxies connections over HBONE to the configured proxy.

func NewDoubleDialer

func NewDoubleDialer(outerCfg Config, innerTLSConfig *tls.Config) Dialer

NewDialer creates a Dialer that proxies connections over HBONE to the configured proxy.