syslog

Documentation

Overview

Package syslog provides an RFC 5424 syslog audit.Output implementation supporting TCP, UDP, and TCP+TLS (including mTLS) transport.

Construction

New dials the syslog server immediately — the server must be reachable at construction time:

out, err := syslog.New(&syslog.Config{
    Network: "tcp+tls",
    Address: "syslog.example.com:6514",
    TLSCA:   "/etc/audit/ca.pem",
}, nil) // optional syslog.Metrics

Valid [Config.Network] values: "tcp" (default), "udp", "tcp+tls". Use "tcp+tls" with [Config.TLSCert] and [Config.TLSKey] for mTLS.

Reconnection

TCP and TLS connections are re-established automatically on write failure, up to [Config.MaxRetries] attempts (default 10). UDP is connectionless and does not reconnect, but messages exceeding the UDP MTU are silently truncated by the network.

Recommended import alias:

import auditsyslog "github.com/axonops/go-audit/syslog"

Index

• Constants
• func NewFactory(syslogMetrics Metrics) audit.OutputFactory
• type Config
  • func (c Config) String() string
• type Metrics
• type Output
  • func New(cfg *Config, syslogMetrics Metrics) (*Output, error)
  • func (s *Output) Close() error
  • func (s *Output) DestinationKey() string
  • func (s *Output) Name() string
  • func (s *Output) Write(data []byte) error
  • func (s *Output) WriteWithMetadata(data []byte, meta audit.EventMetadata) error

Examples

• Config (Mtls)
• Config (Tcp)
• Config (Tls)

Constants

const (
	// DefaultAppName is the default application name in the
	// syslog header when [Config.AppName] is empty.
	DefaultAppName = "audit"

	// DefaultFacility is the default syslog facility when
	// [Config.Facility] is empty.
	DefaultFacility = "local0"

	// DefaultMaxRetries is the default number of reconnection
	// attempts before giving up.
	DefaultMaxRetries = 10

	// MaxMaxRetries is the upper bound for MaxRetries. Values above
	// this are rejected to prevent unbounded retry loops.
	MaxMaxRetries = 20
)

Functions

func NewFactory

func NewFactory(syslogMetrics Metrics) audit.OutputFactory

NewFactory returns an audit.OutputFactory that creates syslog outputs from YAML configuration with the provided syslog-specific metrics captured in the closure. Pass nil to disable syslog metrics.

Types

type Config

type Config struct {
	// Network is the transport protocol: "tcp", "udp", or "tcp+tls".
	// Empty defaults to "tcp". Note: UDP syslog may silently truncate
	// or drop messages larger than ~2048 bytes (RFC 5424 §6.1).
	// Use TCP or TCP+TLS for reliable delivery of large audit events.
	Network string

	// Address is the syslog server address in host:port format.
	// REQUIRED; an empty address causes [New] to return
	// an error.
	Address string

	// AppName is the application name in the syslog header.
	// Empty defaults to [DefaultAppName] ("audit").
	AppName string

	// Facility is the syslog facility name. Supported values:
	// kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
	// cron, authpriv, ftp, local0 through local7.
	// Empty defaults to [DefaultFacility] ("local0").
	// Unknown values cause [New] to return an error.
	Facility string

	// TLSCert is the path to the client certificate for mTLS.
	// Both TLSCert and TLSKey must be set for client authentication.
	TLSCert string

	// TLSKey is the path to the client private key for mTLS.
	// Both TLSCert and TLSKey must be set for client authentication.
	TLSKey string

	// TLSCA is the path to the CA certificate for server verification.
	// When set, the server's certificate is verified against this CA.
	TLSCA string

	// TLSPolicy controls TLS version and cipher suite policy. When nil,
	// the default policy (TLS 1.3 only) is used. See [audit.TLSPolicy]
	// for details on enabling TLS 1.2 fallback.
	TLSPolicy *audit.TLSPolicy

	// Hostname overrides the hostname in the syslog RFC 5424 header.
	// When empty, [os.Hostname] is used at construction time. Set this
	// to match the logger-wide host value from [audit.WithHost].
	Hostname string

	// MaxRetries is the maximum number of consecutive reconnection
	// attempts before giving up. Zero defaults to
	// [DefaultMaxRetries] (10).
	MaxRetries int
}

Config holds configuration for Output.

Example (Mtls)

package main

import (
	"fmt"

	"github.com/axonops/go-audit/syslog"
)

func main() {
	// mTLS syslog with client certificate authentication.
	cfg := &syslog.Config{
		Network: "tcp+tls",
		Address: "syslog.example.com:6514",
		TLSCert: "/etc/audit/client-cert.pem",
		TLSKey:  "/etc/audit/client-key.pem",
		TLSCA:   "/etc/audit/ca.pem",
	}
	fmt.Printf("network=%s address=%s cert=%s key=%s ca=%s\n",
		cfg.Network, cfg.Address, cfg.TLSCert, cfg.TLSKey, cfg.TLSCA)
}

Output:
network=tcp+tls address=syslog.example.com:6514 cert=/etc/audit/client-cert.pem key=/etc/audit/client-key.pem ca=/etc/audit/ca.pem

Example (Tcp)

package main

import (
	"fmt"

	"github.com/axonops/go-audit/syslog"
)

func main() {
	// Plain TCP syslog — the simplest configuration.
	cfg := &syslog.Config{
		Network:  "tcp",
		Address:  "syslog.example.com:514",
		Facility: "local0",
		AppName:  "myapp",
	}
	fmt.Printf("network=%s address=%s facility=%s app=%s\n",
		cfg.Network, cfg.Address, cfg.Facility, cfg.AppName)
}

Output:
network=tcp address=syslog.example.com:514 facility=local0 app=myapp

Example (Tls)

package main

import (
	"fmt"

	"github.com/axonops/go-audit/syslog"
)

func main() {
	// TLS syslog with CA verification.
	cfg := &syslog.Config{
		Network: "tcp+tls",
		Address: "syslog.example.com:6514",
		TLSCA:   "/etc/audit/ca.pem",
	}
	fmt.Printf("network=%s address=%s ca=%s\n", cfg.Network, cfg.Address, cfg.TLSCA)
}

Output:
network=tcp+tls address=syslog.example.com:6514 ca=/etc/audit/ca.pem

func (Config) String

func (c Config) String() string

String returns a human-readable representation of the config with TLS key paths redacted. This prevents credential path leakage when configs are accidentally logged via %v or %+v.

type Metrics

type Metrics interface {
	// RecordSyslogReconnect records a syslog reconnection attempt.
	// success indicates whether the reconnection succeeded. The
	// address is the configured host:port. Implementations SHOULD
	// NOT use address as an unbounded metric label.
	RecordSyslogReconnect(address string, success bool)
}

Metrics is an optional interface for syslog-specific instrumentation. Pass an implementation to New to collect reconnection telemetry. Pass nil to disable.

type Output

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

Output writes serialised audit events to a syslog server over TCP, UDP, or TCP+TLS (including mTLS). Events are formatted as RFC 5424 structured syslog messages with the pre-serialised audit payload (JSON or CEF) as the message body.

Reconnection

On connection failure, Output attempts bounded exponential backoff reconnection (100ms to 30s with jitter, up to [Config.MaxRetries] attempts). Reconnection happens within [Write]: the mutex is released during the backoff sleep so [Close] can interrupt it. On reconnection, the old srslog.Writer is closed and a fresh connection is dialled — this avoids conflicting with srslog's own internal retry-on-write behaviour. The event that triggered the reconnection is retried once on the new connection. If all retries are exhausted, the event is lost and an error is returned.

UDP limitations

UDP syslog is fire-and-forget. [Write] over UDP rarely returns an error even if no server is listening. RFC 5424 recommends receivers support messages up to 2048 bytes on UDP; larger payloads may be silently truncated or dropped by the OS. Consumers with large audit events SHOULD use TCP or TCP+TLS.

TLS certificates

TLS certificate files are loaded once at construction time and are NOT hot-reloaded. If a certificate expires and is rotated on disk, the output continues using the old certificate until the process is restarted. This differs from the schema registry which supports certificate auto-reload.

Output is safe for concurrent use.

func New

func New(cfg *Config, syslogMetrics Metrics) (*Output, error)

New creates a new Output from the given config. It validates the config and establishes the initial connection. The syslogMetrics parameter is optional (may be nil).

func (*Output) Close

func (s *Output) Close() error

Close closes the syslog connection. Close is idempotent and safe for concurrent use.

func (*Output) DestinationKey

func (s *Output) DestinationKey() string

DestinationKey returns the syslog server address, enabling duplicate destination detection via audit.DestinationKeyer.

func (*Output) Name

func (s *Output) Name() string

Name returns the human-readable identifier for this output.

func (*Output) Write

func (s *Output) Write(data []byte) error

Write sends a serialised audit event to the syslog server with the default severity (LOG_INFO). For per-event severity mapping based on the audit event's severity field, the logger calls [WriteWithMetadata] instead. On connection failure, Write attempts reconnection with bounded exponential backoff. Write returns audit.ErrOutputClosed if the output has been closed.

func (*Output) WriteWithMetadata

func (s *Output) WriteWithMetadata(data []byte, meta audit.EventMetadata) error

WriteWithMetadata sends a serialised audit event to the syslog server with the syslog severity derived from the audit event's severity field. The mapping follows RFC 5424 severity semantics: audit severity 10 → LOG_CRIT, 8-9 → LOG_ERR, 6-7 → LOG_WARNING, 4-5 → LOG_NOTICE, 1-3 → LOG_INFO, 0 → LOG_DEBUG. See the package-level syslogSeverities table for the complete mapping.