\input texinfo   @c -*-texinfo-*-@c %**start of header@setfilename vsntp.info@include version.texi@settitle vsntp v@value{VERSION}@syncodeindex vr cp@syncodeindex pg cp@c %**end of header@copyingThis manual is for vsntp(version @value{VERSION}, @value{UPDATED}),a SNTP daemon for Virtual @acronym{PC}@.Copyright @copyright{} 2003-2007 imacat@.@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the @acronym{GNU} Free Documentation License, Version 1.2or any later version published by the Free Software Foundation;with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts@.A copy of the license is included in the section entitled ``@acronym{GNU}Free Documentation License''@.@end quotation@end copying@titlepage@title vsntp v@value{VERSION}@c The following two commands start the copyright page.@page@vskip 0pt plus 1filll@insertcopyingPublished by imacat@*@email{imacat@@mail.imacat.idv.tw}@*@uref{http://www.imacat.idv.tw/}@*@end titlepage@c Output the table of contents at the beginning.@contents@ifnottex@node Top@top Short Sample@insertcopying@end ifnottex@menu* Introduction::* Download the Newest Version: Download.* Compilation and Installation: Install.* Running and Stopping: Run.* Command Line Options: Options.* Supports and Bugs Report: Support.* References::* Copyright::* Index::@end menu@node Introduction@chapter Introduction@pindex Virtual PC@pindex Connectix Virtual PC@cindex RFC 1769 SNTP@cindex UDP@dfn{vsntp} is an @acronym{SNTP} client daemon for machines without asane system time@.  The word ``@dfn{vsntp}'' stands for``@dfn{@acronym{SNTP} for Virtual PC}''@.  It was originally designedfor my @acronym{GNU}/Linux server running on Connectix Virtual @acronym{PC}@.It runs according to @acronym{RFC} 1769 @acronym{SNTP}, connectingthe @acronym{NTP} server on @acronym{UDP} port 123@.  It was originallywritten for @acronym{GNU}/Linux@.Without Virtual @acronym{PC} Additions, the system time on Virtual @acronym{PC} iscompletely insane@.  It's @acronym{RTC} (Real Time Clock, or@acronym{CMOS} time, or hardware clock) is software emulated, whichdoes not seems to be running@.  The @acronym{GNU}/Linux kernel hardlymaintains a system time itself@.  With smooth run it goes 4 secondsahead per minute, which is nearly 1.5 hours per day@.  That isinsane@.  You can even tell it with your eyes@.@pindex David L. Mills@pindex ntp@findex adjtimex()@uref{http://www.ntp.org/,David L. Mills' @command{ntp}} does notwork here@.  It uses a method that learns the clock frequency driftfirst, and adjust the kerenl clock with @code{adjtimex()} so thattime adjustment goes smoothly, from the point of view of system andapplications@.  This assumes an existing fix-speed system clock@.But this is not the case of Virtual @acronym{PC}@.  The system clockon Virtual @acronym{PC} is software emulated@.  It can be faster orslower now and then, depending on the load of the hosting machine@.There is no fixed clock speed@.  The frequency drift does not exist,then@.  It dooms to fail to measure it@.@pindex sntpThere is an @command{sntp} client that comes with David L. Mills'@command{ntp} package@.  It is suggested to be run from@command{crontab}@.  But @command{crontab} runs by minutes, andVirtual @acronym{PC} goes 4 seconds ahead per minute@.  Rolling back4 seconds every minute is insane for most applications@.  It alsoincreases system load heavily to run one instance per minute@.@findex settimeofday()@command{vsntp} is a workaround on this@.  It runs as a daemon toeliminates the additional system load on every synchronization@.  Ituses @code{settimeofday()} to synchronize the time@.  It synchronizesthe time with an arbitrary interval, so that time can be accuratewithin a second@.There are some defects@.  Synchronizing the time too often introducesheavy network load@.  It introduces heavy load on the target@acronym{NTP} server, too@.  You should have a working@acronym{NTP} server nearby that is owned by you@.  Also, since@code{settimeofday()} is called so often, high-accurate timeoperations like timer, @acronym{etc.}, may not run correctly@.@findex sleep()@findex alarm()@command{vsntp} uses @code{sleep()} as the synchronization scheduler.Reports show that on some systems @code{sleep()} may not functionnormally@.  If you find @command{vsntp} stops synchronization afterrunning for some time, that the @code{sleep()} is not functioningnormally on your system, you may want to switch to the @code{alarm()}scheduler with the @option{-a} switch@.If you ever encounter any problem, you may check your syslog@.@command{vsntp} logs detailed debugging information to syslog in loglevel @code{LOG_DEBUG} with facility @code{LOG_DAEMON}@.  You may turnit on in your @file{/etc/syslog.conf} with the following line:@exampledaemon.debug   /var/log/debug@end exampleand check the @file{/var/log/debug} file for the debugging message@.Remember to remove this afterwards, for the amount of the debuggingmessages may be huge and may use up your harddisk in a very shorttime@.  To the least it may slow down your system for frequentharddisk @acronym{I/O}@.@command{vsntp} was originally written for @acronym{GNU}/Linux@.  Ituses @acronym{POSIX} compatible system calls@.  It should work onany @acronym{POSIX} compatible system@.  But I have yet only testedit on @uref{http://www.cygwin.com/, Cygwin}@.  Cygwin is known towork.  I don't have others to test and run on.  Pleaselet me know (and submit the patch if needed) if you can port it toother systems@.  I know it does not work on MSWin32, for the way ithandles the @acronym{PID} file path@.Please tell me if you have successfully running @command{vsntp} onother virtual machines, like @uref{http://www.vmware.com/, VMWare}@.Generally, please tell me if you are using @command{vsntp}@.  Iwould like to know that I am really doing some good for the world,*^_^*  but not having fun myself@. :p@node Download@chapter Download the Newest Version@cindex website@cindex official website@cindex download@cindex SourceForge@cindex Tavern IMACAT's@command{vsntp}'s official website is at@dots{}@itemize@item@uref{https://sourceforge.net/,SourceForge}'s home site:@uref{http://vsntp.sourceforge.net/}@item@uref{https://sourceforge.net/,SourceForge}'s project page:@uref{https://sourceforge.net/projects/vsntp/}@item@uref{http://www.imacat.idv.tw/,Tavern IMACAT's} page:@uref{http://www.imacat.idv.tw/tech/vsntp.html}@end itemizeYou can always download the newest version of @command{vsntp}from@dots{}@itemize@itemSourceForge:@uref{https://sourceforge.net/project/showfiles.php?group_id=99098}@itemTavern IMACAT's @acronym{FTP}:@uref{ftp://ftp.imacat.idv.tw/pub/vsntp/}@end itemizeimacat's @acronym{PGP} public key is at@dots{}@itemize@itemSourceForge:@uref{http://vsntp.sourceforge.net/pgpkey.asc}@itemTavern IMACAT's:@uref{http://www.imacat.idv.tw/me/pgpkey.asc}@end itemize@node Install@chapter Compilation and Installation@command{vsntp} uses standard @acronym{GNU} @command{autoconf} tocompile and install:@enumerate@itemDownload, unzip and untar the @command{vsntp} package:@example% tar xzf vsntp-@value{VERSION}.tar.gz@end example@itemGo into its directory:@example% cd vsntp-@value{VERSION}@end example@pindex configure@itemConfigure with @command{./configure}:@example% ./configure@end example@itemCompile with @command{make}:@example% make@end exampleThe resulted executable will be named @file{vsntp}@.@itemYou need to be @code{root} in order to install @command{vsntp}:@example% suPassword:#@end example@itemYou can simply copy @command{vsntp} to the appropriate directory:@example# cp vsntp /usr/local/sbin@end exampleOr, you can run automatic install:@example# make install@end exampleYou can reduce the size of the installed executable by stripping offdebug symbols inside:@example# make install-strip@end exampleBy default @command{vsntp} will be installed in@file{/usr/local/sbin}@.@end enumerate@node Run@chapter Running and StoppingYou need to be @code{root} to run @command{vsntp}@.  @command{vsntp}uses @code{settimeofday()} to set the system time@.@code{settimeofday()} requires @code{root} privilege@.To start @command{vsntp}, just specify your @acronym{NTP} server:@example# vsntp my.ntp.server.com@end example@command{vsntp} writes its @acronym{PID} in@file{/var/run/vsntp.pid}@.  To stop @command{vsntp}, @command{kill}it by its @acronym{PID}:@example# kill `cat /var/run/vsntp.pid`@end exampleThe @acronym{PID} file location can be changed with the @option{-p}switch.@node Options@chapter Command Line Options@defopt{-i,--interval} @var{n}Set the synchronization interval to @var{n} seconds@.  Default is900@dmn{sec} (15@dmn{min})@.@end defopt@defopt{-p,--pidfile} @var{file}The @acronym{PID} file location@.  Default to @file{/var/run/vsntp.pid}@.@end defopt@defopt{-s,--sleep}Use @code{sleep()} to schedule synchronization@.  (default)@end defopt@defopt{-a,--alarm}Use @code{alarm()} to schedule synchronization@.@end defopt@defopt{-h,--help}Display the help message@.@end defopt@defopt{-v,--version}Display version information@.@end defopt@node Support@chapter Supports and Bugs Report@cindex SourceForge@cindex Tavern IMACAT's@command{vsntp} is hosted on@uref{https://sourceforge.net/,SourceForge} and@uref{http://www.imacat.idv.tw/,Tavern IMACAT's}@.  For the latestinfomation, see:@itemize@item@uref{http://vsntp.sourceforge.net/}@item@uref{https://sourceforge.net/projects/vsntp/}@item@uref{http://www.imacat.idv.tw/tech/vsntp.html}@end itemize@cindex mailing list@cindex Mailman@command{vsntp} has a mailing list hosted at@uref{https://sourceforge.net/,SourceForge}:@email{vsntp-users@@lists.sourceforge.net}@.  Please submit yourquestions, suggestions or bug reports there@.  It is a@uref{http://www.list.org/,Mailman} mailing list@.  For moreinformation, see:@uref{https://lists.sourceforge.net/lists/listinfo/vsntp-users}@.Alternatively, you can send a mail to:@email{vsntp-users-request@@lists.sourceforge.net}with the subject @code{help} for a list of available e-mailcommands@.@node References@unnumbered References@findex settimeofday()@findex adjtimex()@pindex ntp@cindex RFC 1769 SNTP@cindex RFC 1305 NTP@itemize@item@inforef{High-Resolution Calendar, ,libc}, for settimeofday() and adjtimex().@inforef{Setting an Alarm, ,libc}, for alarm().@inforef{Sleeping, ,libc}, for sleep().@item@uref{http://www.ntp.org/,ntp}@item@uref{http://www.faqs.org/rfcs/rfc1769.html,@acronym{RFC} 1769 @acronym{SNTP}}.@item@uref{http://www.faqs.org/rfcs/rfc1305.html,@acronym{RFC} 1305 @acronym{NTP}}.@end itemize@node Copyright@unnumbered Copyright@quotationCopyright @copyright{} 2003-2007 imacat@.This program is free software; you can redistribute it and/or modifyit under the terms of the @cite{@acronym{GNU} General Public License}as published by the Free Software Foundation; either version 2 of theLicense, or (at your option) any later version@.This program is distributed in the hope that it will be useful, but@emph{WITHOUT ANY WARRANTY}; without even the implied warranty of@emph{MERCHANTABILITY} or @emph{FITNESS FOR A PARTICULAR PURPOSE}@.See the @cite{@acronym{GNU} General Public License} for more details@.You should have received a copy of the @cite{@acronym{GNU} GeneralPublic License} along with this program; if not, write to the FreeSoftware Foundation, Inc., 59 Temple Place - Suite 330, Boston,@acronym{MA} 02111-1307, @acronym{USA}@.@end quotation@node Index@unnumbered Index@printindex cp@bye@bye