vsntp/doc/vsntp.8

.\" Process this file with
.\" groff -man -Tascii vsntp.8
.\"
.TH VSNTP 8 "MARCH 2007" VSNTP "System Administration Tools"
.SH NAME
vsntp \- SNTP client for Virtual PC
.SH SYNOPSIS
.BI "vsntp [-i " n "] [-p " file "] [-a|-s] " server
.SH DESCRIPTION
.B vsntp
is an
.SM SNTP
client daemon for machines without a sane system time.  The word
.B vsntp
stands for
.BR "SNTP for Virtual PC" .
It was originally designed for my
.I GNU/Linux
server running on Connectix Virtual PC.  It runs according to
.SM RFC
1769
.SM SNTP
, connecting the
.SM NTP
server on
.SM UDP
port 123.  It has only been compiled and run on
.I GNU/Linux
before.

Without "Virtual
.SM PC
Additions", the system time on Virtual
.SM PC
is completely insane.  It's
.SM RTC
(Real Time Clock, or
.SM CMOS
time, or hardware clock) is software emulated, which does not seems
to be running.  The
.I GNU/Linux
kernel hardly maintains a system time itself.  With smooth run it
goes 4 seconds ahead per minute, which is nearly 1.5 hours per day.
That is insane.  You can even tell it with your eyes.

David L. Mills'
.B ntp
does not work here.  It uses a method that learns the clock frequency
drift first, and adjust the kernel clock with
.B adjtimex()
so that time adjustment goes smoothly, from the point of view of
system and applications.  This assumes an existing fix-speed system
clock.  But this is not the case here.  The system clock on Virtual
.SM PC
is software emulated.  It goes faster or slower 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.

There is an
.B sntp
client that comes with David L. Mills'
.B ntp
package.
It is suggested to be run from crontab.  But crontab runs by minutes,
and Virtual
.SM PC
goes 4 seconds ahead per minute.  Rolling back 4 seconds every minute
is insane for most applications.  It also increases system load
heavily to run one instance per minute.

.B vsntp
is a workaround on this.  It runs as a daemon to to eliminates the
additional system load on every synchronization.  It uses
.B settimeofday()
to synchronize the time.  It synchronizes the
time with an arbitrary interval, so that time can be accurate within
a second.

There are some defects.  Synchronizing the time too often introduces
heavy network load.  It introduces heavy load on the target
.SM NTP
server, too.  You should have a working
.SM NTP
server nearby that is owned by you.  Also, since
.B settimeofday()
is called so often, highly-accurate time operations like timer, etc.,
may not run correctly.

.B vsntp
uses
.BI sleep()
as the synchronization scheduler.  Reports show that on some systems
.BI sleep()
may not function normally.  If you find
.BI vsntp
stops synchronization after running for some time, that the
.BI sleep()
is not functioning normally on your system, you may want to switch
to the
.BI alarm()
scheduler with the
.B -a
switch.

.B vsntp
was originally written for
.I GNU/Linux .
It uses
.SM POSIX
compatible system calls.  It should work on any
.SM POSIX
compatible system.  But I have yet only tested it on Cygwin.  Cygwin
is known to work.  I don't have others to test and run on.  Please let
me know (and submit the patch if needed) if you can port it to other
systems.  I know it does not work on MSWin32, for the way it handles
the
.SM PID
file path.

Please tell me if you have successfully running vsntp on other virtual
machines, like
.BR "VMWare" .

Generally, please tell me if you are using
.B "vsntp" .
I would like to know that I am really doing some good for the world,
*^_^*  but not having fun myself. :p

This is my first daemon, my first socket program and my first
public-released C program.  Any comment or suggestion is welcome. ^_*'
.SH OPTIONS
.IP "-i,--interval n"
Set the synchronization interval to
.I n
seconds.  Default is 900 seconds (15 minutes).
.IP "-p,--pidfile file"
The
.SM PID
file location.  Default to
.IR /var/run/vsntp.pid .
.IP -s,--sleep
Use
.BI sleep()
as the scheduler.  This is currently the default.
.IP -a,--alarm
Use
.BI alarm()
as the scheduler.
.IP -h,--help
Display the help message.
.IP -v,--version
Display version information.
.SH FILES
.I /var/run/vsntp.pid
.RS
The
.SM PID
of the running daemon.
.SH DIAGNOSTICS
If you ever encounter any problem, you may check your syslog.
.B vsntp
logs detailed debugging information to syslog in log level
.B LOG_DEBUG
with facility
.B LOG_DAEMON .
You may turn it on in your
.I /etc/syslog.conf
with the following line:

  daemon.debug   /var/log/debug

and check the
.I /var/log/debug
file for the debugging message.  Remember to remove this afterwards,
for the amount of the debugging messages may be huge and may use up
your hard disk in a very short time.  To the least it may slow down
your system for frequent hard disk
.SM "I/O" .
.SH BUGS
The
.B vsntp
project is hosted on GitHub.  Address your issues on the GitHub issue
tracker https://github.com/imacat/chklinks/issues.
.SH AUTHOR
imacat <imacat@mail.imacat.idv.tw>.
.SH "SEE ALSO"
.BR settimeofday (2),
.BR adjtimex (2),
.BR sleep (3),
.BR alarm (2).

.BR ntp :
http://www.ntp.org/ .

.SM RFC
1769
.SM SNTP
: http://www.faqs.org/rfcs/rfc1769.html .

.SM RFC
1305
.SM NTP
: http://www.faqs.org/rfcs/rfc1305.html .