socheatsok78/chrony repository overview

⁠About

Just another container image for running NTP Server using chrony with support for Linux capabilities using SYS_TIME & IPC_LOCK.

This container runs chrony⁠ on Alpine Linux⁠.

Source⁠ | Docker Hub⁠ | GitHub Container Registry⁠

⁠What is Chrony?

chrony⁠ is a versatile implementation of the Network Time Protocol (NTP). It can synchronise the system clock with NTP servers, reference clocks (e.g. GPS receiver), and manual input using wristwatch and keyboard. It can also operate as an NTPv4 (RFC 5905) server and peer to provide a time service to other computers in the network.

⁠Image

Following platforms for this image are available:

$ docker run --rm mplatform/mquery socheatsok78/chrony:latest

# Image: socheatsok78/chrony:latest
#  * Manifest List: Yes (Image type: application/vnd.oci.image.index.v1+json)
#  * Supported platforms:
#    - linux/amd64
#    - linux/arm64

⁠Releases

The release versioning scheme is based on Alpine releases, and it will follow the same versioning as the base image. The build matrix is generated using actions-matrix/alpine-matrix-action⁠ action.

Currently, the following versions are available:

• latest
• edge
• 3.20
• 3.19

⁠Usage

docker run --name=chrony \
    --publish=123:123/udp \
    --cap-add=SYS_TIME \
    --cap-add=IPC_LOCK \
  socheatsok78/chrony:3.20

# Deploy to a Docker Swarm cluster
docker service create --name=chrony \
    --publish=123:123/udp \
    --cap-add=SYS_TIME \
    --cap-add=IPC_LOCK \
    --mode=global \
  socheatsok78/chrony:3.20

⁠Configure Chrony

You can configure chrony by setting the following environment variables:

⁠Configure NTP Servers

By default, the container will use DEFAULT_NTP_POOL_ADDR environment variable to set the default NTP server. You can set this environment variable to the NTP server you want to use.

Alternatively, If you want to use multiple of other different NTP servers, you can set the following environment variables:

• NTP_SERVER_COUNT: Number of NTP servers to use. (Default unset)
• NTP_SERVER_#_ADDR: NTP Server # address. (Required, if NTP_SERVER_COUNT > 0)
• NTP_SERVER_#_NTS: Enable NTS (Network Time Security) for NTP Server #. (Optional, can be true or false)

⁠Chronyd Options

• LOGLEVEL: Log level. Default: 0 The following levels can to specified: 0 (informational), 1 (warning), 2 (non-fatal error), and 3 (fatal error)
• NOCLIENTLOG: This option disables logging of client requests and responses. Default: false

  Specifies that client accesses are not to be logged. Normally they are logged, allowing statistics to be reported using the clients command in chronyc. This option also effectively disables server support for the NTP interleaved mode.

⁠Advanced Configurations

Some advanced configurations are not documented here, please take a look at the following files:

• rootfs/etc/s6-overlay/scripts/chronyd-init⁠
• rootfs/etc/s6-overlay/s6-rc.d/chronyd/run⁠

⁠NTP Pool Project

By default, this container will syncronize time from pool.ntp.org provided by the NTP Pool Project⁠. You can change the default NTP server by setting the DEFAULT_NTP_POOL_ADDR environment variable.

By using NTP Pool Project, chances are you will connect to server raning from Stratum 1 to Stratum 4 servers depending on your location.

⁠Public NTP Servers

Other NTP Servers:

⁠Monitoring

The metrics are served by SuperQ/chrony_exporter⁠, available at /metrics on 9123 port. e.g. http://localhost:9123/metrics

There is also a dashboard available for Grafana here⁠.

⁠Container Capabilities

The container can be configured to perform the following actions, and all of them are optional features.

⁠Set the capability to update system time

With SYS_TIME capability, this allows the container to update the system time. By default, this capability is not set. Once the --cap-add SYS_TIME provided to the container, chrony will be able to update the system time if necessary.

You can disable this feature by setting the SKIP_SETCAP_SYS_TIME environment variable to true.

⁠Set the capability to lock memory

With IPC_LOCK capability, this allows the container to lock memory. By default, this capability is not set. Once the --cap-add IPC_LOCK provided to the container, chrony will be able to lock memory and prevent it from being swapped out.

You can disable this feature by setting the SKIP_SETCAP_IPC_LOCK environment variable to true.

⁠Important Notes

You may need to disable the host Automatic Date & Time setting to prevent the host from syncing time with the NTP server, instead, let the container handle the time sync.

Here an example of how to disable the Automatic Date & Time setting on Ubuntu:

# Check the NTP service status
timedatectl status

# Disable the NTP service
sudo timedatectl set-ntp 0

# Enable the NTP service
sudo timedatectl set-ntp 1

⁠License

Licensed under the GNU General Public License v3.0. See LICENSE⁠ for more information.