ntpd -- Network Time Protocol daemon

ntpd [-aAbdgLmnPqx] [-c conffile] [-D level]
[-f driftfile] [-k keyfile] [-l logfile] [-p pidfile]
[-s statsdir] [-t key] [-v variable] [-V variable] [-N high] [-r broadcastdelay]

Maintains local time-of-day synchronism with time servers.

Reads ntp.conf at startup or the command line or -c conffile or NetInfo .
Use ntpq and ntpdc to query or change options on the fly.
-q quit after the first time the clock is set (as does ntpdate).
-g and -x can be used with this option.
This will not be sufficient to synchronize the clock.
-g disable sanity once. Normally, ntpd exits if the offset exceeds the sanity limit, which is 1000 seconds by default. If the sanity limit is set to zero, no sanity checking is performed and any offset is acceptable. After that, ntpd will exit if the limit is exceeded. used with the -q option.
-x slew time in all cases (prevents reducing the time). Normally, the time is slewed if the offset is less than the step threshold, (128 ms by default) and stepped if above the threshold.
If the step threshold is set to zero, all offsets are stepped, regardless of value and regardless of the -x option. Not a good idea, as it bypasses the clock state machine which is designed to cope with large time and frequency errors. Since the slew rate is limited to 0.5 ms/s, each second of adjustment requires an interval of 2,000 seconds ( 33 minutes). An adjustment of many seconds can take hours or days . This option can be used with the -q option.
-n Don't fork.
-a Enable authentication mode (default).
-A Disable authentication mode.
-c conffile name of the configuration file. (Disable netinfo?)
-d debugging mode. multiple times, greater detail of display.
-D level debugging level directly. D 9 sample
-f driftfile name of the drift file.
-l logfile name of the log file. The default is the system log facility syslog.
-s statsdir directory path for files created by the statistics facility.
-L Listen to virtual IPs.
-b
-m
use broadcast messages.
use multicast messages on the IP multicast group address 224.0.1.1 (requires multicast kernel).
-p pidfile name to record the ntpd's process ID.
-N priority run the ntpdat a high priority.
-P Override the priority limit set by the operating system.
-r delay default propagation delay . necessary only if the delay cannot be computed automatically by the protocol.
-k keyfile file containing the NTP authentication keys.
-t key Add a key number to the trusted key list.
-v variable
-V variable
Add a system variable listed by default.
The best choice of server is to use one of the server pools where the specific server changes periodically.

> cat ntp.conf
   server pool.ntp.org

A useful command is:

sudo ntpd -q -n -g -x -D 9 |more

which quits after one update, does NOT fork, disables the sanity check permiting large adjustments and slews to the new time.

How NTP Operates

By exchanging messages with servers at poll intervals, several several minutes can elapse before the clock is set. Adjustments to the clock are made in small steps so that the timescale is virtually continuous.

Hardware incorporates a time component (maintained by a battery) which runs when the power is off. When the machine is booted, this is used to initialize the operating system time. After synchronized to a NTP server, the operating system corrects the chip . If this component is more than 17 minutes from the server time, ntpd exits with a panic message to the system log.
-g overrides this check and the clock will be set to the server time regardless of the chip time. To protect against broken hardware, such as when the battery fails or the component becomes defective, once the clock has been set, an error greater than 1000secs will cause ntpd to exit anyway.

When ntpd is first started, the error may cause the clock to be set backwards. Where this is unacceptable -x causes slew corrections to be used.
The local clock can take a long time to converge (33 minutes) for each second the clock is outside the acceptable range. attempts to quickly correct the frequency and restore operation to the normal tracking mode.

Frequency Discipline

  • When the ntpd is started and the the frequency file does not exist, ntpd enters a special mode designed to quickly adapt. This takes approximately 15 minutes, then the time and frequency are set to nominal values and the ntpd enters normal mode. After one hour the frequency file is updated.
  • When the ntpd is started and the file exists, the ntpd frequency is initialized from the file and enters normal mode immediately.
    After that the current frequency offset is written to the file at hourly intervals.

    Operating Modes

    symmetric active/passive, client/server broadcast/multicast and manycast, "Association Management" It normally operates continuously while monitoring for small changes in frequency and trimming the clock for the ultimate precision. It can operate in a one-time mode where the time is set from an external server and frequency is set from a previously recorded frequency file. A broadcast/multicast or manycast client can discover remote servers, compute server-client propagation delay correction factors and configure itself automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment. By default, ntpd runs in continuous mode where each of possibly several external servers is polled It may not be practical for ntpd to run continuously. -q is intended for this purpose. ntpd to exit just after setting the clock for the first time. ntpd is run in continuous mode with selected servers in order to measure and record the intrinsic clock frequency offset in the frequency file. It may take some hours for the frequency and offset to settle down. Then the ntpd is stopped and run in one-time mode as required. At each startup, the frequency is read from the file and initializes the kernel frequency.

    Poll Interval Control

    An intricate state machine to reduce the network load while maintaining a quality of synchronization consistent with the observed jitter and wander. There are a number of ways to tailor the operation in order enhance accuracy by reducing the interval or to reduce network overhead by increasing it. carefully consider the consequences of changing the poll adjustment range from the default minimum of 64 s to the default maximum of 1,024 seconds(33 minutes). The default minimum can be changed with the tinker minpoll command to a value not less than 16 secs. This value is used for all configured associations, unless overridden by the minpoll option on the configuration command. that most device drivers will not operate properly if the poll interval is less than 64 s and that the broadcast server and manycast client associations will also use the default, unless overridden.

    To increase the minimum interval to a few tens of minutes and maximum interval to a day, once the clock discipline loop has stabilized the interval will be increased in steps from the minimum to the maximum. This assumes the intrinsic clock frequency error is small enough for the discipline loop correct it. The capture range of the loop is 500 PPM at an interval of 64s decreasing by a factor of two for each doubling of interval. at a minimum of 1,024 s, for example, the capture range is only 31 PPM. If the intrinsic error is greater than this ntp.drift will have to be specially tailored to reduce the residual error below this limit. Once this is done, the drift file is automatically updated once per hour and is available to initialize the frequency on subsequent daemon restarts. If the system is conserving energy by spinning down the disk or sleeping when idle then the update is deferred until ntpd terminates.

    If umask for ntpd is zero, it is set to 022 so files are created with rwxr-xr-x.


    FILES /etc/ntp.conf , /etc/ntp.drift , /etc/ntp.keys

    SEE ALSO ntp.conf, ntpdate, ntpdc, ntpq(8), sntp (client)

    Local documentation is at file:///usr/share/doc/ntp/index.html
    NTP.org is a great reference and discusses choosing a time server to sync to.

    Sample output from -D 9

    some duplicated lines deleted, some lines combined on same line
    > cat ntp.conf
    server 0.us.pool.ntp.org
    
    > sudo ntpd  -q -g -x -n   -d
    ntpd 4.2.2@1.1532-o Mon Sep 24 01:42:27 UTC 2007 (1)
    
    addto_syslog: precision = 1.000 usec
    create_sockets(123)
    bind() 
    fd 20, family 2, port 123, addr 0.0.0.0, flags=9
    Added addr 0.0.0.0 to list of addresses
    addto_syslog: Listening on interface wildcard, 0.0.0.0#123 Disabled
    bind() 
    bind() fd 21, family 30, port 123, addr ::, flags=1
    Added addr :: to list of addresses
    addto_syslog: Listening on interface wildcard, ::#123 Disabled
    bind() 
    bind() fd 22, family 30, port 123, addr fe80::1, flags=21
    Added addr fe80::1 to list of addresses
    addto_syslog: Listening on interface lo0, fe80::1#123 Enabled
    bind() 
    bind() fd 23, family 2, port 123, addr 127.0.0.1, flags=21
    Added addr 127.0.0.1 to list of addresses
    addto_syslog: Listening on interface lo0, 127.0.0.1#123 Enabled
    bind() 
    bind() fd 24, family 30, port 123, addr ::1, flags=21
    Added addr ::1 to list of addresses
    addto_syslog: Listening on interface lo0, ::1#123 Enabled
    bind() 
    bind() fd 25, family 30, port 123, addr fe80::219:e3ff:fe32:f8c, flags=17
    Added addr fe80::219:e3ff:fe32:f8c to list of addresses
    addto_syslog: Listening on interface en1, fe80::219:e3ff:fe32:f8c#123 Enabled
    bind() fd 26, family 2, port 123, addr 192.168.1.8, flags=25
    Added addr 192.168.1.8 to list of addresses
    addto_syslog: Listening on interface en1, 192.168.1.8#123 Enabled
    
    init_io: maxactivefd 26
    local_clock: time 0 base 0.000000 offset 0.000000 freq 0.000 state 0
    key_expire: at 0
    peer_clear: at 0 next 1 assoc ID 14360 refid INIT
    newpeer: 192.168.1.8->67.18.176.246 mode 3 vers 4 poll 6 10 flags 0x201 0x1 ttl 0 key 00000000
    local_clock: time 0 base 0.000000 offset 0.000000 freq 0.000 state 1
    report_event: system event 'event_restart' (0x01) status 'sync_alarm, sync_unspec, 1 event, event_unspec' (0xc010)
    auth_agekeys: at 1 keys 1 expired 0
    timer: refresh ts 0
    peer 67.18.176.246 event 'event_reach' (0x84) status 'unreach, conf, 1 event, event_reach' (0x8014)
    
    transmit:at  1 192.168.1.8->67.18.176.246 mode 3
    receive:at  1 192.168.1.8<-67.18.176.246 mode 4 code 1 auth 0
    
    clock_filter: n 1 off 254.595285 del 0.068982 dsp 7.937501 jit 0.000001, age 0
    
    transmit:at  3 192.168.1.8->67.18.176.246 mode 3
    receive:at  3 192.168.1.8<-67.18.176.246 mode 4 code 1 auth 0 
    

    transmit:at 9 192.168.1.8->67.18.176.246 mode 3 receive:at 9 192.168.1.8<-67.18.176.246 mode 4 code 1 auth 0 clock_filter: n 5 off 254.595285 del 0.068982 dsp 0.437593 jit 0.000186, age 8 report_event: system event 'event_peer/strat_chg' (0x04) status 'sync_alarm, sync_ntp, 2 events, event_restart' (0xc621) addto_syslog: synchronized to 67.18.176.246, stratum 3 clock_update:at 9 assoc 1 local_clock: assocID 14360 offset 254.595285224 freq 0.000 state 1 addto_syslog: time slew +254.595285 s ntpd: time slew +254.595285s
    > sudo ntpd -g -x -n -d

    transmit:at 67 192.168.1.8->67.18.176.246 mode 3 receive:at 67 192.168.1.8<-67.18.176.246 mode 4 code 1 auth 0 clock_filter: n 2 off 253.316371 del 0.071715 dsp 3.937997 jit 2.639917, age 66 auth_agekeys:at 120 keys 1 expired 0 transmit:at 133 192.168.1.8->67.18.176.246 mode 3 receive:at 133 192.168.1.8<-67.18.176.246 mode 4 code 1 auth 0 clock_filter: n 3 off 253.316371 del 0.071715 dsp 1.938740 jit 4.176210, age 132 auth_agekeys:at 180 keys 1 expired 0 transmit:at 198 192.168.1.8->67.18.176.246 mode 3 receive:at 198 192.168.1.8<-67.18.176.246 mode 4 code 1 auth 0 clock_filter: n 4 off 253.316371 del 0.071715 dsp 0.939532 jit 5.685521, age 197 auth_agekeys:at 240 keys 1 expired 0

    auth_agekeys:at 360 keys 1 expired 0 transmit:at 394 192.168.1.8->67.18.176.246 mode 3 select: endpoint -1 245.199078 select: endpoint 0 246.020350 select: endpoint 1 246.841621 cluster: survivor 138.236.128.112 metric 2.821271 select: combine offset 246.020350 report_event: system event 'event_peer/strat_chg' (0x04) status 'sync_alarm, sync_ntp, 2 events, event_restart' (0xc621) addto_syslog: synchronized to 138.236.128.112, stratum 2 clock_update: at 9 assoc 1 local_clock: assocID 35884 offset 246.020349618 freq 0.000 state 1 addto_syslog: time slew +246.020350 s ntpd: time slew +246.020350s ntpd quietly exits
    Debug1: 9 -> 9 = 9
    ntpd 4.2.2@1.1532-o Mon Sep 24 01:42:27 UTC 2007 (1) Debug1: 9 -> 9 = 9 adding new filegen addto_syslog: set_process_priority: Leave priority alone: priority_done is <2> addto_syslog: precision = 1.000 usec create_sockets(123) address_okay: listen Virtual: 1, IF name: lo0, Up Flag: 1 address_okay: listen Virtual: 1, IF name: en1, Up Flag: 1 addto_syslog: bind() fd 20, family 2, port 123, addr 0.0.0.0, in_classd=0 flags=9 fails: Address already in use addto_syslog: bind() fd 20, family 30, port 123, scope 0, addr ::, in6_is_addr_multicast=0 flags=1 fails: Address already in use addto_syslog: bind() fd 20, family 30, port 123, scope 1, addr fe80::1, in6_is_addr_multicast=0 flags=21 fails: Address already in use addto_syslog: bind() fd 20, family 2, port 123, addr 127.0.0.1, in_classd=0 flags=21 fails: Address already in use addto_syslog: bind() fd 20, family 30, port 123, scope 0, addr ::1, in6_is_addr_multicast=0 flags=21 fails: Address already in use addto_syslog: bind() fd 20, family 30, port 123, scope 5, addr fe80::219:e3ff:fe32:f8c, in6_is_addr_multicast=0 flags=17 fails: Address already in use addto_syslog: bind() fd 20, family 2, port 123, addr 192.168.1.19, in_classd=0 flags=25 fails: Address already in use create_sockets: Total interfaces = 7
    interface 0: fd=-1, bfd=-1, name=wildcard, flags=0x9, scope=0 sin=0.0.0.0 bcast=0.0.0.0, mask=255.255.255.255 Disabled Dumping interface: 0x4e098 fd = -1 bfd = -1 sin = 0.0.0.0, 0002007b 0_0 0_0 0_0 0_0 0_0 0_0 0_0 bcast = 0.0.0.0, 0002007b 0_0 0_0 0_0 0_0 0_0 0_0 0_0 mask = 255.255.255.255, 00020000 ffffffff 0_0 0_0 0_0 0_0 0_0 0_0 name = wildcard flags = 0x00000009 last_ttl = 0 addr_refid = 0_0 num_mcast = 0 received = 0 sent = 0 notsent = 0 ifindex = 0 scopeid = 0
    interface 1: fd=-1, bfd=-1, name=wildcard, flags=0x1, scope=0 sin=:: Disabled Dumping interface: 0x4e26c fd = -1 bfd = -1 sin = ::, 001e007b 0_0 0_0 0_0 0_0 0_0 0_0 0_0 bcast = 0.0.0.0, 0_0 0_0 0_0 0_0 0_0 0_0 0_0 0_0 mask = ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff, 001e0000 0_0 ffffffff ffffffff ffffffff ffffffff 0_0 0_0 name = wildcard flags = 0x00000001 last_ttl = 0 addr_refid = 4ae71336 num_mcast = 0 received = 0 sent = 0 notsent = 0 ifindex = 0 scopeid = 0
    interface 2: fd=-1, bfd=-1, name=lo0, flags=0x15, scope=1 sin=fe80::1 Enabled Dumping interface: 0x4e440 fd = -1 bfd = -1 sin = fe80::1, 001e007b 0_0 fe800000 0_0 0_0 00000001 00000001 0_0 bcast = 0.0.0.0, 0_0 0_0 0_0 0_0 0_0 0_0 0_0 0_0 mask = ffff:ffff:ffff:ffff::, 001e007b 0_0 ffffffff ffffffff 0_0 0_0 0_0 0_0 name = lo0 flags = 0x00000015 last_ttl = 0 addr_refid = 89e5301f num_mcast = 0 received = 0 sent = 0 notsent = 0 ifindex = 0 scopeid = 1
    interface 3: fd=-1, bfd=-1, name=lo0, flags=0x15, scope=0 sin=127.0.0.1, mask=255.0.0.0 Enabled Dumping interface: 0x4e614 fd = -1 bfd = -1 sin = 127.0.0.1, 0002007b 7f000001 0_0 0_0 0_0 0_0 0_0 0_0 bcast = 0.0.0.0, 0_0 0_0 0_0 0_0 0_0 0_0 0_0 0_0 mask = 255.0.0.0, 0002007b ff000000 0_0 0_0 0_0 0_0 0_0 0_0 name = lo0 flags = 0x00000015 last_ttl = 0 addr_refid = 7f000001 num_mcast = 0 received = 0 sent = 0 notsent = 0 ifindex = 0 scopeid = 0
    interface 4: fd=-1, bfd=-1, name=lo0, flags=0x15, scope=0 sin=::1 Enabled Dumping interface: 0x4e7e8 fd = -1 bfd = -1 sin = ::1, 001e007b 0_0 0_0 0_0 0_0 00000001 0_0 0_0 bcast = 0.0.0.0, 0_0 0_0 0_0 0_0 0_0 0_0 0_0 0_0 mask = ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff, 001e007b 0_0 ffffffff ffffffff ffffffff ffffffff 0_0 0_0 name = lo0 flags = 0x00000015 last_ttl = 0 addr_refid = cf404dc8 num_mcast = 0 received = 0 sent = 0 notsent = 0 ifindex = 0 scopeid = 0
    interface 5: fd=-1, bfd=-1, name=en1, flags=0x11, scope=5 sin=fe80::219:e3ff:fe32:f8c Enabled Dumping interface: 0x4e9bc fd = -1 bfd = -1 sin = fe80::219:e3ff:fe32:f8c, 001e007b 0_0 fe800000 0_0 0219e3ff fe320f8c 00000005 0_0 bcast = 0.0.0.0, 0_0 0_0 0_0 0_0 0_0 0_0 0_0 0_0 mask = ffff:ffff:ffff:ffff::, 001e007b 0_0 ffffffff ffffffff 0_0 0_0 0_0 0_0 name = en1 flags = 0x00000011 last_ttl = 0 addr_refid = 5409b305 num_mcast = 0 received = 0 sent = 0 notsent = 0 ifindex = 0 scopeid = 5
    interface 6: fd=-1, bfd=-1, name=en1, flags=0x19, scope=0 sin=192.168.1.19 bcast=192.168.1.255, mask=255.255.255.0 Enabled Dumping interface: 0x4eb90 fd = -1 bfd = -1 sin = 192.168.1.19, 0002007b c0a80113 0_0 0_0 0_0 0_0 0_0 0_0 bcast = 192.168.1.255, 0002007b c0a801ff 0_0 0_0 0_0 0_0 0_0 0_0 mask = 255.255.255.0, 0002007b ffffff00 0_0 0_0 0_0 0_0 0_0 0_0 name = en1 flags = 0x00000019 last_ttl = 0 addr_refid = c0a80113 num_mcast = 0 received = 0 sent = 0 notsent = 0 ifindex = 0 scopeid = 0
    init_io: maxactivefd 0 local_clock: time 0 base 0.000000 offset 0.000000 freq 0.000 state 0 Debug2: 9 -> 9 = 9 getaddrinfo time.apple.com getnetnum given time.apple.com, got 17.151.16.23 newpeer: cast flags: 0x1 for address: 17.151.16.23 Finding interface for addr 17.151.16.23 in list of addresses Found interface index 6 for address 17.151.16.23 newpeer: using fd -1 and our addr 192.168.1.19 key_expire: at 0 peer_clear:at 0 next 1 assoc ID 48798 refid INIT newpeer: 192.168.1.19->17.151.16.23 mode 3 vers 4 poll 6 10 flags 0x1 0x1 ttl 0 key 0_0 authtrust: keyid 0000ffff life 1 local_clock: time 0 base 0.000000 offset 0.000000 freq 0.000 state 1 report_event: system event 'event_restart' (0x01) status 'sync_alarm, sync_unspec, 1 event, event_unspec' (0xc010) sendpkt(fd=-1 dst=17.151.16.23, src=192.168.1.19, ttl=0, len=48) addto_syslog: sendto(17.151.16.23) (fd=-1): Bad file descriptor addto_syslog: rebind_interface not triggered on errno 9 transmit:at 1 192.168.1.19->17.151.16.23 mode 3 poll_update:at 1 17.151.16.23 flags 0001 poll 6 burst 0 last 1 next 64 auth_agekeys:at 1 keys 1 expired 0 timer: refresh ts 0