ntp

README

ntp

The ntp package is an implementation of a Simple NTP (SNTP) client based on RFC5905. It allows you to connect to a remote NTP server and request information about the current time.

Querying the current time

If all you care about is the current time according to a remote NTP server, simply use the Time function:

time, err := ntp.Time("0.beevik-ntp.pool.ntp.org")

Querying time metadata

To obtain the current time as well as some additional metadata about the time, use the Query function:

response, err := ntp.Query("0.beevik-ntp.pool.ntp.org")
time := time.Now().Add(response.ClockOffset)

Alternatively, use the QueryWithOptions function if you want to change the default behavior used by the Query function:

options := ntp.QueryOptions{ Timeout: 30*time.Second, TTL: 5 }
response, err := ntp.QueryWithOptions("0.beevik-ntp.pool.ntp.org", options)
time := time.Now().Add(response.ClockOffset)

The Response structure returned by Query includes the following information:

• Time: The time the server transmitted its response, according to its own clock.
• ClockOffset: The estimated offset of the local system clock relative to the server's clock. For a more accurate time reading, you may add this offset to any subsequent system clock reading.
• RTT: An estimate of the round-trip-time delay between the client and the server.
• Precision: The precision of the server's clock reading.
• Stratum: The server's stratum, which indicates the number of hops from the server to the reference clock. A stratum 1 server is directly attached to the reference clock. If the stratum is zero, the server has responded with the "kiss of death".
• ReferenceID: A unique identifier for the consulted reference clock.
• ReferenceTime: The time at which the server last updated its local clock setting.
• RootDelay: The server's aggregate round-trip-time delay to the stratum 1 server.
• RootDispersion: The server's estimated maximum measurement error relative to the reference clock.
• RootDistance: An estimate of the root synchronization distance between the client and the stratum 1 server.
• Leap: The leap second indicator, indicating whether a second should be added to or removed from the current month's last minute.
• MinError: A lower bound on the clock error between the client and the server.
• KissCode: A 4-character string describing the reason for a "kiss of death" response (stratum=0).
• Poll: The maximum polling interval between successive messages to the server.

The Response structure's Validate method performs additional sanity checks to determine whether the response is suitable for time synchronization purposes.

err := response.Validate()
if err == nil {
    // response data is suitable for synchronization purposes
}

Using the NTP pool

The NTP pool is a shared resource used by people all over the world. To prevent it from becoming overloaded, please avoid querying the standard pool.ntp.org zone names in your applications. Instead, consider requesting your own vendor zone or joining the pool.

Documentation

Overview

Package ntp provides an implementation of a Simple NTP (SNTP) client capable of querying the current time from a remote NTP server. See RFC5905 (https://tools.ietf.org/html/rfc5905) for more details.

This approach grew out of a go-nuts post by Michael Hofmann: https://groups.google.com/forum/?fromgroups#!topic/golang-nuts/FlcdMU5fkLQ

Index

• Constants
• func ClockOffsetChan(ctx context.Context, interval time.Duration, hosts ...string) chan time.Duration
• func TimeChan(ctx context.Context, interval time.Duration, hosts ...string) chan time.Time
• type HostResponse
  • func HostPreferred(hosts []string) *HostResponse
• type LeapIndicator
• type QueryOptions
• type Response
  • func GetResponse(host string) *Response
  • func Query(host string) (*Response, error)
  • func QueryWithOptions(host string, opt QueryOptions) (*Response, error)
  • func (r *Response) Validate() error

Constants

const (
	// LeapNoWarning indicates no impending leap second.
	LeapNoWarning LeapIndicator = 0

	// LeapAddSecond indicates the last minute of the day has 61 seconds.
	LeapAddSecond = 1

	// LeapDelSecond indicates the last minute of the day has 59 seconds.
	LeapDelSecond = 2

	// LeapNotInSync indicates an unsynchronized leap second.
	LeapNotInSync = 3
)

Functions

func ClockOffsetChan

func ClockOffsetChan(ctx context.Context, interval time.Duration, hosts ...string) chan time.Duration

ClockOffsetChan 启动 Simple NTP (SNTP), 周期性获取时钟偏移值

func TimeChan

func TimeChan(ctx context.Context, interval time.Duration, hosts ...string) chan time.Time

TimeChan 启动 Simple NTP (SNTP), 周期性获取最新时间

Types

type HostResponse

type HostResponse struct {
	Host string
	Resp *Response
}

func HostPreferred

func HostPreferred(hosts []string) *HostResponse

HostPreferred 选择最快的 NTP Host

type LeapIndicator

type LeapIndicator uint8

The LeapIndicator is used to warn if a leap second should be inserted or deleted in the last minute of the current month.

type QueryOptions

type QueryOptions struct {
	Timeout      time.Duration // defaults to 5 seconds
	Version      int           // NTP protocol version, defaults to 4
	LocalAddress string        // IP address to use for the client address
	Port         int           // Server port, defaults to 123
	TTL          int           // IP TTL to use, defaults to system default
}

QueryOptions contains the list of configurable options that may be used with the QueryWithOptions function.

type Response

type Response struct {
	// Time is the transmit time reported by the server just before it
	// responded to the client's NTP query.
	Time time.Time

	// ClockOffset is the estimated offset of the client clock relative to
	// the server. Add this to the client's system clock time to obtain a
	// more accurate time.
	ClockOffset time.Duration

	// RTT is the measured round-trip-time delay estimate between the client
	// and the server.
	RTT time.Duration

	// Precision is the reported precision of the server's clock.
	Precision time.Duration

	// Stratum is the "stratum level" of the server. The smaller the number,
	// the closer the server is to the reference clock. Stratum 1 servers are
	// attached directly to the reference clock. A stratum value of 0
	// indicates the "kiss of death," which typically occurs when the client
	// issues too many requests to the server in a short period of time.
	Stratum uint8

	// ReferenceID is a 32-bit identifier identifying the server or
	// reference clock.
	ReferenceID uint32

	// ReferenceTime is the time when the server's system clock was last
	// set or corrected.
	ReferenceTime time.Time

	// RootDelay is the server's estimated aggregate round-trip-time delay to
	// the stratum 1 server.
	RootDelay time.Duration

	// RootDispersion is the server's estimated maximum measurement error
	// relative to the stratum 1 server.
	RootDispersion time.Duration

	// RootDistance is an estimate of the total synchronization distance
	// between the client and the stratum 1 server.
	RootDistance time.Duration

	// Leap indicates whether a leap second should be added or removed from
	// the current month's last minute.
	Leap LeapIndicator

	// MinError is a lower bound on the error between the client and server
	// clocks. When the client and server are not synchronized to the same
	// clock, the reported timestamps may appear to violate the principle of
	// causality. In other words, the NTP server's response may indicate
	// that a message was received before it was sent. In such cases, the
	// minimum error may be useful.
	MinError time.Duration

	// KissCode is a 4-character string describing the reason for a
	// "kiss of death" response (stratum = 0). For a list of standard kiss
	// codes, see https://tools.ietf.org/html/rfc5905#section-7.4.
	KissCode string

	// Poll is the maximum interval between successive NTP polling messages.
	// It is not relevant for simple NTP clients like this one.
	Poll time.Duration
}

A Response contains time data, some of which is returned by the NTP server and some of which is calculated by the client.

func GetResponse

func GetResponse(host string) *Response

GetResponse 获取 NTP 响应, 无效值返回 nil

func Query

func Query(host string) (*Response, error)

Query returns a response from the remote NTP server Host. It contains the time at which the server transmitted the response as well as other useful information about the time and the remote server.

func QueryWithOptions

func QueryWithOptions(host string, opt QueryOptions) (*Response, error)

QueryWithOptions performs the same function as Query but allows for the customization of several query options.

func (*Response) Validate

func (r *Response) Validate() error

Validate checks if the response is valid for the purposes of time synchronization.