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
https://help.ubuntu.com/community/UbuntuTime
http://manpages.ubuntu.com/hwclock
http://manpages.ubuntu.com/tzselect
http://manpages.ubuntu.com/ntpdate
https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
http://tools.ietf.org/html/rfc5905 # network time protocol aka ntp and simple ntp rfc
http://tools.ietf.org/html/rfc1305 # earlier ntp rfc; obsoleted by rfc5905
http://tools.ietf.org/html/rfc4330 # earlier sntp rfc; obsoleted by rfc5905
! files/directories
/sbin/hwclock
/etc/init/hwclock.conf
/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
/usr/sbin/ntpdate
/usr/sbin/ntpdate-debian
/etc/network/if-up.d/ntpdate
## 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
...
script
. /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 http://manpages.ubuntu.com/tzfile
## 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 http://tools.ietf.org/html/rfc1305; ntp and simple ntp are now defined in http://tools.ietf.org/html/rfc5905
! 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 ntp.ubuntu.com
server 91.189.94.4, stratum 2, offset 0.047243, delay 0.06445
server 91.189.89.199, stratum 2, offset 0.047046, delay 0.06628
4 Mar 09:11:44 ntpdate[5685]: adjust time server 91.189.94.4 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 ntp.ubuntu.com 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
http://www.pool.ntp.org
https://help.ubuntu.com/12.04/serverguide/NTP.html
http://articles.slicehost.com/2010/11/8/using-ntp-to-sync-time-on-ubuntu
http://manpages.ubuntu.com/ntpd
! 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 http://manpages.ubuntu.com/ntpdate 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 0.ubuntu.pool.ntp.org, 1.ubuntu.pool.ntp.org, etc.
server 0.europe.pool.ntp.org
server 1.europe.pool.ntp.org
server 2.europe.pool.ntp.org
server 3.europe.pool.ntp.org
! to show status use ntpq -p
root@dev:~# ntpq -p
remote refid st t when poll reach delay offset jitter
==============================================================================
gromit.nocabal. 130.149.17.21 2 u 13 64 1 29.073 7879676 0.002
ridcully.episod 235.106.237.243 3 u 12 64 1 42.624 7879677 0.002
ntp.pixelkinder 131.188.3.220 2 u 11 64 1 34.376 7879683 0.002
ns1.customer-re 40.33.41.76 2 u 10 64 1 32.055 7879686 0.002
golem.canonical 192.93.2.20 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