linux time

I find that most desktop users (and even some admins) don't have a firm grasp of linux time issues. It's true that in general time just works on linux, but there are times (no pun intended) when a knowledge of the key ideas comes in handy.

## the util-linux, libc-bin, and ntpdate packages contain the basic linux time and timezone utilities hwclock, tzselect, and ntpdate respectively; these packages are installed during system installation

! links # network time protocol aka ntp and simple ntp rfc # earlier ntp rfc; obsoleted by rfc5905 # earlier sntp rfc; obsoleted by rfc5905

! files/directories
/etc/default/rcS # UTC envvar file
/etc/adjtime # hwclock status file
/dev/rtc # links to /dev/rtc0
/dev/rtc0 # real-time clock device special file

/etc/localtime # binary timezone file copied from /usr/share/zoneinfo/
/usr/share/zoneinfo/localtime # links to /etc/localtime
/usr/share/zoneinfo/ # timezone files
/usr/share/zoneinfo/Europe/Berlin # a timezone file
/etc/timezone # text file containing timezone name e.g. Europe/Berlin


## the linux kernel marks time via the timer interrupt and maintains time as the number of seconds since 00:00:00 january 1 1970 utc aka the unix epoch; the kernel may therefore be said to maintain time in utc and linux system software generally uses the time from this software clock as-is e.g. linux file systems stamp files with this system time

! utc times are usually displayed to the user in local time aka wall clock time by applying a timezone offset based on the host timezone configuration

! coordinated universal time aka utc is the successor to greenwich mean time aka gmt as a time standard and is also informally used as a timezone reference; gmt is now only correctly used as a timezone reference and is also referred to as western european time aka wet

## the kernel initializes the software clock at boot from the host hardware clock aka real-time clock aka rtc which is battery-backed and designed to keep time even when the host power is off; on a linux host the hardware clock is typically set to utc rather than to local time; however there is nothing in the hardware clock to indicate timezone and if in fact local time is being used then some approach must be used to indicate this and to adjust the system time to utc at boot; on ubuntu the UTC envvar set in /etc/default/rcS indicates utc or local time and this envvar is used to configure a call to the hwclock utility in the /etc/init/hwclock.conf upstart job to adjust the system time if necessary

root@dev:~# cat /etc/init/hwclock.conf
    . /etc/default/rcS                                      # contains UTC=yes or UTC=no
    [ "$UTC" = "yes" ] && tz="--utc" || tz="--localtime"    # --utc or --localtime will indicate to hwclock the state of the hardware clock
    [ "$BADYEAR" = "yes" ] && badyear="--badyear"
    exec hwclock --systz $tz --noadjfile $badyear           # --systz adjusts system time if --localtime rather than --utc option is passed
end script

! if --localtime is passed then the system time adjustment to utc is based on the host timezone configuration; --systz in fact also sets the kernel timezone to this timezone

! if neither --utc nor --localtime is passed then the default is the last value used as recorded in /etc/adjtime; otherwise utc is assumed

! windows/linux dual-boot hosts usually have the hardware clock set to local time and thus UTC=no in /etc/default/rcS

! the hardware clock is accessible via /dev/rtc; to read the hardware clock run hwclock with --utc or --localtime depending on the state of the hardware clock and hwclock will display the time from the hardware clock as local time

root@dev:~# hwclock --utc
Sun 20 Jul 2013 20:46:13 CEST  -0.141192 seconds

! to display the system time run date

root@dev:~# date
Sat Nov  5 13:02:33 CET 2011      # in local time i.e. with timezone offset applied

root@dev:~# date -u
Sat Nov  5 12:02:33 UTC 2011      # in utc

root@dev:~# date -R
Sat, 05 Nov 2011 13:02:33 +0100   # rfc 2822 format

root@dev:~# date +%s
1320494553                        # in seconds since 1970-01-01 00:00:00 utc

! to set the system time run date -s

date -s "2010-12-24 13:02:00"   # any reasonable format will do

## the system timezone on ubuntu is set based on the binary timezone definition file /usr/share/zoneinfo/localtime which links to /etc/localtime; this file is a copy of one of the files in /usr/share/zoneinfo/ e.g. /usr/share/zoneinfo/Europe/Berlin and is normally put into place during installation; to safely change it the tzdata package may be reconfigured interactively:

root@dev:~# dpkg-reconfigure tzdata

; alternatively the desired timezone string e.g. Europe/Berlin may be placed in /etc/timezone and tzdata reconfigured non-interactively:

root@dev:~# dpkg-reconfigure --frontend noninteractive tzdata
Current default time zone: 'Europe/Berlin'
Local time is now:      Wed Jul 23 16:56:59 CEST 2013.
Universal Time is now:  Wed Jul 23 14:56:59 UTC 2013.

! the TZ envvar may be used to set the timezone in the current bash session

! the /usr/bin/tzselect script may be used to determine the proper timezone string for /etc/timezone and for the TZ envvar

! the timezone file format is described in

## a host's hardware clock might not keep time accurately over a long period due to natural drift and if it's incorrect then the software clock initialized from it is incorrect too; furthermore the software clock may also suffer drift over long periods between boots; the usual solution to this problem is to periodically synchronize the software clock with an accurate network time server via the network time protocol aka ntp by using the ntpdate utility or the ntpd daemon

! the network time protocol was originally defined in; ntp and simple ntp are now defined in

! prior to network access and ntp servers being commonly available the hardware clock was usually manually synchronized with hwclock --set or --systohc which would calculate and record a daily drift figure in /etc/adjtime which was then used to adjust the hardware clock with hwclock --adjust

## ntpdate is installed by default on both ubuntu desktop and server; it requires root access and sets the host clock by querying the ntp servers specified as arguments; by default it is run at boot via the /etc/network/if-up.d/ntpdate script which calls the /usr/sbin/ntpdate-debian script which calls /usr/sbin/ntpdate -s

! the ntpdate -s option causes output to go to /var/log/syslog

! the -q argument means query i.e. don't set

root@dev:~# ntpdate -q
server, stratum 2, offset 0.047243, delay 0.06445
server, stratum 2, offset 0.047046, delay 0.06628
 4 Mar 09:11:44 ntpdate[5685]: adjust time server offset 0.047243 sec

! ntpdate doesn't set the hardware clock and it doesn't enable the so-called kernel 11-minute mode like the ntpd daemon does in which the kernel sets the hardware clock from the software clock every 11 minutes; since the software clock is synchronized early in the boot process the accuracy of the hardware clock is less important but it still should be periodically synchronized with the software clock with hwclock --systohc --utc

! /usr/sbin/ntpdate-debian is a shell script that sources /etc/default/ntpdate and uses the resulting envvars in calling ntpdate; if the envvar NTPDATE_USE_NTP_CONF is set to the default value of yes then it will try to set the envvar NTPSERVERS to the server list from /etc/ntp.conf which is the conf file for ntpd from the ntp package; if the ntp package isn't installed then NTPSERVERS will retain its default value of or whatever value the user has set

! enabling automatic setting of the time from the internet in unity system settings seems to cause gnome to call ntpdate-debian -s periodically; it's unclear whether the polling interval is configurable; this approach is considered adequate for desktop

! running ntpdate via a cron job seemed to be discouraged at one point but the ntpdate man page written by the ntp rfc author recommends it in the absence of an ntp daemon and gnome with time syncing enabled is essentially doing the same thing

## the ntp package contains the ntp daemon ntpd that would typically be used on a server; it is not installed by default on ubuntu server or desktop; it sets the host clock by periodically querying the ntp servers specified in /etc/ntp.conf; it's superior to ntpdate in that it makes smaller more frequent adjustments i.e. it slews rather than steps the clock

! links

! ntpd enables the so-called kernel 11-minute mode in which the kernel sets the hardware clock from the software clock every 11 minutes; it does this by clearing i.e. setting to 0 the STA_UNSYNC bit in the kernel's phase-lock loop aka pll operating parameters; this can be checked by inspecting the value of the status field with ntptime or ntpdc; if the bit in the 64s column is 0 then 11-minute mode is enabled

root@dev:~# ntptime -r
ntp_gettime() returns code 0 (OK)
  time d77a6622.84228968  Wed, Jul 23 2014 18:49:38.516, (.516152290),
  maximum error 887107 us, estimated error 36885 us  ntptime=d77a6622.84228968 unixtime=53cfe7a2.516152290 Wed Jul 23 18:49:38 2014
, TAI offset 0
ntp_adjtime() returns code 0 (OK)
  modes 0x0 (),
  offset 30835.770 us, frequency 500.000 ppm, interval 1 s,
  maximum error 887107 us, estimated error 36885 us,
  status 0x2001 (PLL,NANO),                                    # 10000000000001b; STA_UNSYNC cleared
  time constant 6, precision 0.001 us, tolerance 500 ppm,

root@dev:~# ntpdc
ntpdc> kerninfo
pll offset:           0.0087391 s
pll frequency:        500.000 ppm
maximum error:        0.959704 s
estimated error:      0.043637 s
status:               2001  pll nano                           # 10000000000001b; STA_UNSYNC cleared
pll time constant:    6
precision:            1e-09 s
frequency tolerance:  500 ppm
ntpdc> exit

! the /etc/network/if-up.d/ntpdate script stops ntpd before running ntpdate-debian as says that ntpdate will not set the clock if ntpd is running

! to use e.g. a european ntp server pool modify /etc/ntp.conf and change the server settings which default to,, etc.


! to show status use ntpq -p

root@dev:~# ntpq -p
     remote           refid      st t when poll reach   delay   offset  jitter
 gromit.nocabal.    2 u   13   64    1   29.073  7879676   0.002
 ridcully.episod  3 u   12   64    1   42.624  7879677   0.002
 ntp.pixelkinder    2 u   11   64    1   34.376  7879683   0.002
 ns1.customer-re      2 u   10   64    1   32.055  7879686   0.002
 golem.canonical      2 u    9   64    1   35.370  7879680   0.002

! ntpd operates as a client to synchronize its host's clock and may also operate as a server for other clients; interestingly it uses udp port 123 as the source port as an ntp client which is also the port that an ntp server listens on; if it is operating as a client then packets are going out and then coming in; any firewall in use might need adjustment e.g. the iptables output chain by default lets everything out but if one is blocking input then one must append to the input chain based on protocol udp and source and destination ports 123

iptables -A INPUT -p udp --sport 123 --dport 123 -j ACCEPT   # unlike most input rules this is for the response not the request
Currently unrated





RSS / Atom