diff options
Diffstat (limited to 'ntpd/invoke-ntpd.texi')
| -rw-r--r-- | ntpd/invoke-ntpd.texi | 719 |
1 files changed, 719 insertions, 0 deletions
diff --git a/ntpd/invoke-ntpd.texi b/ntpd/invoke-ntpd.texi new file mode 100644 index 000000000000..a781b26681f8 --- /dev/null +++ b/ntpd/invoke-ntpd.texi @@ -0,0 +1,719 @@ +@node ntpd Invocation +@section Invoking ntpd +@pindex ntpd +@cindex NTP daemon program +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-ntpd.texi) +# +# It has been AutoGen-ed October 21, 2015 at 12:38:21 PM by AutoGen 5.18.5 +# From the definitions ntpd-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + + +The +@code{ntpd} +utility is an operating system daemon which sets +and maintains the system time of day in synchronism with Internet +standard time servers. +It is a complete implementation of the +Network Time Protocol (NTP) version 4, as defined by RFC-5905, +but also retains compatibility with +version 3, as defined by RFC-1305, and versions 1 +and 2, as defined by RFC-1059 and RFC-1119, respectively. + +The +@code{ntpd} +utility does most computations in 64-bit floating point +arithmetic and does relatively clumsy 64-bit fixed point operations +only when necessary to preserve the ultimate precision, about 232 +picoseconds. +While the ultimate precision is not achievable with +ordinary workstations and networks of today, it may be required +with future gigahertz CPU clocks and gigabit LANs. + +Ordinarily, +@code{ntpd} +reads the +@code{ntp.conf(5)} +configuration file at startup time in order to determine the +synchronization sources and operating modes. +It is also possible to +specify a working, although limited, configuration entirely on the +command line, obviating the need for a configuration file. +This may +be particularly useful when the local host is to be configured as a +broadcast/multicast client, with all peers being determined by +listening to broadcasts at run time. + +If NetInfo support is built into +@code{ntpd} +then +@code{ntpd} +will attempt to read its configuration from the +NetInfo if the default +@code{ntp.conf(5)} +file cannot be read and no file is +specified by the +@code{-c} +option. + +Various internal +@code{ntpd} +variables can be displayed and +configuration options altered while the +@code{ntpd} +is running +using the +@code{ntpq(1ntpqmdoc)} +and +@code{ntpdc(1ntpdcmdoc)} +utility programs. + +When +@code{ntpd} +starts it looks at the value of +@code{umask(2)}, +and if zero +@code{ntpd} +will set the +@code{umask(2)} +to 022. + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpd} program. +This software is released under the NTP license, <http://ntp.org/license>. + +@menu +* ntpd usage:: ntpd help/usage (@option{--help}) +* ntpd ipv4:: ipv4 option (-4) +* ntpd ipv6:: ipv6 option (-6) +* ntpd authreq:: authreq option (-a) +* ntpd authnoreq:: authnoreq option (-A) +* ntpd configfile:: configfile option (-c) +* ntpd driftfile:: driftfile option (-f) +* ntpd panicgate:: panicgate option (-g) +* ntpd force-step-once:: force-step-once option (-G) +* ntpd jaildir:: jaildir option (-i) +* ntpd interface:: interface option (-I) +* ntpd keyfile:: keyfile option (-k) +* ntpd logfile:: logfile option (-l) +* ntpd novirtualips:: novirtualips option (-L) +* ntpd modifymmtimer:: modifymmtimer option (-M) +* ntpd nice:: nice option (-N) +* ntpd pidfile:: pidfile option (-p) +* ntpd priority:: priority option (-P) +* ntpd quit:: quit option (-q) +* ntpd propagationdelay:: propagationdelay option (-r) +* ntpd saveconfigquit:: saveconfigquit option +* ntpd statsdir:: statsdir option (-s) +* ntpd trustedkey:: trustedkey option (-t) +* ntpd user:: user option (-u) +* ntpd updateinterval:: updateinterval option (-U) +* ntpd wait-sync:: wait-sync option (-w) +* ntpd slew:: slew option (-x) +* ntpd usepcc:: usepcc option +* ntpd pccfreq:: pccfreq option +* ntpd mdns:: mdns option (-m) +* ntpd config:: presetting/configuring ntpd +* ntpd exit status:: exit status +* ntpd Usage:: Usage +* ntpd Files:: Files +* ntpd See Also:: See Also +* ntpd Bugs:: Bugs +* ntpd Notes:: Notes +@end menu + +@node ntpd usage +@subsection ntpd help/usage (@option{--help}) +@cindex ntpd help + +This is the automatically generated usage text for ntpd. + +The text printed is the same whether selected with the @code{help} option +(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example +ntpd - NTP daemon program - Ver. 4.2.8p4 +Usage: ntpd [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... \ + [ <server1> ... <serverN> ] + Flg Arg Option-Name Description + -4 no ipv4 Force IPv4 DNS name resolution + - prohibits the option 'ipv6' + -6 no ipv6 Force IPv6 DNS name resolution + - prohibits the option 'ipv4' + -a no authreq Require crypto authentication + - prohibits the option 'authnoreq' + -A no authnoreq Do not require crypto authentication + - prohibits the option 'authreq' + -b no bcastsync Allow us to sync to broadcast servers + -c Str configfile configuration file name + -d no debug-level Increase debug verbosity level + - may appear multiple times + -D Num set-debug-level Set the debug verbosity level + - may appear multiple times + -f Str driftfile frequency drift file name + -g no panicgate Allow the first adjustment to be Big + - may appear multiple times + -G no force-step-once Step any initial offset correction. + -i Str jaildir Jail directory + -I Str interface Listen on an interface name or address + - may appear multiple times + -k Str keyfile path to symmetric keys + -l Str logfile path to the log file + -L no novirtualips Do not listen to virtual interfaces + -n no nofork Do not fork + - prohibits the option 'wait-sync' + -N no nice Run at high priority + -p Str pidfile path to the PID file + -P Num priority Process priority + -q no quit Set the time and quit + - prohibits these options: + saveconfigquit + wait-sync + -r Str propagationdelay Broadcast/propagation delay + Str saveconfigquit Save parsed configuration and quit + - prohibits these options: + quit + wait-sync + -s Str statsdir Statistics file location + -t Str trustedkey Trusted key number + - may appear multiple times + -u Str user Run as userid (or userid:groupid) + -U Num updateinterval interval in seconds between scans for new or dropped interfaces + Str var make ARG an ntp variable (RW) + - may appear multiple times + Str dvar make ARG an ntp variable (RW|DEF) + - may appear multiple times + -w Num wait-sync Seconds to wait for first clock sync + - prohibits these options: + nofork + quit + saveconfigquit + -x no slew Slew up to 600 seconds + opt version output version information and exit + -? no help display extended usage information and exit + -! no more-help extended usage information passed thru pager + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + + +The following option preset mechanisms are supported: + - examining environment variables named NTPD_* + +Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org> +@end example +@exampleindent 4 + +@node ntpd ipv4 +@subsection ipv4 option (-4) +@cindex ntpd-ipv4 + +This is the ``force ipv4 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv6. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +@node ntpd ipv6 +@subsection ipv6 option (-6) +@cindex ntpd-ipv6 + +This is the ``force ipv6 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv4. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +@node ntpd authreq +@subsection authreq option (-a) +@cindex ntpd-authreq + +This is the ``require crypto authentication'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +authnoreq. +@end itemize + +Require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is the default. +@node ntpd authnoreq +@subsection authnoreq option (-A) +@cindex ntpd-authnoreq + +This is the ``do not require crypto authentication'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +authreq. +@end itemize + +Do not require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is almost never a good idea. +@node ntpd configfile +@subsection configfile option (-c) +@cindex ntpd-configfile + +This is the ``configuration file name'' option. +This option takes a string argument. +The name and path of the configuration file, +@file{/etc/ntp.conf} +by default. +@node ntpd driftfile +@subsection driftfile option (-f) +@cindex ntpd-driftfile + +This is the ``frequency drift file name'' option. +This option takes a string argument. +The name and path of the frequency file, +@file{/etc/ntp.drift} +by default. +This is the same operation as the +@code{driftfile} @kbd{driftfile} +configuration specification in the +@file{/etc/ntp.conf} +file. +@node ntpd panicgate +@subsection panicgate option (-g) +@cindex ntpd-panicgate + +This is the ``allow the first adjustment to be big'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +Normally, +@code{ntpd} +exits with a message to the system log if the offset exceeds the panic threshold, which is 1000 s by default. This option allows the time to be set to any value without restriction; however, this can happen only once. If the threshold is exceeded after that, +@code{ntpd} +will exit with a message to the system log. This option can be used with the +@code{-q} +and +@code{-x} +options. +See the +@code{tinker} +configuration file directive for other options. +@node ntpd force-step-once +@subsection force-step-once option (-G) +@cindex ntpd-force-step-once + +This is the ``step any initial offset correction.'' option. +Normally, +@code{ntpd} +steps the time if the time offset exceeds the step threshold, +which is 128 ms by default, and otherwise slews the time. +This option forces the initial offset correction to be stepped, +so the highest time accuracy can be achieved quickly. +However, this may also cause the time to be stepped back +so this option must not be used if +applications requiring monotonic time are running. +See the @code{tinker} configuration file directive for other options. +@node ntpd jaildir +@subsection jaildir option (-i) +@cindex ntpd-jaildir + +This is the ``jail directory'' option. +This option takes a string argument. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{HAVE_DROPROOT} during the compilation. +@end itemize + +Chroot the server to the directory +@kbd{jaildir} +. +This option also implies that the server attempts to drop root privileges at startup. +You may need to also specify a +@code{-u} +option. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +@code{--enable-clockctl}) or Linux (configure with +@code{--enable-linuxcaps}) or Solaris (configure with @code{--enable-solarisprivs}). +@node ntpd interface +@subsection interface option (-I) +@cindex ntpd-interface + +This is the ``listen on an interface name or address'' option. +This option takes a string argument @file{iface}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +Open the network address given, or all the addresses associated with the +given interface name. This option may appear multiple times. This option +also implies not opening other addresses, except wildcard and localhost. +This option is deprecated. Please consider using the configuration file +@code{interface} command, which is more versatile. +@node ntpd keyfile +@subsection keyfile option (-k) +@cindex ntpd-keyfile + +This is the ``path to symmetric keys'' option. +This option takes a string argument. +Specify the name and path of the symmetric key file. +@file{/etc/ntp.keys} +is the default. +This is the same operation as the +@code{keys} @kbd{keyfile} +configuration file directive. +@node ntpd logfile +@subsection logfile option (-l) +@cindex ntpd-logfile + +This is the ``path to the log file'' option. +This option takes a string argument. +Specify the name and path of the log file. +The default is the system log file. +This is the same operation as the +@code{logfile} @kbd{logfile} +configuration file directive. +@node ntpd novirtualips +@subsection novirtualips option (-L) +@cindex ntpd-novirtualips + +This is the ``do not listen to virtual interfaces'' option. +Do not listen to virtual interfaces, defined as those with +names containing a colon. This option is deprecated. Please +consider using the configuration file @code{interface} command, which +is more versatile. +@node ntpd modifymmtimer +@subsection modifymmtimer option (-M) +@cindex ntpd-modifymmtimer + +This is the ``modify multimedia timer (windows only)'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SYS_WINNT} during the compilation. +@end itemize + +Set the Windows Multimedia Timer to highest resolution. This +ensures the resolution does not change while ntpd is running, +avoiding timekeeping glitches associated with changes. +@node ntpd nice +@subsection nice option (-N) +@cindex ntpd-nice + +This is the ``run at high priority'' option. +To the extent permitted by the operating system, run +@code{ntpd} +at the highest priority. +@node ntpd pidfile +@subsection pidfile option (-p) +@cindex ntpd-pidfile + +This is the ``path to the pid file'' option. +This option takes a string argument. +Specify the name and path of the file used to record +@code{ntpd}'s +process ID. +This is the same operation as the +@code{pidfile} @kbd{pidfile} +configuration file directive. +@node ntpd priority +@subsection priority option (-P) +@cindex ntpd-priority + +This is the ``process priority'' option. +This option takes a number argument. +To the extent permitted by the operating system, run +@code{ntpd} +at the specified +@code{sched_setscheduler(SCHED_FIFO)} +priority. +@node ntpd quit +@subsection quit option (-q) +@cindex ntpd-quit + +This is the ``set the time and quit'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +saveconfigquit, wait-sync. +@end itemize + +@code{ntpd} +will not daemonize and will exit after the clock is first +synchronized. This behavior mimics that of the +@code{ntpdate} +program, which will soon be replaced with a shell script. +The +@code{-g} +and +@code{-x} +options can be used with this option. +Note: The kernel time discipline is disabled with this option. +@node ntpd propagationdelay +@subsection propagationdelay option (-r) +@cindex ntpd-propagationdelay + +This is the ``broadcast/propagation delay'' option. +This option takes a string argument. +Specify the default propagation delay from the broadcast/multicast server to this client. This is necessary only if the delay cannot be computed automatically by the protocol. +@node ntpd saveconfigquit +@subsection saveconfigquit option +@cindex ntpd-saveconfigquit + +This is the ``save parsed configuration and quit'' option. +This option takes a string argument. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SAVECONFIG} during the compilation. +@item +must not appear in combination with any of the following options: +quit, wait-sync. +@end itemize + +Cause @code{ntpd} to parse its startup configuration file and save an +equivalent to the given filename and exit. This option was +designed for automated testing. +@node ntpd statsdir +@subsection statsdir option (-s) +@cindex ntpd-statsdir + +This is the ``statistics file location'' option. +This option takes a string argument. +Specify the directory path for files created by the statistics facility. +This is the same operation as the +@code{statsdir} @kbd{statsdir} +configuration file directive. +@node ntpd trustedkey +@subsection trustedkey option (-t) +@cindex ntpd-trustedkey + +This is the ``trusted key number'' option. +This option takes a string argument @file{tkey}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +Add the specified key number to the trusted key list. +@node ntpd user +@subsection user option (-u) +@cindex ntpd-user + +This is the ``run as userid (or userid:groupid)'' option. +This option takes a string argument. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{HAVE_DROPROOT} during the compilation. +@end itemize + +Specify a user, and optionally a group, to switch to. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +@code{--enable-clockctl}) or Linux (configure with +@code{--enable-linuxcaps}) or Solaris (configure with @code{--enable-solarisprivs}). +@node ntpd updateinterval +@subsection updateinterval option (-U) +@cindex ntpd-updateinterval + +This is the ``interval in seconds between scans for new or dropped interfaces'' option. +This option takes a number argument. +Give the time in seconds between two scans for new or dropped interfaces. +For systems with routing socket support the scans will be performed shortly after the interface change +has been detected by the system. +Use 0 to disable scanning. 60 seconds is the minimum time between scans. +@node ntpd wait-sync +@subsection wait-sync option (-w) +@cindex ntpd-wait-sync + +This is the ``seconds to wait for first clock sync'' option. +This option takes a number argument. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{HAVE_WORKING_FORK} during the compilation. +@item +must not appear in combination with any of the following options: +nofork, quit, saveconfigquit. +@end itemize + +If greater than zero, alters @code{ntpd}'s behavior when forking to +daemonize. Instead of exiting with status 0 immediately after +the fork, the parent waits up to the specified number of +seconds for the child to first synchronize the clock. The exit +status is zero (success) if the clock was synchronized, +otherwise it is @code{ETIMEDOUT}. +This provides the option for a script starting @code{ntpd} to easily +wait for the first set of the clock before proceeding. +@node ntpd slew +@subsection slew option (-x) +@cindex ntpd-slew + +This is the ``slew up to 600 seconds'' option. +Normally, the time is slewed if the offset is less than the step threshold, which is 128 ms by default, and stepped if above the threshold. +This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. +Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s. +Thus, an adjustment as much as 600 s will take almost 14 days to complete. +This option can be used with the +@code{-g} +and +@code{-q} +options. +See the +@code{tinker} +configuration file directive for other options. +Note: The kernel time discipline is disabled with this option. +@node ntpd usepcc +@subsection usepcc option +@cindex ntpd-usepcc + +This is the ``use cpu cycle counter (windows only)'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SYS_WINNT} during the compilation. +@end itemize + +Attempt to substitute the CPU counter for @code{QueryPerformanceCounter}. +The CPU counter and @code{QueryPerformanceCounter} are compared, and if +they have the same frequency, the CPU counter (RDTSC on x86) is +used directly, saving the overhead of a system call. +@node ntpd pccfreq +@subsection pccfreq option +@cindex ntpd-pccfreq + +This is the ``force cpu cycle counter use (windows only)'' option. +This option takes a string argument. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{SYS_WINNT} during the compilation. +@end itemize + +Force substitution the CPU counter for @code{QueryPerformanceCounter}. +The CPU counter (RDTSC on x86) is used unconditionally with the +given frequency (in Hz). +@node ntpd mdns +@subsection mdns option (-m) +@cindex ntpd-mdns + +This is the ``register with mdns as a ntp server'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must be compiled in by defining @code{HAVE_DNSREGISTRATION} during the compilation. +@end itemize + +Registers as an NTP server with the local mDNS server which allows +the server to be discovered via mDNS client lookup. + + +@node ntpd config +@subsection presetting/configuring ntpd + +Any option that is not marked as @i{not presettable} may be preset by +loading values from environment variables named @code{NTPD} and @code{NTPD_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of +the options listed above in upper case and segmented with underscores. +The @code{NTPD} variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + + +The command line options relating to configuration and/or usage help are: + +@subsubheading version (-) + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. +Only the first letter of the argument is examined: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node ntpd exit status +@subsection ntpd exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@end table +@node ntpd Usage +@subsection ntpd Usage +@node ntpd Files +@subsection ntpd Files +@node ntpd See Also +@subsection ntpd See Also +@node ntpd Bugs +@subsection ntpd Bugs +@node ntpd Notes +@subsection ntpd Notes |