NetTime

WHAT IS THIS?

NetTime sets the AROS system clock from an NTP server, once, and ends. It
is meant for machines without a clock of their own: a Raspberry Pi running
AROS starts in 1978 at every boot.

It asks one or more servers over SNTP, checks the answer, corrects for the
time the answer spent on the network, applies your time zone with its
summer time rules, and sets the clock through timer.device. While the
network comes up it keeps trying, for as long as you allow.

This archive is the build for AROS aarch64 (the Raspberry Pi port of AROS);
the AROS i386 build is comm/net/nettime.i386-aros.lha,
the AROS x86_64 build is comm/net/nettime.x86_64-aros.lha.

REQUIREMENTS

- AROS for the Raspberry Pi (aarch64) with AROSTCP.
- A configured TCP/IP stack (AROSTCP, bsdsocket.library).

INSTALLATION

Copy NetTime to C: and add a line like this at the end of S:User-Startup,
with your own time zone in place of CET-1CEST,M3.5.0,M10.5.0/3:

    Run >NIL: C:NetTime pool.ntp.org CET-1CEST,M3.5.0,M10.5.0/3 120

Run lets the boot go on. NetTime waits for the network in the background
and leaves the clock alone if no server answers within two minutes.

USAGE

    NetTime SERVERS,ZONE,SECONDS/N,QUIET/S,SAVE/S,SELFTEST/S

SERVERS   names or IPv4 addresses with commas between them, asked in
          turn (pool.ntp.org)
ZONE      the time zone in the POSIX form; without it NetTime reads
          ENV:TZ, then the Locale preferences (which know no summer
          time), and without those it sets the clock to UTC
SECONDS   how long to keep trying while the network comes up, 0 to 3600
          (60); one round over all the servers always runs
QUIET     print nothing when all goes well
SAVE      also write the battery-backed clock, as SetClock SAVE does
SELFTEST  run the internal tests

Return codes: 0 the clock is set; 5 no server answered, the clock could
not be set, or Ctrl-C came first; 10 the arguments make no sense; 20 the
self-test failed.

WRITING THE ZONE

The POSIX form gives the name of standard time, its offset WEST of UTC (so
places east of Greenwich have a minus), and then, if there is summer time,
its name and the two days it starts and ends:

    CET-1CEST,M3.5.0,M10.5.0/3

CET-1      standard time is called CET and is one hour east of UTC
CEST       summer time, one hour ahead unless an offset follows the name
M3.5.0     it starts in March, in the last week, on Sunday, at 02:00
M10.5.0/3  it ends on the last Sunday of October at 03:00 summer time

Some zones:

    UK, Ireland, Portugal     GMT0BST,M3.5.0/1,M10.5.0
    Central Europe            CET-1CEST,M3.5.0,M10.5.0/3
    Finland, Greece, Romania  EET-2EEST,M3.5.0/3,M10.5.0/4
    US Eastern                EST5EDT,M3.2.0,M11.1.0
    US Pacific                PST8PDT,M3.2.0,M11.1.0
    India                     IST-5:30
    Japan                     JST-9
    Sydney, Melbourne         AEST-10AEDT,M10.1.0,M4.1.0/3
    New Zealand               NZST-12NZDT,M9.5.0,M4.1.0/3
    UTC                       UTC0

To give every program that reads it the same zone, set it once with
SetEnv SAVE TZ CET-1CEST,M3.5.0,M10.5.0/3 and leave ZONE out.

A name in angle brackets, such as <+03>-3, needs quotes in the Shell. Only
days in the Mm.w.d form are read. A zone with a summer time that NetTime
cannot place (EST5EDT with no days, or days in the Jn form) is refused
rather than taken as one without summer time, which would put the clock an
hour off for half of the year. Names such as Europe/Rome are not read.

KNOWN LIMITS

- NetTime runs once. The clock does not move by itself when summer time
  starts or ends, and it drifts while the machine stays on: run NetTime
  again, or reboot, to correct it.
- SNTP has no authentication: whoever can answer in place of the server
  can set your clock. NetTime only believes an answer that comes from the
  address it asked, brings back the random number of the question, and
  carries a time that hangs together and is not older than 2026.
- IPv4 only.
- AROS keeps the system clock in local time and computes UTC with the time
  zone of the Locale preferences, which knows no summer time: programs
  that print UTC may be an hour off in summer.
- Recent AROS builds carry timesyncd, a service of AROSTCP that keeps the
  clock in step all the time and takes the time zone from the Locale
  preferences. If your system has it and you need no summer time rules,
  you may not need NetTime.
- aarch64: on a Raspberry Pi without a clock chip, AROS keeps the
  battery clock in the file DEVS:battclock. SAVE rewrites that file every
  time, and the next boot starts from the saved time instead of 1978.
- aarch64: the AROS system for the Raspberry Pi has no LhA. Unpack the
  archive on another computer and copy NetTime to the SD card.

SOURCE AND LICENSE

GNU GPL v3 or later, see LICENSE. Source of this release:
  https://github.com/kaffeine1/aros-nettime/tree/v1.0
Bug reports: https://github.com/kaffeine1/aros-nettime/issues

Michele Dipace <michele.dipace()kaffeine.net>