Proposed documentation/script changes for potato (ntp/chrony/util-linux)
Hello developers,
Attached you'll find context diff files against files in the ntp, chrony and
util-linux packages, as well as a new README.Debian.hwclock file for the
util-linux package.
These changes are being proposed with the objective of dealing with the
constant user problems regarding hwclock and clock setting in Debian, and
aim for *potato*.
Better documentation and solutions should be aimed for in woody.
Please review the enclosed diff files. Unless there are problems, they will
be submitted tomorrow (01 Feb) sometime after 23:00 UTC as separate bug
reports per package, and cc: to the maintainers of each package and to
debian-devel as well.
I've been asked not to muck around with the man pages by some, and to do it
by others. The final decison to modify the man page or not belongs to the
util-linux maintainer anyway, so I'll go with a minimal changes proposal
approach:
Since the hwclock manpage does spread misinformation for a standard Debian
install, and I don't expect users to read the readme for required packages
they didn't go out of their way to install, I've added the proper readmes to
the SEE ALSO section of the man page.
I personally think a SEE ALSO entry is not enough, but we shall see. I hope
I am wrong in this.
You'll notice I was very generous at adding warnings to the hwclock init
script.
The BTS bug reports will be submitted as severity "important" (release
critical bug) for package util-linux, because this is a required package and
we aim these fix for potato. If you don't feel this should be an "important"
bug, please say so before I submit the bug report.
I do not use chrony, and I am not sure of the severity of the interaction
between chrony and the hwclock scripts. Since the chrony package does not
appear to deal with the RTC in the standard debian installation, the
documentation update just reminds the user to verify hwclock and will be
submitted as a "normal" bug.
ntp has no interaction problems with the current state of the util-linux
package init/shutdown scripts, so the documentation updates for ntp will
also be submitted as a "normal" bug.
I will ask the maintainers to update this for potato, even if the bugs are
severity normal. If you feel all bugs should be submitted as RC "important"
bugs, or that none should be submitted as RC bugs, please say so before I
submit the bug reports.
Note:
There are diffs for two versions of the hwclock.sh script included. The
first one (marked LOCALTIME) shows the time copied to the RTC during
shutdown in local time. The second one (marked UTCLOCALTIME) shows the time
copied to the RTC during shutdown in whatever timezone it is kept in the RTC
(either UTC or local).
I am not sure which one is better:
- Tell the user exactly what we're writing in his RTC. This gives the user a
change to notice their RTC is in UTC before complaining Debian is setting
his Windows clock wrong, but it risks complains from extremely cluless users
(he asked for a UTC RTC during instalation, the script SAYS the time it is
displaying is in UTC, but he still can't get it).
- Tell the user the local time version of whatever we're storing in the RTC,
which is the way it's being currently done. This is less useful as a
debuging/hint aid.
I'll go with the conservative and current (LOCALTIME) approach if nobody
speaks up for the UTC/Local time version... but I'll continue using the
UTC/local time in my system :-)
--
"One disk to rule them all, One disk to find them. One disk to bring
them all and in the darkness grind them. In the Land of Redmond
where the shadows lie." -- The Silicon Valley Tarot
Henrique Holschuh
*** /tmp/chrony-1.10/debian/README.debian Mon Jan 31 00:26:23 2000
--- debian/README.debian Sun Jan 30 22:24:12 2000
***************
*** 28,34 ****
The standard Debian installation does not use the real time clock
facilities. If you want to use them you will need to edit the config
! files and scripts.
The scripts /etc/ppp/ip-up.d/chrony, /etc/ppp/ip-down.d/chrony, and
/etc/cron.weekly/chrony read key 1 from /etc/chrony/chrony.keys and use it
--- 28,36 ----
The standard Debian installation does not use the real time clock
facilities. If you want to use them you will need to edit the config
! files and scripts. You will also need to make sure hwclock (util-linux
! package) is kept out of chrony's way (see the hwclock README files in
! the util-linux documentation for more information).
The scripts /etc/ppp/ip-up.d/chrony, /etc/ppp/ip-down.d/chrony, and
/etc/cron.weekly/chrony read key 1 from /etc/chrony/chrony.keys and use it
*** /usr/share/doc/ntp/README.Debian Thu Jan 6 03:33:39 2000
--- debian/README.Debian Sun Jan 30 22:28:38 2000
***************
*** 15,17 ****
--- 15,26 ----
provided to rotate /var/log/ntpd if present, but it will not cycle the daemon
if syslog is in use. By default, new installations of this package will use
syslog.
+
+ NTP and hwclock issues: hwclock (from the util-linux package) is normally
+ called on startup and shutdown. You must ensure that hwclock --adjust is never
+ called (make sure it is disabled in /etc/init.d/hwclock.sh) in a host which
+ has ntpd active. You should allow hwclock --systohc to be called on shutdown,
+ because the kernel does not fully update the RTC time and it could be off by
+ a multiple of 30 minutes in the next boot if hwclock --systohc is never called
+ by the shutdown sequence. See the hwclock README files in util-linux
+ documentation for more information.
hwclock and Debian:
A Debian installation will, by default, call hwclock --hctosys during system
startup and hwclock --systohc during system shutdown.
To set the date/time of the system, just use the standard UNIX date facilities
(such as date) or any of the advanced timekeeping utilities (ntp, ntpdate,
chrony). Other methods of setting the clock (such as hwclock) are likely to
cause trouble, do not use them.
Please note that because the shutdown scripts call hwclock --systohc, you
cannot set the clock using hwclock only, as your adjustment will be lost on
the next reboot. THIS MEANS YOU MUST *NOT* FOLLOW THE PROCEDURES IN THE
hwclock(8) MAN PAGE TO SET THE CLOCK DATE/TIME USING A REBOOT UNLESS YOU
EDIT THE SHUTDOWN SCRIPTS.
The full story:
A Linux system actually has two clocks:
- The System Clock, kept by the kernel. This is the clock that Linux uses for
day-to-day activities, and this is also the clock you set using date.
- The Hardware Clock, also called RTC, which is used as a backup to keep time
while the computer is turned off, or in APM suspended state. This is the
clock you set using hwclock --set.
(you can get more information about these two clocks in the hwclock(8) man
page).
hwclock is used to copy time between these two clocks. For the Debian
standard install, the system clock is initialized with the value of the
hardware clock during startup, and the value of the system clock is copied
back to the hardware clock during system shutdown/reboot.
So, in a Debian default install, you can keep the illusion that there's a
single clock. Unless you use a program that modifies the hardware clock
directly and does not set the system clock as well, that is.
Issues with hwclock --adjust:
hwclock has a facility to try to correct for systematic drift in the
hardware clock, accessed by hwclock --adjust. This facility is *dangerous*
because it has a severe drawback: it assumes that no program other than
hwclock --systohc will ever be used to change the hardware clock.
This assumption is often false, as many common utilities such as ntp,
ntpdate, chrony, as well as your computer's System Setup BIOS program, and
any other OS you have in your machine will change the clock.
Also, if hwclock --adjust is used, one must make sure the drift file
(/etc/adjtime) is deleted every time the system clock is set to a very
different value (even if you're using hwclock itself to do it!), or the
drift computation might become invalid and cause the hardware clock to be
incorrectly set the next time hwclock --adjust is used.
hwclock currently does not perform any sort of sanity checks in the values
it uses to compute the drift file, and will corrupt your clock time by
potentially very large amounts if anything goes wrong.
Don't use the hwclock --adjust facility, refer to alternate (and much safer)
programs such as ntp, chrony or adjtimex if you need precision timekeeping.
*** /tmp/util-linux-2.10d/clock/hwclock.8 Mon Jan 31 01:21:22 2000
--- clock/hwclock.8 Sun Jan 30 22:17:34 2000
***************
*** 588,594 ****
.BR gettimeofday (2),
.BR settimeofday (2),
.BR crontab (1),
! .BR tzset (3)
.SH AUTHORS
Written By Bryan Henderson, September 1996 (bryanh@giraffe-data.com),
--- 588,596 ----
.BR gettimeofday (2),
.BR settimeofday (2),
.BR crontab (1),
! .BR tzset (3),
! .BR /etc/init.d/hwclock.sh,
! .BR /usr/doc/util-linux/README.Debian.hwclock
.SH AUTHORS
Written By Bryan Henderson, September 1996 (bryanh@giraffe-data.com),
*** /tmp/util-linux-2.10d/debian/hwclock.sh Mon Jan 31 01:22:55 2000
--- debian/hwclock.sh Mon Jan 31 01:36:04 2000
***************
*** 4,9 ****
--- 4,20 ----
#
# Version: @(#)hwclock.sh 2.00 14-Dec-1998 miquels@cistron.nl
#
+ # Patches:
+ # 2000-01-30 Henrique M. Holschuh <hmh@rcm.org.br>
+ # - Minor cosmetic changes in an attempt to help new
+ # users notice something IS changing their clocks
+ # during startup/shutdown.
+ # - Added comments to alert users of hwclock issues
+ # and discourage tampering without proper doc reading.
+
+ # WARNING: Please read /usr/doc/util-linux/README.Debian.hwclock
+ # before changing this file. You risk serious clock
+ # misbehaviour otherwise.
. /etc/default/rcS
[ "$GMT" = "-u" ] && UTC="yes"
***************
*** 20,26 ****
--- 31,67 ----
then
echo "0.0 0 0.0" > /etc/adjtime
fi
+
+ # Uncomment the hwclock --adjust line below if you want
+ # hwclock to try to correct systematic drift errors in the
+ # Hardware Clock.
+ #
+ # WARNING: If you uncomment this option, you must either make
+ # sure *nothing* changes the Hardware Clock other than
+ # hwclock --systohc, or you must delete /etc/adjtime
+ # every time someone else modifies the Hardware Clock.
+ #
+ # Common "vilains" are: ntp, MS Windows, the BIOS Setup
+ # program.
+ #
+ # WARNING: You must remember to invalidate (delete)
+ # /etc/adjtime if you ever need to set the system clock
+ # to a very different value and hwclock --adjust is being
+ # used.
+ #
+ # Please read /usr/doc/util-linux/README.Debian.hwclock
+ # before enablig hwclock --adjust.
+ #
# hwclock --adjust $GMT
+
+ if [ "$VERBOSE" != no ]
+ then
+ echo
+ echo "Setting the System Clock using the Hardware Clock as reference..."
+ fi
+ # Copies Hardware Clock time to System Clock using the correct
+ # timezone for hardware clocks in local time, and sets kernel
+ # timezone. DO NOT REMOVE.
hwclock --hctosys $GMT
#
# Now that /usr/lib/zoneinfo should be available,
***************
*** 28,44 ****
#
if [ "$VERBOSE" != no ]
then
! echo
! echo "Local time: `date`"
echo
fi
;;
stop|restart|reload)
[ "$GMT" = "-u" ] && GMT="--utc"
hwclock --systohc $GMT
if [ "$VERBOSE" != no ]
then
! echo "CMOS clock updated to `date`."
fi
;;
show)
--- 69,95 ----
#
if [ "$VERBOSE" != no ]
then
! echo "System Clock set. Local time: `date`"
echo
fi
;;
stop|restart|reload)
+ #
+ # Updates the Hardware Clock with the System Clock time.
+ # This will *override* any changes made to the Hardware Clock.
+ #
+ # WARNING: If you disable this, any changes to the system
+ # clock will not be carried across reboots.
+ #
+ if [ "$VERBOSE" != no ]
+ then
+ echo "Saving the System Clock time to the Hardware Clock..."
+ fi
[ "$GMT" = "-u" ] && GMT="--utc"
hwclock --systohc $GMT
if [ "$VERBOSE" != no ]
then
! echo "Hardware Clock updated to `date`."
fi
;;
show)
***************
*** 46,53 ****
;;
*)
echo "Usage: hwclock.sh {start|stop|reload|show}" >&2
! echo " start sets kernel clock from CMOS clock" >&2
! echo " stop and reload set CMOS clock from kernel clock" >&2
exit 1
;;
esac
--- 97,104 ----
;;
*)
echo "Usage: hwclock.sh {start|stop|reload|show}" >&2
! echo " start sets kernel (system) clock from hardware (RTC) clock" >&2
! echo " stop and reload set hardware (RTC) clock from kernel (system) clock" >&2
exit 1
;;
esac
*** /tmp/util-linux-2.10d/debian/hwclock.sh Mon Jan 31 01:22:55 2000
--- debian/hwclock.sh Mon Jan 31 01:36:20 2000
***************
*** 4,9 ****
--- 4,22 ----
#
# Version: @(#)hwclock.sh 2.00 14-Dec-1998 miquels@cistron.nl
#
+ # Patches:
+ # 2000-01-30 Henrique M. Holschuh <hmh@rcm.org.br>
+ # - Minor cosmetic changes in an attempt to help new
+ # users notice something IS changing their clocks
+ # during startup/shutdown.
+ # - Added comments to alert users of hwclock issues
+ # and discourage tampering without proper doc reading.
+ # - Try to show the real time (local or UTC) set to
+ # the RTC on shutdown.
+
+ # WARNING: Please read /usr/doc/util-linux/README.Debian.hwclock
+ # before changing this file. You risk serious clock
+ # misbehaviour otherwise.
. /etc/default/rcS
[ "$GMT" = "-u" ] && UTC="yes"
***************
*** 20,26 ****
--- 33,69 ----
then
echo "0.0 0 0.0" > /etc/adjtime
fi
+
+ # Uncomment the hwclock --adjust line below if you want
+ # hwclock to try to correct systematic drift errors in the
+ # Hardware Clock.
+ #
+ # WARNING: If you uncomment this option, you must either make
+ # sure *nothing* changes the Hardware Clock other than
+ # hwclock --systohc, or you must delete /etc/adjtime
+ # every time someone else modifies the Hardware Clock.
+ #
+ # Common "vilains" are: ntp, MS Windows, the BIOS Setup
+ # program.
+ #
+ # WARNING: You must remember to invalidate (delete)
+ # /etc/adjtime if you ever need to set the system clock
+ # to a very different value and hwclock --adjust is being
+ # used.
+ #
+ # Please read /usr/doc/util-linux/README.Debian.hwclock
+ # before enablig hwclock --adjust.
+ #
# hwclock --adjust $GMT
+
+ if [ "$VERBOSE" != no ]
+ then
+ echo
+ echo "Setting the System Clock using the Hardware Clock as reference..."
+ fi
+ # Copies Hardware Clock time to System Clock using the correct
+ # timezone for hardware clocks in local time, and sets kernel
+ # timezone. DO NOT REMOVE.
hwclock --hctosys $GMT
#
# Now that /usr/lib/zoneinfo should be available,
***************
*** 28,44 ****
#
if [ "$VERBOSE" != no ]
then
! echo
! echo "Local time: `date`"
echo
fi
;;
stop|restart|reload)
[ "$GMT" = "-u" ] && GMT="--utc"
hwclock --systohc $GMT
if [ "$VERBOSE" != no ]
then
! echo "CMOS clock updated to `date`."
fi
;;
show)
--- 71,97 ----
#
if [ "$VERBOSE" != no ]
then
! echo "System Clock set. Local time: `date`"
echo
fi
;;
stop|restart|reload)
+ #
+ # Updates the Hardware Clock with the System Clock time.
+ # This will *override* any changes made to the Hardware Clock.
+ #
+ # WARNING: If you disable this, any changes to the system
+ # clock will not be carried across reboots.
+ #
+ if [ "$VERBOSE" != no ]
+ then
+ echo "Saving the System Clock time to the Hardware Clock..."
+ fi
[ "$GMT" = "-u" ] && GMT="--utc"
hwclock --systohc $GMT
if [ "$VERBOSE" != no ]
then
! echo "Hardware Clock updated to `date $GMT`."
fi
;;
show)
***************
*** 46,53 ****
;;
*)
echo "Usage: hwclock.sh {start|stop|reload|show}" >&2
! echo " start sets kernel clock from CMOS clock" >&2
! echo " stop and reload set CMOS clock from kernel clock" >&2
exit 1
;;
esac
--- 99,106 ----
;;
*)
echo "Usage: hwclock.sh {start|stop|reload|show}" >&2
! echo " start sets kernel (system) clock from hardware (RTC) clock" >&2
! echo " stop and reload set hardware (RTC) clock from kernel (system) clock" >&2
exit 1
;;
esac
Reply to: