ntp

package
v1.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 3, 2026 License: MPL-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package ntp provides a time sync client via SNTP protocol.

Index

Constants

View Source
const (
	// MinAllowablePoll is the minimum time allowed for a client to query a time server.
	MinAllowablePoll = 32 * time.Second
	// MaxAllowablePoll is the maximum allowed interval for querying a time server.
	MaxAllowablePoll = 2048 * time.Second
	// RetryPoll is the interval between retries if the error is not Kiss-o-Death.
	RetryPoll = time.Second
	// AdjustTimeLimit is a maximum time drift to compensate via adjtimex().
	//
	// Deltas smaller than AdjustTimeLimit are gradually adjusted (slewed) to approach the network time.
	// Deltas larger than AdjustTimeLimit are set by letting the system time jump.
	AdjustTimeLimit = 400 * time.Millisecond
	// EpochLimit is a minimum time difference to signal that change as epoch change.
	EpochLimit = 15 * time.Minute
	// ExpectedAccuracy is the expected time sync accuracy, used to adjust poll interval.
	ExpectedAccuracy = 200 * time.Millisecond
	// NTSBootstrapAttempts is the number of initial NTS session establishment attempts
	// during which a TLS certificate validity-period (time) failure is tolerated by
	// falling back to a verifier which validates the chain and hostname but ignores
	// the certificate notBefore/notAfter.
	//
	// This works around the boot-time chicken-and-egg problem: NTS key exchange runs
	// over TLS, but the system clock used to validate the certificate may not be set
	// yet. After this many attempts (or once time has been synced), certificate
	// validation is always strict.
	NTSBootstrapAttempts = 5
)

Variables

This section is empty.

Functions

func IsPTPDevice added in v1.9.1

func IsPTPDevice(server string) bool

IsPTPDevice checks if a given server string represents a PTP device.

func QueryPTPDevice added in v1.9.1

func QueryPTPDevice(device string) (unix.Timespec, error)

QueryPTPDevice queries PTP device for current time.

Types

type AdjustTimeFunc

type AdjustTimeFunc func(buf *unix.Timex) (state timex.State, err error)

AdjustTimeFunc provides a function to adjust time.

type CurrentTimeFunc

type CurrentTimeFunc func() time.Time

CurrentTimeFunc provides a function which returns current time.

type Measurement added in v1.7.0

type Measurement struct {
	ClockOffset time.Duration
	Leap        ntp.LeapIndicator
	Spike       bool
}

Measurement is a struct containing correction data based on a time request.

type NTSNewSessionFunc added in v1.14.0

type NTSNewSessionFunc func(address string, skipCertTimeCheck bool) (NTSSession, error)

NTSNewSessionFunc creates an NTS session for a given server address. Defaults to nts.NewSession wrapper; injectable for testing.

When skipCertTimeCheck is true, the implementation should validate the TLS certificate chain and hostname but ignore the certificate validity period. This is used to bootstrap NTS before the system clock has been set.

type NTSSession added in v1.14.0

type NTSSession interface {
	Query() (*ntp.Response, error)
}

NTSSession abstracts the beevik/nts Session for testability.

func DefaultNTSNewSession added in v1.14.0

func DefaultNTSNewSession(address string, skipCertTimeCheck bool) (NTSSession, error)

DefaultNTSNewSession creates a real NTS session using beevik/nts. This is the default NTSNewSessionFunc used in production.

When skipCertTimeCheck is true, the TLS certificate chain and hostname are still fully validated, but the certificate validity period (notBefore / notAfter) is ignored. This is used to bootstrap NTS when the system clock is not yet set (e.g. at boot without an RTC), where an otherwise valid server certificate would be rejected as "expired or not yet valid".

type QueryFunc

type QueryFunc func(server string) (*ntp.Response, error)

QueryFunc provides a function which performs NTP query.

type SetTimeFunc

type SetTimeFunc func(tv *syscall.Timeval) error

SetTimeFunc provides a function to set system time.

type SpikeStatus added in v1.14.0

type SpikeStatus struct {
	// Detected is true if the last measurement was discarded as a spike.
	Detected bool
	// Consecutive is the number of measurements discarded in a row.
	Consecutive int
}

SpikeStatus describes the state of the spike filter.

A measurement discarded as a spike is not applied to the clock at all, so a filter which keeps rejecting is indistinguishable from a clock which is simply never corrected unless the rejections themselves are reported.

type Syncer

type Syncer struct {
	MinPoll, MaxPoll, RetryPoll time.Duration

	// these functions are overridden in tests for mocking support
	CurrentTime CurrentTimeFunc
	NTPQuery    QueryFunc
	AdjustTime  AdjustTimeFunc
	DisableRTC  bool

	// NTS (Network Time Security) support
	UseNTS        bool
	NTSNewSession NTSNewSessionFunc

	// NTSBootstrapAttempts is the number of initial NTS session establishment
	// attempts during which a TLS certificate validity-period failure is tolerated
	// by retrying with a verifier that ignores certificate time constraints.
	NTSBootstrapAttempts int
	// contains filtered or unexported fields
}

Syncer performs time sync via NTP on schedule.

func NewSyncer

func NewSyncer(logger *zap.Logger, timeServers []string, useNTS bool) *Syncer

NewSyncer creates new Syncer with default configuration.

func (*Syncer) EpochChange

func (syncer *Syncer) EpochChange() <-chan struct{}

EpochChange returns a channel which receives a value each time jumps more than EpochLimit.

func (*Syncer) Run

func (syncer *Syncer) Run(ctx context.Context)

Run runs the sync process.

Run is usually run in a goroutine. When context is canceled, sync process aborts.

func (*Syncer) SetTimeServers

func (syncer *Syncer) SetTimeServers(timeServers []string)

SetTimeServers sets the list of time servers to use.

func (*Syncer) SpikeStatus added in v1.14.0

func (syncer *Syncer) SpikeStatus() SpikeStatus

SpikeStatus returns the current state of the spike filter.

func (*Syncer) SpikeStatusChange added in v1.14.0

func (syncer *Syncer) SpikeStatusChange() <-chan struct{}

SpikeStatusChange returns a channel which receives a value each time the state of the spike filter changes.

func (*Syncer) Synced

func (syncer *Syncer) Synced() <-chan struct{}

Synced returns a channel which is closed when time is in sync.

Directories

Path Synopsis
internal
spike
Package spike provides a spike detector for NTP responses.
Package spike provides a spike detector for NTP responses.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL