ntpdate Command for NTPv4

Purpose

Sets the date and time by using the Network Time Protocol (NTP).

Syntax

ntpdate [ -46bBdqsuv ] [ -a key] [-e authdelay] [ -k keyfile] [ -o version] [ -p samples] [ -t timeout] server [...]

Description

The ntpdate command sets the local date and time by polling the NTP servers that are given as the server arguments to determine the correct time. The ntpdate command must run as a root on the local host. Samples are obtained from each specified server, and a subset of the NTP clock filter and selection algorithms are used to select the best sample.

Note: The accuracy and reliability of the ntpdate command depends on the number of servers, the number of polls that it runs each time, and the interval between the runs.

The ntpdate command is run manually when necessary to set the host clock, or run from the host startup script to set the clock at boot time. Such functions are useful to set the time in the clock initially before the ntpd daemon is started. It is also possible to run the ntpdate command from a cron script. However, the ntpdate command with contrived cron scripts is not a substitute for the ntpd daemon, which uses complex algorithms to maximize accuracy and reliability while minimizing resource use. Since the ntpdate command does not tune the host clock frequency as the ntpd daemon does, the accuracy is limited.

Time adjustments are made by the ntpdate command in the following ways:

If the ntpdate command determines that the clock has an error of more than 0.5 seconds, it steps the time by calling the system settimeofday subroutine.
If the error is less than 0.5 seconds, it slews the time by calling the system adjtime subroutine.

The second technique is less disruptive and more accurate when the error is small, and works well when the ntpdate command is run from a cron script every hour or two.

If the -u flag is not specified with the ntpdate command, the ntpdate command declines to set the date when the ntpd daemon is also run on the same host. If you run the ntpdate command regularly from a cron script instead of using a daemon, running it every hour or two keeps the time accurate enough to avoid stepping the clock.

If NetInfo support is compiled into the ntpdate command and the ntpdate command identifies a time server in the NetInfo configuration for ntpd, then the server argument is optional.

Flags

Table 1. Flags
Item	Description
-4	Forces DNS resolution of hostnames to the IP version 4 (IPv4) namespace.
-6	Forces DNS resolution of hostnames to the IP version 6 (IPv6) namespace.
-a `key`	Enables the authentication function and specifies the key identifier to be used for authentication as the argument key. The keys and key identifiers must match in both the client and server key files. The default is to disable the authentication function.
-B	Forces the time to be slewed by using the adjtime subroutine, regardless of whether the measured offset exceeds + or - 500 milliseconds. The default is to set the time by using the settimeofday subroutine if the offset is greater than + or -500 milliseconds. Note: If the offset is greater than + or - 500 millisecond, then slewing the clock to the correct value takes a long time (hours). During this process, it's essential not to use the host for synchronizing clients.
-b	Forces the time to be stepped by using the settimeofday subroutine system call, rather than slewed (default) by using the adjtime subroutine system call. This option is used when called from a startup file at boot time.
-d	Enable the debugging mode in which the ntpdate command goes through all the steps by using an unprivileged port, but does not adjust the local clock. It also prints information useful for general debugging.
-e `authdelay`	Specifies the processing delays to perform an authentication function. The processing delay time is specified by the `authdelay` variable in seconds and fractions. For more information, see the ntpd daemon. This number is small enough to be negligible for most purposes, but specifying it enhances timekeeping on slower CPUs.
-k `keyfile`	Specifies the path for the authentication key file as a string specified by the `keyfile` variable. The default is `/etc/ntp.keys`. This file needs to be in the format that is described in the ntpd demon.
-o `version`	Specifies the NTP version for outgoing packets as an integer specified by the `version` variable. The valid values for the version variable are 1, 2, 3, or 4. The default value is 4. This option enables the ntpdate command to be used with older NTP versions.
-p `samples`	Specifies the number of samples to be acquired from each server as an integer specified by the `samples` variable. The default value is 4.
-q	Specifies the query. The -q option does not set the clock.
-s	Diverts the logging output from the standard output (default) to the system `SYSLOG` facility. It is designed primarily for convenience of `cron` scripts.
-t `timeout`	Specifies the maximum waiting time for a server response. The maximum waiting time is specified by the `timeout` variable in seconds and fractions. The value is rounded to a multiple of 0.2 seconds. The default value is 2 seconds, which is suitable for polling across a LAN.
-u	Directs the ntpdate command to use an unprivileged port for outgoing packets. This option is useful if you are behind a firewall that blocks incoming traffic to privileged ports and you need to synchronize with hosts outside the firewall. Note: The -d option always uses the unprivileged ports.
-v	Verbose output. This option causes the version identification string of the ntpdate command to be logged.

Parameters

Table 2. Parameters
Item	Description
`Server...`	Specifies the servers to poll

Exit Status

The ntpdate command returns the following exit values:

Table 3. Exit Status
Item	Description
`0`	Successful completion.
`nonzero`	An error occurred.

Security

Access Control: You must have root authority to run this command.
Auditing Events: N/A

Examples

To set the local date and time by polling the NTP servers at address 9.41.254.24, enter the following command:
```
ntpdate 9.41.254.24
```
An output similar to the following output is displayed:
```
address: ::
address: 0.0.0.0
25 Feb 12:19:41 ntpdate[434262]: adjust time server 9.41.254.24 offset -0.005270  sec
```

Files

Table 4. Files
Item	Description
/usr/sbin/ntp4/ntpdate4	Contains the ntpdate command for NTP version 4. Default Symbolic link to NTP version 3 binary from /usr/sbin directory. /usr/sbin/ntpdate `-->` /usr/sbin/ntp3/ntpdate
/etc/ntp.keys	Encryption keys used by ntpdate.