Change SNTP Attributes (CHGNTPA)

The Change Network Time Protocol Attributes (CHGNTPA) command is used to change configurable Simple Network Time Protocol (SNTP) service attributes. The changes take effect the next time the SNTP service is started either by the Start TCP/IP(STRTCP) command or by the Start TCP/IP Server (STRTCPSVR) command.

Most of the SNTP attributes have an initial value. The following figure shows the initial values, as shipped by IBM, for the command keyword parameters:

    AUTOSTART     *NO
    POLLITV       60 minutes
    MINADJ        20 milliseconds
    MAXADJ        20 minutes
    ADJTHLD       *MAXADJ
    ACTLOG        *NONE
    SVRAUTOSTR    *NO
    SVRACTLOG     *NONE
    SYNCRQD       *NO

Restrictions:

• You must have input/output system configuration (*IOSYSCFG) special authority to run this command.

Parameters

Remote system (RMTSYS)

Specifies one or more remote systems to which the SNTP client can connect for the time service. The first parameter value in the list that can provide valid time service will be selected. When the selected time server fails, a new time server will be selected. The remote system name must be valid, and the system must be able to communicate with the local system. The user can assign names to an internet address with the Work with TCP/IP host table entries option on the Configure TCP/IP menu (CFGTCP command). Also, a remote name server can be used to map remote system names to internet addresses.

A list of public time servers is maintained on the Internet. You can use a search engine with a query of "NTP servers", or refer to the resources in the SNTP topic in the Information Center. The time server should be selected based on minimum network response time delay at the location where the system is installed. If a firewall is installed between the local system and the time server, the firewall configuration may need to be updated to allow the passing of UDP packets on port 123.

Single values

*SAME

The remote systems used for the time service do not change.

*NONE

No remote systems are to be used for the time service.

Other values (up to 3 repetitions)

character-value

Specify the host name or internet address of the NTP or SNTP time server system.

• An internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255.
• A host name can be either the short form or the full domain version of the name. A common practice is to define one short name that is unique within your local network and to also define the full domain version of the host name that is unique within the internet. A domain name or a host name can be a text string having 1 to 255 characters. Domain names consist of one or more labels separated by periods. Each label can contain up to 63 characters.

Client autostart (AUTOSTART)

Specifies whether to start the SNTP client automatically when TCP/IP is started using the Start TCP/IP (STRTCP) command, or by specifying SERVER(*AUTOSTART) on the Start TCP/IP Server (STRTCPSVR) command.

*SAME

The client autostart value does not change if it was previously set.

*NO

Do not automatically start the SNTP client. AUTOSTART(*NO) is the initial value.

*YES

Automatically start the SNTP client.

Client poll interval (POLLITV)

Specifies the time interval, in minutes, after which the SNTP client will connect to the NTP or SNTP time server in order to determine if the system clock needs correction.

*SAME

The polling interval does not change if it was previously set.

1-1440

Specify the number of minutes to use as the polling interval.

Client minimum adjustment (MINADJ)

The threshold, in milliseconds, between the NTP or SNTP server time and the local clock time. When the difference is below this value, the local clock will not be adjusted.

*SAME

The minimum adjustment does not change if it was previously set.

*NONE

The value is set to zero.

0-300000

Specify the number of milliseconds to use as the clock minimum adjustment threshold.

Client maximum adjustment (MAXADJ)

The threshold, in minutes, between the NTP or SNTP server time and the local clock time. When the difference is above this value, the local clock will not be set/adjusted.

*SAME

The maximum adjustment does not change if it was previously set.

1-120

Specify the number of minutes to use as the clock maximum adjustment threshold.

Client adjustment threshold (ADJTHLD)

Specifies the threshold which determines whether changing the clock will require setting or adjusting the clock.

• Setting the clock means replacing the current clock value with a new value. For instance replacing 12:47:56 (in hhmmss format where hh = hours, mm = minutes, ss = seconds) with the value 12:56:15 or 12:40:10. Setting the clock in this manner causes the clock to jump either forward or backward and can cause errors and unpredictable results if programs are accessing the clock time values before and after this setting of the clock. Setting of the clock requires full knowledge of the system environment. Otherwise unpredictable results can occur.
• Adjusting the clock means to incrementally speed up or slow down the clock so that time is gradually synchronized with the NTP or SNTP time server. Adjusting does not cause the large jumps in time that can be experienced with setting the clock. Adjusting does however take time to complete. For instance adjusting the clock by 1 second may take 10 seconds of wall clock time to complete. Note that this 10 second wall clock interval is just an example, the system determines how long the adjustment will actually take to complete. While adjusting of the clock is not as immediate as setting of the clock, it does avoid the problems associated with setting the clock while programs are accessing the clock time.

*SAME

The threshold does not change if it was previously set.

*MAXADJ

Adjusting of the clock will be done for all time differences up to the value specified for the Client maximum adjustment (MAXADJ) parameter.

1-7200

Specify the number of seconds between the NTP or SNTP time server and the SNTP client clock to be used as the threshold value. For time differences less than or equal to this value, an adjustment of the clock will be done. Otherwise a setting of the clock will be done.

Client activity log (ACTLOG)

Specifies the activities which cause logging for updating the clock to be done. Logging entries are written to a file in directory /QIBM/USERDATA/OS400/TCPIP/NTP for the client.

*SAME

The activity logging value does not change if it was previously set.

*NONE

No logging will be done. ACTLOG(*NONE) is the initial value.

*CHANGE

Logging will be done only when a change is made on the clock.

*POLL

Logging will occur every time the NTP or SNTP server sends a valid time value to the SNTP client. In addition, all *CHANGE activities will be logged.

Server autostart (SVRAUTOSTR)

Specifies whether to start the SNTP server automatically when TCP/IP is started by the Start TCP/IP (STRTCP) command or by specifying SERVER(*AUTOSTART) on the Start TCP/IP Server (STRTCPSVR) command.

*SAME

The server autostart value does not change if it was previously set.

*NO

Do not automatically start the SNTP server. SVRAUTOSTR(*NO) is the initial value.

*YES

Automatically start the SNTP server.

Server activity log (SVRACTLOG)

Specifies the activities which cause logging for the SNTP server. Logging entries are written to a file in directory /QIBM/USERDATA/OS400/TCPIP/NTP/SERVER.

*SAME

The activity logging value does not change if it was previously set.

*NONE

No logging will be done. SVRACTLOG(*NONE) is the initial value.

*ERROR

Logging will be done only when an error status is returned by the server.

*ALL

Logging will occur every time a request is made to the SNTP server.

Synchronization required (SYNCRQD)

Specifies whether the SNTP system client must be synchronized with an external time server before valid time will be served.

*SAME

The synchronization requirement value does not change if it was previously set.

*NO

No synchronization of the SNTP system client to an external time server is required.

*YES

The system clock must be synchronized by the SNTP client and adjustment of the system clock must be completed before valid time will be served. When the time difference between the time server and the system time is less than twice the MINADJ value or 100 milliseconds, whichever is greater, the clock is considered synchronized.

Examples

Example 1: Setting the SNTP Client

CHGNTPA RMTSYS(AAAA.BBBBB.CCC)

This command sets the SNTP client remote server hostname. AAAA.BBBBB.CCC.

Example 2: Setting Clock Time Adjustment Thresholds

CHGNTPA MINADJ(50) MAXADJ(10)

This command sets the client minimum adjustment threshold to 50 milliseconds and the maximum adjustment threshold to 10 minutes. If the time value returned from the NTP or SNTP server system is more than 50 milliseconds and less than 10 minutes different from the local clock, the local clock will be set/adjusted.

Example 3: Setting the Clock Set/Adjustment threshold

CHGNTPA ADJTHLD(2)

This command sets the SNTP client set/adjustment threshold value to 2 seconds. For time difference between the NTP or SNTP server and SNTP clock of 2 seconds or less, the clock will be adjusted. For time difference greater than 2 seconds, a set of the clock will be done.

Example 4: Setting the SNTP Server to Require Synchronized Client

CHGNTPA SYNCRQD(*YES)

This command sets the SNTP server to require the system clock to be synchronized by the SNTP client. If the SNTP system clock has not been synchronized, an unsynchronized response code will be returned by the SNTP server. An unsynchronized condition can be caused by inability of the SNTP client to contact the SNTP server, an error condition to prevent the SNTP client from updating the system clock, or the adjustment of the system clock has not been completed.

Example 5: Setting the SNTP Client using multiple servers

CHGNTPA RMTSYS(AAAA.BBBBB.CCC DDD.EEE.FFF GGG.HHH.III)

This command sets the SNTP client clock server to be host names AAAA.BBBBB.CCC, DDD.EEE.FFF, and GGG.HHH.III. If a valid time cannot be obtained from server AAAA.BBBBB.CCC, the SNTP client will attempt to contact server DDD.EEE.FFF followed by GGG.HHH.III.

Example 6: Setting the Set/Adjustment threshold

CHGNTPA SVRAUTOSTR(*YES)

This command sets the SNTP server to start automatically when the command STRTCP is issued.

Error messages

*ESCAPE Messages

CPF0011

Error detected by prompt override program.

TCP15A5

Error accessing member &3

TCP15A6

Attribute file keyword &4 missing

TCP1901

Internet address &2 not valid.

TCP1903

Specified host name not valid.

TCP264D

Error occurred processing file.

TCP8050

*IOSYSCFG authority required to use &1.

TCP9133

NTP attributes not changed.

TCP9155

System clock adjustment is not supported.

TCP9503

File &3 in library &2 not available.

TCP9999

Internal system error in program &1.