srslog

README

srslog

Go has a syslog package in the standard library, but it has the following shortcomings:

1. It doesn't have TLS support
2. According to bradfitz on the Go team, it is no longer being maintained.

I agree that it doesn't need to be in the standard library. So, I've followed Brad's suggestion and have made a separate project to handle syslog.

This code was taken directly from the Go project as a base to start from.

However, this does have TLS support.

Usage

Basic usage retains the same interface as the original syslog package. We only added to the interface where required to support new functionality.

Switch from the standard library:

import(
    //"log/syslog"
    syslog "github.com/RackSec/srslog"
)

You can still use it for local syslog:

w, err := syslog.Dial("", "", syslog.LOG_ERR, "testtag")

Or to unencrypted UDP:

w, err := syslog.Dial("udp", "192.168.0.50:514", syslog.LOG_ERR, "testtag")

Or to unencrypted TCP:

w, err := syslog.Dial("tcp", "192.168.0.51:514", syslog.LOG_ERR, "testtag")

But now you can also send messages via TLS-encrypted TCP:

w, err := syslog.DialWithTLSCertPath("tcp+tls", "192.168.0.52:514", syslog.LOG_ERR, "testtag", "/path/to/servercert.pem")

And if you need more control over your TLS configuration :

pool := x509.NewCertPool()
serverCert, err := ioutil.ReadFile("/path/to/servercert.pem")
if err != nil {
    return nil, err
}
pool.AppendCertsFromPEM(serverCert)
config := tls.Config{
    RootCAs: pool,
}

w, err := DialWithTLSConfig(network, raddr, priority, tag, &config)

(Note that in both TLS cases, this uses a self-signed certificate, where the remote syslog server has the keypair and the client has only the public key.)

And then to write log messages, continue like so:

if err != nil {
    log.Fatal("failed to connect to syslog:", err)
}
defer w.Close()

w.Alert("this is an alert")
w.Crit("this is critical")
w.Err("this is an error")
w.Warning("this is a warning")
w.Notice("this is a notice")
w.Info("this is info")
w.Debug("this is debug")
w.Write([]byte("these are some bytes"))

If you need further control over connection attempts, you can use the DialWithCustomDialer function. To continue with the DialWithTLSConfig example:

netDialer := &net.Dialer{Timeout: time.Second*5} // easy timeouts
realNetwork := "tcp" // real network, other vars your dail func can close over
dial := func(network, addr string) (net.Conn, error) {
    // cannot use "network" here as it'll simply be "custom" which will fail
    return tls.DialWithDialer(netDialer, realNetwork, addr, &config)
}

w, err := DialWithCustomDialer("custom", "192.168.0.52:514", syslog.LOG_ERR, "testtag", dial)

Your custom dial func can set timeouts, proxy connections, and do whatever else it needs before returning a net.Conn.

Generating TLS Certificates

We've provided a script that you can use to generate a self-signed keypair:

pip install cryptography
python script/gen-certs.py

That outputs the public key and private key to standard out. Put those into .pem files. (And don't put them into any source control. The certificate in the test directory is used by the unit tests, and please do not actually use it anywhere else.)

Running Tests

Run the tests as usual:

go test

But we've also provided a test coverage script that will show you which lines of code are not covered:

script/coverage --html

That will open a new browser tab showing coverage information.

License

This project uses the New BSD License, the same as the Go project itself.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Documentation

Index

• Constants
• Variables
• func DefaultFormatter(timestamp time.Time, p Priority, hostname, tag string, content []byte) []byte
• func DefaultFramer(in []byte) [][]byte
• func NewLogger(p Priority, logFlag int) (*log.Logger, error)
• func RFC3164Formatter(timestamp time.Time, p Priority, hostname, tag string, content []byte) []byte
• func RFC5424Formatter(timestamp time.Time, p Priority, hostname, tag string, content []byte) []byte
• func RFC5425MessageLengthFramer(in []byte) [][]byte
• func UnixFormatter(timestamp time.Time, p Priority, _, tag string, content []byte) []byte
• type DialFunc
• type Formatter
• type Framer
• type Priority
• type Writer
  • func Dial(network, raddr string, priority Priority, tag string) (*Writer, error)
  • func DialWithCustomDialer(network, raddr string, priority Priority, tag string, customDial DialFunc) (*Writer, error)
  • func DialWithTLSCert(network, raddr string, priority Priority, tag string, serverCert []byte) (*Writer, error)
  • func DialWithTLSCertPath(network, raddr string, priority Priority, tag, certPath string) (*Writer, error)
  • func DialWithTLSConfig(network, raddr string, priority Priority, tag string, tlsConfig *tls.Config) (*Writer, error)
  • func New(priority Priority, tag string) (w *Writer, err error)
  • func (w *Writer) Alert(m string) (err error)
  • func (w *Writer) Close() error
  • func (w *Writer) Crit(m string) (err error)
  • func (w *Writer) Debug(m string) (err error)
  • func (w *Writer) Emerg(m string) (err error)
  • func (w *Writer) Err(m string) (err error)
  • func (w *Writer) Info(m string) (err error)
  • func (w *Writer) Notice(m string) (err error)
  • func (w *Writer) SetFormatter(f Formatter)
  • func (w *Writer) SetFramer(f Framer)
  • func (w *Writer) SetHostname(hostname string)
  • func (w *Writer) Warning(m string) (err error)
  • func (w *Writer) Write(b []byte) (int, error)
  • func (w *Writer) WriteWithPriority(p Priority, b []byte) (int, error)
  • func (w *Writer) WriteWithTimestamp(timestamp time.Time, b []byte) (int, error)
  • func (w *Writer) WriteWithTimestampAndPriority(timestamp time.Time, p Priority, b []byte) (int, error)

Constants

const FacilityMask = 0xf8

const SeverityMask = 0x07

Variables

var ErrNilDialFunc = errors.New("srslog: nil DialFunc passed to DialWithCustomDialer")

ErrNilDialFunc is returned from DialWithCustomDialer when a nil DialFunc is passed, avoiding a nil pointer deference panic.

Functions

func DefaultFormatter

func DefaultFormatter(timestamp time.Time, p Priority, hostname, tag string, content []byte) []byte

DefaultFormatter is the original format supported by the Go syslog package, and is a non-compliant amalgamation of 3164 and 5424 that is intended to maximize compatibility.

func DefaultFramer

func DefaultFramer(in []byte) [][]byte

DefaultFramer does nothing, since there is no framing to apply. This is the original behavior of the Go syslog package, and is also typically used for UDP syslog.

func NewLogger

func NewLogger(p Priority, logFlag int) (*log.Logger, error)

NewLogger creates a log.Logger whose output is written to the system log service with the specified priority. The logFlag argument is the flag set passed through to log.New to create the Logger.

func RFC3164Formatter

func RFC3164Formatter(timestamp time.Time, p Priority, hostname, tag string, content []byte) []byte

RFC3164Formatter provides an RFC 3164 compliant message.

func RFC5424Formatter

func RFC5424Formatter(timestamp time.Time, p Priority, hostname, tag string, content []byte) []byte

RFC5424Formatter provides an RFC 5424 compliant message.

func RFC5425MessageLengthFramer

func RFC5425MessageLengthFramer(in []byte) [][]byte

RFC5425MessageLengthFramer prepends the message length to the front of the provided message, as defined in RFC 5425.

func UnixFormatter

func UnixFormatter(timestamp time.Time, p Priority, _, tag string, content []byte) []byte

UnixFormatter omits the hostname, because it is only used locally.

Types

type DialFunc

type DialFunc func(string, string) (net.Conn, error)

DialFunc is the function signature to be used for a custom dialer callback with DialWithCustomDialer

type Formatter

type Formatter func(timestamp time.Time, p Priority, hostname, tag string, content []byte) []byte

Formatter is a type of function that takes the constituent parts of a syslog message and returns a formatted string. A different Formatter is defined for each different syslog protocol we support.

type Framer

type Framer func(in []byte) [][]byte

Framer is a type of function that takes an input string (typically an already-formatted syslog message) and applies "message framing" to it. We have different framers because different versions of the syslog protocol and its transport requirements define different framing behavior.

type Priority

type Priority int

Priority is a combination of the syslog facility and severity. For example, LOG_ALERT | LOG_FTP sends an alert severity message from the FTP facility. The default severity is LOG_EMERG; the default facility is LOG_KERN.

const (

	// From /usr/include/sys/syslog.h.
	// These are the same on Linux, BSD, and OS X.
	LOG_EMERG Priority = iota
	LOG_ALERT
	LOG_CRIT
	LOG_ERR
	LOG_WARNING
	LOG_NOTICE
	LOG_INFO
	LOG_DEBUG
)

const (

	// From /usr/include/sys/syslog.h.
	// These are the same up to LOG_FTP on Linux, BSD, and OS X.
	LOG_KERN Priority = iota << 3
	LOG_USER
	LOG_MAIL
	LOG_DAEMON
	LOG_AUTH
	LOG_SYSLOG
	LOG_LPR
	LOG_NEWS
	LOG_UUCP
	LOG_CRON
	LOG_AUTHPRIV
	LOG_FTP

	LOG_LOCAL0
	LOG_LOCAL1
	LOG_LOCAL2
	LOG_LOCAL3
	LOG_LOCAL4
	LOG_LOCAL5
	LOG_LOCAL6
	LOG_LOCAL7
)

type Writer

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

A Writer is a connection to a syslog server.

func Dial

func Dial(network, raddr string, priority Priority, tag string) (*Writer, error)

Dial establishes a connection to a log daemon by connecting to address raddr on the specified network. Each write to the returned Writer sends a log message with the given facility, severity and tag. If network is empty, Dial will connect to the local syslog server.

func DialWithCustomDialer

func DialWithCustomDialer(network, raddr string, priority Priority, tag string, customDial DialFunc) (*Writer, error)

DialWithCustomDialer establishes a connection by calling customDial. Each write to the returned Writer sends a log message with the given facility, severity and tag. Network must be "custom" in order for this package to use customDial. While network and raddr will be passed to customDial, it is allowed for customDial to ignore them. If customDial is nil, this function returns ErrNilDialFunc.

func DialWithTLSCert

func DialWithTLSCert(network, raddr string, priority Priority, tag string, serverCert []byte) (*Writer, error)

DialWithTLSCert establishes a secure connection to a log daemon by connecting to address raddr on the specified network. It uses serverCert to load a TLS certificate and configure the secure connection.

func DialWithTLSCertPath

func DialWithTLSCertPath(network, raddr string, priority Priority, tag, certPath string) (*Writer, error)

DialWithTLSCertPath establishes a secure connection to a log daemon by connecting to address raddr on the specified network. It uses certPath to load TLS certificates and configure the secure connection.

func DialWithTLSConfig

func DialWithTLSConfig(network, raddr string, priority Priority, tag string, tlsConfig *tls.Config) (*Writer, error)

DialWithTLSConfig establishes a secure connection to a log daemon by connecting to address raddr on the specified network. It uses tlsConfig to configure the secure connection.

func New

func New(priority Priority, tag string) (w *Writer, err error)

New establishes a new connection to the system log daemon. Each write to the returned Writer sends a log message with the given priority and prefix.

func (*Writer) Alert

func (w *Writer) Alert(m string) (err error)

Alert logs a message with severity LOG_ALERT; this overrides the default priority passed to `srslog.New` and the `srslog.Dial*` functions.

func (*Writer) Close

func (w *Writer) Close() error

Close closes a connection to the syslog daemon.

func (*Writer) Crit

func (w *Writer) Crit(m string) (err error)

Crit logs a message with severity LOG_CRIT; this overrides the default priority passed to `srslog.New` and the `srslog.Dial*` functions.

func (*Writer) Debug

func (w *Writer) Debug(m string) (err error)

Debug logs a message with severity LOG_DEBUG; this overrides the default priority passed to `srslog.New` and the `srslog.Dial*` functions.

func (*Writer) Emerg

func (w *Writer) Emerg(m string) (err error)

Emerg logs a message with severity LOG_EMERG; this overrides the default priority passed to `srslog.New` and the `srslog.Dial*` functions.

func (*Writer) Err

func (w *Writer) Err(m string) (err error)

Err logs a message with severity LOG_ERR; this overrides the default priority passed to `srslog.New` and the `srslog.Dial*` functions.

func (*Writer) Info

func (w *Writer) Info(m string) (err error)

Info logs a message with severity LOG_INFO; this overrides the default priority passed to `srslog.New` and the `srslog.Dial*` functions.

func (*Writer) Notice

func (w *Writer) Notice(m string) (err error)

Notice logs a message with severity LOG_NOTICE; this overrides the default priority passed to `srslog.New` and the `srslog.Dial*` functions.

func (*Writer) SetFormatter

func (w *Writer) SetFormatter(f Formatter)

SetFormatter changes the formatter function for subsequent messages.

func (*Writer) SetFramer

func (w *Writer) SetFramer(f Framer)

SetFramer changes the framer function for subsequent messages.

func (*Writer) SetHostname

func (w *Writer) SetHostname(hostname string)

SetHostname changes the hostname for syslog messages if needed.

func (*Writer) Warning

func (w *Writer) Warning(m string) (err error)

Warning logs a message with severity LOG_WARNING; this overrides the default priority passed to `srslog.New` and the `srslog.Dial*` functions.

func (*Writer) Write

func (w *Writer) Write(b []byte) (int, error)

Write sends a log message to the syslog daemon using the default priority passed into `srslog.New` or the `srslog.Dial*` functions.

func (*Writer) WriteWithPriority

func (w *Writer) WriteWithPriority(p Priority, b []byte) (int, error)

WriteWithPriority sends a log message with a custom priority.

func (*Writer) WriteWithTimestamp

func (w *Writer) WriteWithTimestamp(timestamp time.Time, b []byte) (int, error)

WriteWithTimestamp sends a log message with a custom timestamp.

func (*Writer) WriteWithTimestampAndPriority

func (w *Writer) WriteWithTimestampAndPriority(timestamp time.Time, p Priority, b []byte) (int, error)

WriteWithTimestampAndPriority sends a log message with custom timestamp and priority.