harald

README

harald

(like a herald, but better)

Harald has one goal and one goal only: forward traffic if you want it.

Config

The config can be written in:

• YAML (*.yml or *.yaml)
• JSON (*.json)
• TOML (*.toml)

Version 1 has been deprecated and is no longer accepted.

See the examples/ directory for full config examples.

Config version 2 is structured like this:

# Version of this config file.
version: 2
# See https://pkg.go.dev/log/slog#Level.UnmarshalJSON for details.
log_level: "debug"
# Default dial_timeout, can be overwritten in a rule, must be in a format that
# can be parsed by https://pkg.go.dev/time#ParseDuration.
dial_timeout: "10ms"
# Whether to start all listeners right away.
enable_listeners: false
# The rules for forwarding traffic, each rule has a name which will be used for
# logging.
rules:
  http: { }
  ssh: { }

Rules

A rule looks like this:

# the two arguments passed to https://pkg.go.dev/net#Listen
listen:
  network: tcp
  address: :60001
# the two arguments passed to https://pkg.go.dev/net#Dial
connect:
  network: tcp
  address: localhost:8080
# configuration for server-side TLS
tls:
  # protocols offered via the ALPN TLS extension
  application_protocols: [ "http/1.1", "h2" ]
  # the level as described at https://pkg.go.dev/crypto/tls#ClientAuthType
  client_auth: 5
  # server certificate as PEM encoded
  certificate: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  # key for the server certificate
  key: |
    -----BEGIN EC PRIVATE KEY-----
    ...
    -----END EC PRIVATE KEY-----
  # client CAs, will be used according to the client_auth level
  client_cas: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

Documentation

Overview

Package harald contains the core logic of harald.

Harald is a great guy. He takes care of forwarding connections and listens to your needs. Get him started with SIGUSR1, stop him with SIGUSR2 and shut him down for good with SIGTERM. Currently only unix-like systems (as determined by the go build constraint `unix`) are supported due to the dependency to the process signals.

Any logging is done through the default logger of log/slog. Consult the documentation for how to configure it.

Index

• Constants
• func Harald(c Config, signals <-chan os.Signal) (err error)
• type Config
  • func LoadConfig(path string) (Config, error)
• type Duration
  • func (d *Duration) Duration() time.Duration
  • func (d *Duration) UnmarshalText(text []byte) error
• type ForwardRule
  • func (r ForwardRule) NewForwarder(name string, defaultDialTimeout time.Duration) (*Forwarder, error)
• type Forwarder
  • func (f *Forwarder) Start() (err error)
  • func (f *Forwarder) Stop()
  • func (f *Forwarder) String() string
• type Forwarders
  • func (forwarders Forwarders) Start()
  • func (forwarders Forwarders) Stop()
• type NetConf
• type TLS
  • func (t *TLS) Config() (conf *tls.Config, err error)

Constants

const (
	KeyForwarder    = "forwarder"
	KeyError        = "error"
	KeySignal       = "signal"
	KeyPid          = "pid"
	KeyBytesWritten = "bytes-written"
	KeyConnId       = "conn-id"
)

Functions

func Harald

func Harald(c Config, signals <-chan os.Signal) (err error)

Harald is the main entrypoint. The config controls the behaviour and the signals channel is used to bring up / shut down the listeners and stop the execution. The channel should be subscribed to SIGTERM, SIGUSR1 and SIGUSR2.

Types

type Config

type Config struct {
	Version         int                    `json:"version" yaml:"version" toml:"version"`
	LogLevel        slog.Level             `json:"log_level" yaml:"log_level" toml:"log_level"`
	DialTimeout     Duration               `json:"dial_timeout" yaml:"dial_timeout" toml:"dial_timeout"`
	EnableListeners bool                   `json:"enable_listeners" yaml:"enable_listeners" toml:"enable_listeners"`
	Rules           map[string]ForwardRule `json:"rules" yaml:"rules" toml:"rules"`
}

func LoadConfig

func LoadConfig(path string) (Config, error)

type Duration

type Duration time.Duration

func (*Duration) Duration

func (d *Duration) Duration() time.Duration

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(text []byte) error

type ForwardRule

type ForwardRule struct {
	DialTimeout Duration `json:"dial_timeout" yaml:"dial_timeout" toml:"dial_timeout"`
	Listen      NetConf  `json:"listen" yaml:"listen" toml:"listen"`
	Connect     NetConf  `json:"connect" yaml:"connect" toml:"connect"`
	TLS         *TLS     `json:"tls" yaml:"tls" toml:"tls"`
}

func (ForwardRule) NewForwarder

func (r ForwardRule) NewForwarder(name string, defaultDialTimeout time.Duration) (*Forwarder, error)

NewForwarder initialize a new forwarder based on the rule it's called on and the additional parameters passed in.

type Forwarder

type Forwarder struct {
	ForwardRule
	// contains filtered or unexported fields
}

func (*Forwarder) Start

func (f *Forwarder) Start() (err error)

Start opens a new listener.

func (*Forwarder) Stop

func (f *Forwarder) Stop()

Stop will close the listener if it is open. The reference to the listener is also set to nil to prevent further usage. TODO: does this need explicit synchronization?

func (*Forwarder) String

func (f *Forwarder) String() string

String representation of the Forwarder. The format of the addresses is inspired by the '-i' argument of lsof.

type Forwarders

type Forwarders []*Forwarder

Forwarders maintains a list of pointers to Forwarder. It holds pointers because each struct may maintain data that can not be copied.

func (Forwarders) Start

func (forwarders Forwarders) Start()

Start all forwarders in the list. Logs errors encountered while starting a forwarder but continues starting the forwarders.

func (Forwarders) Stop

func (forwarders Forwarders) Stop()

Stop all forwarders in the list.

type NetConf

type NetConf struct {
	Network string `json:"network" yaml:"network"`
	Address string `json:"address" yaml:"address"`
}

type TLS

type TLS struct {
	Certificate string `json:"certificate" yaml:"certificate" toml:"certificate"`
	Key         string `json:"key" yaml:"key" toml:"key"`
	ClientCAs   string `json:"client_cas" yaml:"client_cas" toml:"client_cas"`
	// ApplicationProtocols offered via ALPN in order of preference. See the
	// IANA registry for a list of options:
	// https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
	ApplicationProtocols []string `json:"application_protocols" yaml:"application_protocols" toml:"application_protocols"`
	// See the go documentation for details:
	// https://pkg.go.dev/crypto/tls#ClientAuthType
	ClientAuth tls.ClientAuthType `json:"client_auth" yaml:"client_auth" toml:"client_auth"`
}

TLS configuration for the server side.

func (*TLS) Config

func (t *TLS) Config() (conf *tls.Config, err error)