udpgw

README

This is an implementation of a UDPGW server written in Go.

USAGE

$ cd cmd
$ go build -o server
$ ./server -port 7300 generate
$ ./server run

ASSUMPTIONS

You have Go installed.

Documentation

Index

• Constants
• func CommonLogger(traceLogger *TraceLogger) *commonLogger
• func GenerateConfig(params *GenerateConfigParams) ([]byte, error)
• func InitLogging(config *Config) (retErr error)
• func IsLogLevelDebug() bool
• func NewIntentionalPanicError(errorMessage string) error
• func NewLogWriter() *io.PipeWriter
• func StartServer(configJSON []byte) (retErr error)
• type Config
  • func LoadConfig(configJSON []byte) (*Config, error)
  • func (config *Config) GetLogFileReopenConfig() (int, bool, os.FileMode)
• type CustomJSONFormatter
  • func (f *CustomJSONFormatter) Format(entry *logrus.Entry) ([]byte, error)
• type DNSResolver
  • func NewDNSResolver(defaultResolver string) (*DNSResolver, error)
  • func (dns *DNSResolver) Get() net.IP
  • func (dns *DNSResolver) GetAll() []net.IP
  • func (dns *DNSResolver) GetAllIPv4() []net.IP
  • func (dns *DNSResolver) GetAllIPv6() []net.IP
• type GenerateConfigParams
• type IntentionalPanicError
  • func (err IntentionalPanicError) Error() string
• type LogFields
  • func (a LogFields) Add(b LogFields)
• type PanickingLogWriter
  • func NewPanickingLogWriter(name string, writer io.Writer) *PanickingLogWriter
  • func (w *PanickingLogWriter) Write(p []byte) (n int, err error)
• type TraceLogger
  • func (logger *TraceLogger) LogPanicRecover(recoverValue interface{}, stack []byte)
  • func (logger *TraceLogger) LogRawFieldsWithTimestamp(fields LogFields)
  • func (logger *TraceLogger) WithTrace() *logrus.Entry
  • func (logger *TraceLogger) WithTraceFields(fields LogFields) *logrus.Entry
• type TunnelServer
  • func NewTunnelServer(config *Config, dnsResolver *DNSResolver, shutdownBroadcast <-chan struct{}) (*TunnelServer, error)
  • func (server *TunnelServer) Run() error

Constants

const (
	DEFAULT_LOG_FILE_REOPEN_RETRIES = 25
	PERIODIC_GARBAGE_COLLECTION     = 120 * time.Second
	DEFAULT_UDPGW_PORT              = 7300
	DEFAULT_CONFIG_FILE_NAME        = "udpgw.json"
)

const (
	DNS_SYSTEM_CONFIG_FILENAME      = "/etc/resolv.conf"
	DNS_SYSTEM_CONFIG_RELOAD_PERIOD = 5 * time.Second
	DNS_RESOLVER_PORT               = 53
)

Functions

func CommonLogger

func CommonLogger(traceLogger *TraceLogger) *commonLogger

CommonLogger wraps a TraceLogger instance with an interface that conforms to common.Logger. This is used to make the TraceLogger available to other packages that don't import the "server" package.

func GenerateConfig

func GenerateConfig(params *GenerateConfigParams) ([]byte, error)

func InitLogging

func InitLogging(config *Config) (retErr error)

InitLogging configures a logger according to the specified config params. If not called, the default logger set by the package init() is used. Concurrency notes: this should only be called from the main goroutine; InitLogging only has effect on the first call, as the logging facilities it initializes may be in use by other goroutines after that point.

func IsLogLevelDebug

func IsLogLevelDebug() bool

func NewIntentionalPanicError

func NewIntentionalPanicError(errorMessage string) error

NewIntentionalPanicError creates a new IntentionalPanicError.

func NewLogWriter

func NewLogWriter() *io.PipeWriter

NewLogWriter returns an io.PipeWriter that can be used to write to the global logger. Caller must Close() the writer.

func StartServer

func StartServer(configJSON []byte) (retErr error)

Types

type Config

type Config struct {

	// LogLevel specifies the log level. Valid values are:
	// panic, fatal, error, warn, info, debug
	LogLevel string

	// LogFilename specifies the path of the file to log
	// to. When blank, logs are written to stderr.
	LogFilename string

	// LogFileReopenRetries specifies how many retries, each with a 1ms delay,
	// will be attempted after reopening a rotated log file fails. Retries
	// mitigate any race conditions between writes/reopens and file operations
	// performed by external log managers, such as logrotate.
	//
	// When omitted, DEFAULT_LOG_FILE_REOPEN_RETRIES is used.
	LogFileReopenRetries *int

	// LogFileCreateMode specifies that the server should create a new
	// log file when one is not found, such as after rotation with logrotate
	// configured with nocreate. The value is the os.FileMode value to use when
	// creating the file.
	//
	// When omitted, the server does not create log files.
	LogFileCreateMode *int

	// SkipPanickingLogWriter disables panicking when
	// unable to write any logs.
	SkipPanickingLogWriter bool

	// HostID is the ID of the server host; this is used for
	// event logging.
	HostID string

	// UdpgwPort is the port at which the udpgw server should run.
	UdpgwPort uint16

	// DNSResolverIPAddress specifies the IP address of a DNS server
	// to be used when "/etc/resolv.conf" doesn't exist or fails to
	// parse. When blank, "/etc/resolv.conf" must contain a usable
	// "nameserver" entry.
	DNSResolverIPAddress string
}

Config specifies the configuration and behavior of a Udpgw server.

func LoadConfig

func LoadConfig(configJSON []byte) (*Config, error)

LoadConfig loads and validates a JSON encoded server config.

func (*Config) GetLogFileReopenConfig

func (config *Config) GetLogFileReopenConfig() (int, bool, os.FileMode)

GetLogFileReopenConfig gets the reopen retries, and create/mode inputs for rotate.NewRotatableFileWriter, which is used when writing to log files.

By default, we expect the log files to be managed by logrotate, with logrotate configured to re-create the next log file after rotation. As described in the documentation for rotate.NewRotatableFileWriter, and as observed in production, we occasionally need retries when attempting to reopen the log file post-rotation; and we avoid conflicts, and spurious re-rotations, by disabling file create in rotate.NewRotatableFileWriter. In large scale production, incidents requiring retry are very rare, so the retry delay is not expected to have a significant impact on performance.

The defaults may be overriden in the Config.

type CustomJSONFormatter

type CustomJSONFormatter struct {
}

CustomJSONFormatter is a customized version of logrus.JSONFormatter

func (*CustomJSONFormatter) Format

func (f *CustomJSONFormatter) Format(entry *logrus.Entry) ([]byte, error)

Format implements logrus.Formatter. This is a customized version of the standard logrus.JSONFormatter adapted from: https://github.com/Sirupsen/logrus/blob/f1addc29722ba9f7651bc42b4198d0944b66e7c4/json_formatter.go

The changes are: - "time" is renamed to "timestamp" - there's an option to omit the standard "msg" and "level" fields

type DNSResolver

type DNSResolver struct {
	common.ReloadableFile
	// contains filtered or unexported fields
}

DNSResolver maintains fresh DNS resolver values, monitoring "/etc/resolv.conf" on platforms where it is available; and otherwise using a default value.

func NewDNSResolver

func NewDNSResolver(defaultResolver string) (*DNSResolver, error)

NewDNSResolver initializes a new DNSResolver, loading it with fresh resolver values. The load must succeed, so either "/etc/resolv.conf" must contain valid "nameserver" lines with a DNS server IP address, or a valid "defaultResolver" default value must be provided. On systems without "/etc/resolv.conf", "defaultResolver" is required.

The resolver is considered stale and reloaded if last checked more than 5 seconds before the last Get(), which is similar to frequencies in other implementations:

• https://golang.org/src/net/dnsclient_unix.go, resolverConfig.tryUpdate: 5 seconds

• https://github.com/ambrop72/badvpn/blob/master/udpgw/udpgw.c, maybe_update_dns: 2 seconds

func (*DNSResolver) Get

func (dns *DNSResolver) Get() net.IP

Get returns one of the cached resolvers, selected at random, after first updating the cached values if they're stale. If reloading fails, the previous values are used.

Randomly selecting any one of the configured resolvers is expected to be more resiliant to failure; e.g., if one of the resolvers becomes unavailable.

func (*DNSResolver) GetAll

func (dns *DNSResolver) GetAll() []net.IP

GetAll returns a list of all DNS resolver addresses. Cached values are updated if they're stale. If reloading fails, the previous values are used.

func (*DNSResolver) GetAllIPv4

func (dns *DNSResolver) GetAllIPv4() []net.IP

GetAllIPv4 returns a list of all IPv4 DNS resolver addresses. Cached values are updated if they're stale. If reloading fails, the previous values are used.

func (*DNSResolver) GetAllIPv6

func (dns *DNSResolver) GetAllIPv6() []net.IP

GetAllIPv6 returns a list of all IPv6 DNS resolver addresses. Cached values are updated if they're stale. If reloading fails, the previous values are used.

type GenerateConfigParams

type GenerateConfigParams struct {
	LogFilename            string
	SkipPanickingLogWriter bool
	LogLevel               string
	UdpgwPort              uint16
}

GenerateConfigParams specifies customizations to be applied to a generated server config.

type IntentionalPanicError

type IntentionalPanicError struct {
	// contains filtered or unexported fields
}

IntentionalPanicError is an error type that is used when calling panic() in a situation where recovers should propagate the panic.

func (IntentionalPanicError) Error

func (err IntentionalPanicError) Error() string

Error implements the error interface.

type LogFields

type LogFields logrus.Fields

LogFields is an alias for the field struct in the underlying logging package.

func (LogFields) Add

func (a LogFields) Add(b LogFields)

Add copies log fields from b to a, skipping fields which already exist, regardless of value, in a.

type PanickingLogWriter

type PanickingLogWriter struct {
	// contains filtered or unexported fields
}

PanickingLogWriter wraps an io.Writer and intentionally panics when a Write() fails.

func NewPanickingLogWriter

func NewPanickingLogWriter(
	name string, writer io.Writer) *PanickingLogWriter

NewPanickingLogWriter creates a new PanickingLogWriter.

func (*PanickingLogWriter) Write

func (w *PanickingLogWriter) Write(p []byte) (n int, err error)

Write implements the io.Writer interface.

type TraceLogger

type TraceLogger struct {
	*logrus.Logger
}

TraceLogger adds single frame stack trace information to the underlying logging facilities.

func (*TraceLogger) LogPanicRecover

func (logger *TraceLogger) LogPanicRecover(recoverValue interface{}, stack []byte)

LogPanicRecover calls LogRawFieldsWithTimestamp with standard fields for logging recovered panics.

func (*TraceLogger) LogRawFieldsWithTimestamp

func (logger *TraceLogger) LogRawFieldsWithTimestamp(fields LogFields)

LogRawFieldsWithTimestamp directly logs the supplied fields adding only an additional "timestamp" field; and "host_id" and "build_rev" fields identifying this server and build. The stock "msg" and "level" fields are omitted. This log is emitted at the Error level. This function exists to support API logs which have neither a natural message nor severity; and omitting these values here makes it easier to ship these logs to existing API log consumers. Note that any existing "trace"/"host_id"/"build_rev" field will be renamed to "field.<name>".

func (*TraceLogger) WithTrace

func (logger *TraceLogger) WithTrace() *logrus.Entry

WithTrace adds a "trace" field containing the caller's function name and source file line number; and "host_id" and "build_rev" fields identifying this server and build. Use this function when the log has no fields.

func (*TraceLogger) WithTraceFields

func (logger *TraceLogger) WithTraceFields(fields LogFields) *logrus.Entry

WithTraceFields adds a "trace" field containing the caller's function name and source file line number; and "host_id" and "build_rev" fields identifying this server and build. Use this function when the log has fields. Note that any existing "trace"/"host_id"/"build_rev" field will be renamed to "field.<name>".

type TunnelServer

type TunnelServer struct {
	// contains filtered or unexported fields
}

func NewTunnelServer

func NewTunnelServer(
	config *Config,
	dnsResolver *DNSResolver,
	shutdownBroadcast <-chan struct{}) (*TunnelServer, error)

func (*TunnelServer) Run

func (server *TunnelServer) Run() error