From 41266cbaa09a7beae101c671bc97b52ee8c3673b Mon Sep 17 00:00:00 2001 From: Miroslav Lichvar Date: Fri, 27 Jun 2014 16:05:43 +0200 Subject: [PATCH] make_release: generate FAQ from chrony.txt --- faq.txt | 268 --------------------------------------------------- faqgen.pl | 140 --------------------------- make_release | 10 ++ 3 files changed, 10 insertions(+), 408 deletions(-) delete mode 100644 faq.txt delete mode 100644 faqgen.pl diff --git a/faq.txt b/faq.txt deleted file mode 100644 index 030a4f8..0000000 --- a/faq.txt +++ /dev/null @@ -1,268 +0,0 @@ -@@PROLOGUE - - -Frequently asked questions - - - - - - - - -

-This is a set of questions and answers to common problems and issues. -

-As we receive more emails about the software, we will add new questions -to this page. -

-

-The developers can be reached via the chrony-dev mailing list. See -question 1.4. for details. -

- -
-@@ENDPROLOGUE -S: Administrative issues - -Q: Where can I get chrony source code? -Tarballs are available via the Download link on the Chrony -Web site. For the current development from the developers' version control -system see the Git link on the Web site. - -Q: Are there any packaged versions of chrony? -We are aware of packages for Debian, Fedora, Gentoo, Mandriva, Slackware, -and Ubuntu. We are not involved with how these are built or distributed. - -Q: Where is the home page? -It is currently at http://chrony.tuxfamily.org/. - -Q: Is there a mailing list? -Yes, it's currently at chrony-users@chrony.tuxfamily.org. There is a low-volume -list called chrony-announce which is just for announcements of new releases or -similar matters of high importance. You can join the lists by sending a -message with the subject subscribe to chrony-users-request@chrony.tuxfamily.org or -chrony-announce-request@chrony.tuxfamily.org respectively. - -For those who want to contribute to the development of chrony, there is a -developers' mailing list. You can subscribe by sending mail with the -subject subscribe to -chrony-dev-request@chrony.tuxfamily.org. - -Q: What licence is applied to chrony? -Starting from version 1.15, chrony is licensed under the GNU General Public -License, Version 2. Versions prior to 1.15 were licensed under a custom BSD-like -license. - -S: Chrony compared to other programs -Q: How does chrony compare to xntpd? -If your computer is permenently connected, or connected for long periods (that -is, for the several hours it takes xntpd to settle down), or you need to -support hardware reference clocks to your computer, then xntpd will work fine. -Apart from not supporting hardware clocks, chrony will work fine too. - -If your computer connects to the 'net for 5 minutes once a day (or something -like that), or you turn your Linux computer off when you're not using -it, or you want to use NTP on an isolated network with no hardware clocks in -sight, chrony will work much better for you. - -The reason I wrote chrony was that I could not get xntpd to do -anything sensible on my PC at home, which is connected to the 'net for -about 5 minutes once or twice a day, mainly to upload/download email -and news. Nowadays it is also turned off for 22-23 hours a day, when -not in use. I wanted a program which would : - -- slew the time to correct it when I go online and NTP servers become visible - -- determine the rate at which the computer gains or loses time and use this - information to keep it reasonably correct between connects to the 'net. This - has to be done using a method that does not care about the intermittent - availability of the references or the fact the computer is turned off between - groups of measurements.. - -- maintain the time across reboots, by working out the error and drift rate of - the computer's real-time clock and using this information to set the system - clock correctly at boot up. (In the last few months, it became impossible for - me to leave my computer powered permanently.) - -Also, when working with isolated networks with no true time references -at all, I found xntpd gave me no help with managing the local clock's -gain/loss rate on the NTP master node (which I set from my watch). I -added some automated support in chrony to deal with this. - -S: Selection of NTP servers -Q: I have several computers on a LAN. Should I make one the master, or make them all clients of an external server? -I think the best configuration is to make one computer the master, with the -others as clients of it. Add a 'local' directive to the master's chrony.conf -file. This configuration will be better because - -* the load on the external connection is less -* the load on the external NTP server(s) is less -* if your external connection goes down, the computers on the LAN will maintain - a common time with each other. - -S: My computer is not synchronising. -This is the most common problem. There are a number of reasons, see the -following questions. - -Q: Behind a firewall? -If there is a firewall between you and the NTP server you're trying to use, -the packets may be blocked. Try using a tool like etherfind or tcpdump to see -if you're getting responses from the server. If you have an external modem, -see if the receive light blinks straight after the transmit light (when the -link is quiet apart from the NTP traffic.) Try adding 'log measurements' to -the chrony.conf file and look in the measurements.log file after chrony has -been running for a short period. See if any measurements appear. - -Most people run chronyd on the firewall itself, to avoid all issues of UDP -packet forwarding and/or masquerading. - -Q: Do you have a non-permanant (i.e. intermittent) Internet connection? -Check that you're using chronyc's 'online' and 'offline' commands -appropriately. Again, check in measurements.log to see if you're getting any -data back from the server. - -Q: In measurements.log, do the '7' and '8' flag columns always show zero? -Do you have a 'local stratum X' directive in the chrony.conf file? If X is -lower than the stratum of the server you're trying to use, this situation will -arise. You should always make X quite high (e.g. 10) in this directive. - -S: Issues with chronyc - -Q: I keep getting the error '506 Cannot talk to daemon'. -Make sure that the chrony.conf file (on the computer where chronyd is running) -has a 'cmdallow' entry for the computer you are running chronyc on. This -isn't necessary for localhost. - -Perhaps chronyd is not running. Try using the ps command (e.g. on Linux, 'ps --auxw') to see if it's running. Or try 'netstat -a' and see if the ports -123/udp and 323/udp are listening. If chronyd is not running, you may have a -problem with the way you are trying to start it (e.g. at boot time). - -Perhaps you have a firewall set up in a way that blocks packets on port -323/udp. You need to amend the firewall configuration in this case. - -Q: Is the chronyc<->chronyd protocol documented anywhere? -Only by the source code :-) See cmdmon.c (chronyd side) and client.c (chronyc -side). - -S: Real-time clock issues. -Q: What is the real-time clock (RTC)? -This is the clock which keeps the time even when your computer is turned off. -It works with 1 second resolution. chronyd can monitor the rate at which the -real-time clock gains or loses time, and compensate for it when you set the -system time from it at the next reboot. See the documentation for details. - -Q: I want to use chronyd's real-time clock support. Must I disable hwclock? -The hwclock program is often set-up by default in the boot and shutdown scripts -with many Linux installations. If you want to use chronyd's real-time clock -support, the important thing is to disable hwclock in the shutdown -procedure. If you don't, it will over-write the RTC with a new value, unknown -to chronyd. At the next reboot, chronyd will compensate this (wrong) time with -its estimate of how far the RTC has drifted whilst the power was off, giving a -meaningless initial system time. - -There is no need to remove hwclock from the boot process, as long as chronyd is -started after it has run. - -Q: I just keep getting the '513 RTC driver not running' message -For the real time clock support to work, you need the following three things: - -* a kernel that is supported (e.g. 2.2 onwards) -* enhanced RTC support compiled into the kernel -* an 'rtcfile' directive in your chrony.conf file. - -S: Microsoft Windows - -Q: Does chrony support Windows? -No. The chronyc program (the command-line client used for configuring -chronyd while it is running) has been successfully built and run under Cygwin -in the past. chronyd is not portable, because part of it is very -system-dependent. It needs adapting to work with Windows' equivalent of the -adjtimex() call, and it needs to be made to work as an NT service. - -Q: Are there any plans to support Windows? -We have no plans to do this. Anyone is welcome to pick this work up and -contribute it back to the project. - -Q: What alternative NTP clients are there for Windows? -Some of the names we've seen mentioned are - - Automachron - - NetTime (nettime.sourceforge.net) - -S: NTP-specific issues -Q: Can chrony be driven from broadcast NTP servers? -No. I remember looking at how they worked when I was first writing chrony. -Since the 'target market' then was dial-up systems, broadcast packets were not -relevant so I didn't bother working out how to deal with the complexities of -doing the delay estimation. - -I no longer have root access to a LAN environment to develop and test broadcast -server support. Neither have I the time to work on this. I would be very -happy to accept a patch from anyone who can develop, test and debug the -necessary changes! - -Q: Can chronyd transmit broadcast NTP packets (e.g. to synchronise other computers on a private LAN)? -Yes. Starting from version 1.17, chrony has this capability. - -Q: Can chrony keep the system clock a fixed offset away from real time? -I have not experimented much, but I don't believe this would be possible as -the program currently stands. - -Q: What happens if the network connection is dropped without using chronyc's 'offline' command first? -In this case chronyd will keep trying to access the server(s) that it thinks -are online. Eventually it will decide that they are unreachable and no longer -consider itself synchronised to them. If you have other computers on your LAN -accessing the computer that is affected this way, they too will become -'unsynchronised', unless you have the 'local' directive set up on the master -computer. - -The 'auto_offline' option to the 'server' entry in the chrony.conf file may be -useful to avoid this situation. - -S: Development - -Q: Can I get the source via git from anywhere? -Yes. See the Git link at http://chrony.tuxfamily.org for -information. - -S: Linux-specific issues - -Q: Why does the source code include kernel header files? -The program needs to see the definitions of structures used to interact with -the real time clock (via /dev/rtc) and with the adjtimex() system call. Sadly -this has led to a number of compilation problems with newer kernels which have -been increasingly hard to fix in a way that makes the code compilable on all -Linux kernel versions. Hopefully -the situation will not deteriorate further with future kernel versions. - -Q: I get "Could not open /dev/rtc, Device or resource busy" in my syslog file. -Check that you haven't accidentally got two copies of chronyd running (perhaps -defined in different start-up scripts.) - -S: Solaris-specific issues -Q: On Solaris 2.8, I get an error message about not being able to open kvm to change dosynctodr. -(The dosynctodr variable controls whether Solaris couples the equivalent of its -BIOS clock into its system clock at regular intervals). The Solaris port of -chrony was developed in the Solaris 2.5 era. Some aspect of the Solaris kernel -has changed which prevents the same technique working. I no longer have root -access to any Solaris machines to work on this, and am reliant on somebody -developing the patch and testing it. A good starting point would be to see if -xntpd has been modified to work for Solaris 2.8. - -@@EPILOGUE -
- -Back to -the author's -main page - - -@@ENDEPILOGUE diff --git a/faqgen.pl b/faqgen.pl deleted file mode 100644 index 8151feb..0000000 --- a/faqgen.pl +++ /dev/null @@ -1,140 +0,0 @@ -#!/usr/bin/env perl - -# $Header - -# Copyright 2001 Richard P. Curnow -# LICENCE - -# A script to generate an HTML FAQ page from a text input file. The input is assumed to consist of the following: -# Lines starting with 'S:'. These introduce sections. -# Lines starting with 'Q:'. These are the topics of questions. -# Body text (either as an introduction to the sections, or as answers to the questions. -# The body text is set as pre-formatted. - -$| = 1; - -@prologue = (); -@epilogue = (); - -@sections=(); # section titles -@sect_text=(); # introductory text in sections - -@questions=(); # questions in sections -@answers=(); # answers to questions - -$sn = -1; -$had_q = 0; - -#{{{ Parse input -while (<>) { - if (m/\@\@PROLOG/o) { - while (<>) { - last if (m/^\@\@ENDPROLOG/); - push (@prologue, $_); - } - } elsif (m/\@\@EPILOG/o) { - while (<>) { - last if (m/^\@\@ENDEPILOG/); - push (@epilogue, $_); - } - } elsif (m/^[sS]:[ \t]*(.*)$/) { - chomp; - $qn = -1; - ++$sn; - $sections[$sn] = &guard($1); - $sect_text[$sn] = ""; - $questions[$sn] = [ ]; - $answers[$sn] = [ ]; - $had_q = 0; - } elsif (/^[qQ]:[ \t]*(.*)$/) { - chomp; - die unless ($sn >= 0); - ++$qn; - $questions[$sn]->[$qn] = &guard($1); - $had_q = 1; - } else { - if ($had_q) { - if ($qn >= 0) { - $answers[$sn]->[$qn] .= $_; - } - } else { - if ($sect_text[$sn] ne "" || $_ !~ /^\s*$/) { - $sect_text[$sn] .= $_; - } - } - } -} -#}}} - -# Emit file header -if ($#prologue >= 0) { - print @prologue; -} else { -print < - - -Chrony Frequently Asked Questions - - - -Table of contents -EOF -} - -# Emit table of contents -print "\n"; - -# Emit main sections -for $sn (0 .. $#sections) { - print "
\n"; - print "\n"; - #print "".($sn+1).". ".$sections[$sn]."\n"; - print "\n"; - if ($sect_text[$sn] ne "") { - print "
\n";
-        print $sect_text[$sn];
-        print "
\n"; - } - for $qn (0 .. $#{$questions[$sn]}) { - $sq = ($sn+1).".".($qn+1); - print "

\n"; - print "\n"; - print "".$sq.". ".$questions[$sn]->[$qn]."\n"; - print "

\n";
-        print $answers[$sn]->[$qn];
-        print "
\n"; - } -} - -# Print footer -if ($#epilogue >= 0) { - print @epilogue; -} else { -print < - -EOF -} - - -#{{{ sub guard { -sub guard { -# Hide wierd tags etc - my ($x) = @_; - return $x; -} -#}}} - - diff --git a/make_release b/make_release index fb79722..0a85e24 100755 --- a/make_release +++ b/make_release @@ -59,6 +59,16 @@ if [ $(wc -l < INSTALL) -gt 100 -o $(wc -l < INSTALL) -lt 85 ]; then exit 3 fi +awk '/^[1-9] Frequently asked questions$/{p=1} + /^Appendix A GNU General Public License$/{exit}; p' chrony.txt | \ + tail -n +4 | sed 's/^[1-9]\.\([1-9]\)/\1/' | sed 's/^----/--/' | \ + sed 's/^====/==/' > FAQ + +if [ $(wc -l < FAQ) -gt 400 -o $(wc -l < FAQ) -lt 200 ]; then + echo "FAQ generated incorrectly?" + exit 3 +fi + rm -f config.h config.log faqgen.pl make_release chrony.spec.sample .gitignore cd ..