net/ntpd/README.md

   1 # Configuring NTPD with UCI
   2
   3 ## Precedent
   4 Sysntpd is the lightweight implementation of the NTP protocol under
   5 Busybox.  It supports many (but not all) of the same parameters.
   6
   7 It is configured as a `config timeserver ntp` section in `/etc/config/system`,
   8 below.
   9
  10 ## Configuration
  11
  12 A sample configuration looks like:
  13
  14 **/etc/config/system**:
  15
  16 ```
  17 config timeserver ntp
  18         option enabled 1
  19         option enable_server 1
  20         list server tick.udel.edu
  21         list server tock.udel.edu
  22         list interface eth0
  23         list interface eth1
  24         list interface eth2
  25 ```
  26
  27 If you want to temporarily disable the service without deleting all of the
  28 configuration state, this is done by clearing the `enabled` parameter.  If
  29 this parameter is `1` (the default), the service is enabled.
  30
  31 The service can run as a stand-alone client (`enable_server 0`, the default)
  32 or it can also operate as a server in turn to local clients, by setting this
  33 parameter to `1`.
  34
  35 The parameter(s) `server` enumerate a list of servers to be used for
  36 reference NTP servers by the local daemon.  At least one is required,
  37 and two or more are recommended (unless you have an extremely available
  38 local server).  They should be picked to be geographically divergent,
  39 and preferrably reachable via different network carriers to protect
  40 against network partitions, etc.  They should also be high-quality
  41 time providers (i.e. having stable, accurate clock sources).
  42
  43 The `interface` parameter enumerates the list of interfaces on which
  44 the server is reachable (see `enable_server 1` above), and may be a
  45 subset of all of the interfaces present on the system.  For security
  46 reasons, you may elect to only offer the service on internal networks.
  47 If omitted, it defaults to _all_ interfaces.
  48
  49 ## Differences with `sysntpd`
  50
  51 Busybox `sysntpd` supports configuring servers based on DHCP
  52 provisioning (option 6, per the [DHCP and BOOTP
  53 Parameter](https://www.iana.org/assignments/bootp-dhcp-parameters/bootp-dhcp-parameters.xhtml)
  54 list from IANA).  This functionality is enabled (in Busybox) with the
  55 `use_dhcp` boolean parameter (default `1`), and the `dhcp_interface`
  56 list parameter, which enumerates the interfaces whose provisioning
  57 is to be utilized.
  58
  59 ### Considerations for DHCP-provisioned NTP servers
  60
  61 Most terrestrial and satellite ISPs have access to very high-quality
  62 clock sources (these are required to maintain synchronization on T3,
  63 OC3, etc trunks or earth terminals) but seldom offer access to those
  64 time sources via NTP in turn to their clients, mostly from a misplaced
  65 fear that their time source might come under attack (a slave closely
  66 tied to the master could also provide extremely high-quality time
  67 without the risk of network desynchronization should it come under
  68 sophisticated attack).
  69
  70 As a result, the NTP servers that your ISP may point you at are
  71 often of unknown/unverified quality, and you use them at your own
  72 risk.
  73
  74 Early millenial versions of Windows (2000, XP, etc) used NTP only
  75 to _initially set_ the clock to approximately 100ms accuracy (and
  76 not maintain sychronization), so the bar wasn't set very high.
  77 Since then, requirements for higher-qualty timekeeping have
  78 arisen (e.g. multi-master SQL database replication), but most ISPs
  79 have not kept up with the needs of their users.
  80
  81 Current releases of Windows use Domain Controllers for time
  82 acquisition via the [NT5DS protocol](https://blogs.msdn.microsoft.com/w32time/2007/07/07/what-is-windows-time-service/)
  83 when domain joined.
  84
  85 Because of the unreliable quality of NTP servers DHCP-provisioned by
  86 ISPs, support for this functionality was deemed unnecessary.