WeOS
5.29.0

# Network Time Protocol – NTP

## Introduction

Time is a tricky concept. For most switching and routing operations having the correct system time is not required. However, for OpenVPN, IPsec, logging, and a few other functions time is of crucial importance.

System time is saved to, and restored from, the Real-Time Clock (RTC). At system bootstrap time is restored from RTC, which may fail if the system has experience power loss for an extended period of time. When the system shuts dow, or reboots, the RTC is updated with the current time.

Time and date can be set manually from the CLI admin-exec context using the `date` command:

    example:/#> date
    Wed Jun 19 12:52:09 UTC 2019
    example:/#> help date
    Syntax:
        date [[YYYY-MM-DD] hh:mm[:ss]]
    Usage:
        System date & time

Another option is to enable the system NTP client and set up at least one valid time server. NTP adjusts for clock drift but may sometimes have trouble setting the initial time, if current time differs too much, in which case the `date` command is useful to help push things along.

## Timezone

The time zone is the offset from Universal Coordinated Time (UTC), which is stored in the RTC. If time on your system seems off this is usually what you want to change, unless your site keeps all servers, routers, and switches on UTC.

The time zone setting is available in the system configuration context of the CLI:

    example:/#> configure
    example:/config/#> system
    example:/config/system/#>

`[no] timezone [TIMEZONE [no-dst]]`

  Set system time zone.

  Try `show timezone keyword` to list matching timezones for your region.

  E.g., `show timezone Europe`

  An optional ‘no-dst’ can be appended after timezone to specify that the timezone Dayligh Saving Time isn’t used. Note that this also affects historical timezone information.

  When setting the timezone using the ‘Etc/GMT+/-offset’ notation, please take into account that the unit is consistent with POSIX which has positive signs west of Greenwich, while many people expect positive signs east of Greenwich.

  E.g., ‘Etc/GMT+4’ corresponds to 4 hours behind UT (i.e. west of Greenwich) even though many people would expect it to mean 4 hours ahead of UT (i.e. east of Greenwich).

  `[no] no-dst`
    Disable Daylight Saving time for the timezone
  no
    Reset system time zone to its default: UTC
`list-timezones`
  List all available time zone codes

## NTP Client

When configured as an NTP client, the device synchronises with all configured NTP peers. The peers are continuously evaluated for best offset, delay and jitter.

Note

Before the client is synchronised with its peers, it first asks for a preliminary date/time, which might differ some seconds, or even minutes, from the actual current time. This time is set as the initial system time.

All subsequent responses from the peer are treated as adjustments of the clock frequency in order to edge closer to the time provided from peer.

NTP cannot change the system time when there is a bug time difference, instead it sets time only once, initially, and then simply adjusts that time. If contact with peers cannot be established, preliminary time will not be set, and system is left with either the time restored from the RTC, or that which is set according to the UNIX epoch.

When multiple peers are set up, preference can be set by using the `weight` peer option. This option has the highest priority, regardless of offset, delay and jitter that other servers migh have. Meaning, a server with poor offset, delay and jitter can still be chosen when given a higher weight. By default, all servers have a weight of 1, which means NTP chooses the best peer.

The time obtained from an NTP server is always in UTC, so the time zone must be configured in order to get correct system time.

## NTP Server

NTP server can act as a client (1) to an upstream server, with which it synchronises, or be a stand-alone server (2), distributing its own system time, regardless of how accurate it is.

In both cases NTP server will distribute the time to its downstream peers, but the accuracy may differ significantly depending on the origin of time.

Regardless of the configured time zone on NTP server, distributed time is in UTC, per RFC, therefore clients must configure timezone in order to get correct system time.

## DHCP Clients

The DHCP server can be set up to distribute NTP server(s). This is can be very useful when managing a complete subnet, in which end-devices act as both DHCP and NTP clients. The setting can be global, per subnet, or even per static lease.

It is possible to have both manually configured NTP peers, and those received from a DHCP server. Time servers which are received from DHCP server have a default weight value of 1, which is not possible to change.

## Configuration

NTP is a top-level configuration context in the CLI:

    example:/#> configure
    example:/config/#> ntp
    example:/config/ntp/#>

`[no] enable`

  Enable or disable NTP client/server. When disabled the settings are still saved to `startup-config.cfg`. To completely deactivate the service, use `no ntp` from the main configuration context.

  no
    Disable NTP client/server configuration.
`[no] peer [FQDN|IPADDR]`

  Remote NTP peer to synchronise with.

  You either can use a private or a public NTP peer, as ‘pool.ntp.org’ for example. If unset, the NTP server will try to set NTP peer from its DHCP client. This setting opens up the peer specific settings:

  `[no] enable`
    Enable or disable this peer
  `[no] preferred`
    Prefer this peer over other sources.
  `[no] poll-interval [VALUE]`

    Interval, in seconds, between updates (30-720). Default: 512.

    Note: Due to NTP protocol limitations, the poll interval is always set to the nearest lower power of two, e.g. 32, 64, 128, 256, 512 (The one exception is if the poll interval is set to 30 or 31, resulting in rounding up to 32). For example, if you set 600s, the actual interval will be 512s.

`[no] step-adjust`

  Configure step-adjust function.

  If the time difference between NTP client and server is greater than a given ‘threshold’ value, the client will step its clock, instead of slowly adjusting it (slew). This can be repeated for up to ‘limit’ number of measurements, unless ‘limit 0’ is set, which would allow to step the clock infinitely.

  This is not recommended for regular use, but can be necessary in situations where a network is isolated for long periods of time.

  By default, step-adjust is performed by NTP client during the initial contact with NTP server, if the time difference between them is larger than 10 seconds.

  `[no] threshold`
    Set the step-adjust threshold, defaults to 10.
  `[no] limit`
    Set the step-adjust limit, defaults to 1.
  `no`
    Disable step-adjust completely
`[no] server`

  Enable or disable the NTP server. When disabled only the client mode is active. This setting opens up the server specific settings:

  `[no] listen [IFACE ...]`

    Interfaces on which to allow server queries (connection from a downstream client).

    no
      Listen on all interfaces (allow queries from everywhere). This is the default behaviour.
  no
    Disable server functionality

## Status

Status of the NTP client and server can be viewed from the admin-exec context using the `show ntp` command. The alias `show sntp` also works.

`[show] ntp [verbose]`

  Show NTP client and server status.

  When NTP is running, displays the process ID, client synchronisation sources, and server configuration.

  `verbose`
    Show extended information about the synchronisation sources, including an explanation of the column headers and status indicators.

  Examples:

  - `show ntp` Show NTP client and server status
  - `show ntp verbose` Show extended NTP status with field descriptions

    example:/#> show ntp
    NTP Client/Server running as PID: 587

    CLIENT
    MS Name/IP address         Stratum Poll Reach LastRx Last sample
    ===============================================================================
    ^* ntp1.example.com              1   9   377   504   -562us[ -642us] +/-   11ms
    ^- ntp2.example.com              2  10   377   185   +890us[ +810us] +/-   45ms

    SERVER
    Enabled on: All interfaces

The CLIENT section shows the NTP peers where each line represents one configured peer. The columns are:

Column | Description
--- | ---
M | Mode of the source: `^` = server, `=` = peer
S | State: `*` = current best, `+` = combined, `-` = not combined, `x` = may be in error, `~` = too variable, `?` = unusable
Name/IP | Name or IP address of the NTP peer
Stratum | Stratum level of the source
Poll | Polling interval (as a power of 2, in seconds)
Reach | Reachability register (octal)
LastRx | Time since last sample was received (in seconds)
Last sample | Offset between local clock and source at last measurement

The SERVER section shows whether the NTP server functionality is enabled and, if so, on which interfaces it is listening for client queries.

    example:/#> show ntp verbose
    NTP Client/Server running as PID: 587

    CLIENT

      .-- Source mode  '^' = server, '=' = peer, '#' = local clock.
     / .- Source state '*' = current best, '+' = combined, '-' = not combined,
    | /             'x' = may be in error, '~' = too variable, '?' = unusable.
    ||                                                 .- xxxx [ yyyy ] +/- zzzz
    ||      Reachability register (octal) -.           |  xxxx = adjusted offset,
    ||      Log2(Polling interval) --.      |          |  yyyy = measured offset,
    ||                                \     |          |  zzzz = estimated error.
    ||                                 |    |           \
    MS Name/IP address         Stratum Poll Reach LastRx Last sample
    ===============================================================================
    ^* ntp1.example.com              1   9   377   504   -562us[ -642us] +/-   11ms
    ^- ntp2.example.com              2  10   377   185   +890us[ +810us] +/-   45ms

    SERVER
    Enabled on: All interfaces

The `verbose` option adds a legend above the sources table, explaining the meaning of each indicator and column.

### Restart and Resync

`ntp restart`

  Restart the NTP daemon and trigger a resynchronisation with all configured NTP servers. This is useful when NTP peers have been changed or when the system clock needs to be forcibly re-synchronised.

  If NTP is not configured, the command prints an informational message and takes no action.

`ntp resync`
  Alias for `ntp restart`.

    example:/#> ntp restart
    example:/#>

« Previous Next »