If you are using the current version of Cumulus Linux, the content on this page may not be up to date. The current version of the documentation is available
here. If you are redirected to the main page of the user guide, then this page may have been renamed; please search for it there.

Setting Date and Time

Setting the time zone, date and time requires root privileges; use sudo.

Setting the Time Zone

To see the current time zone, list the contents of /etc/timezone:

cumulus@switch:~$ cat /etc/timezone
US/Eastern

Edit the file to add your desired time zone. A list of valid time zones
can be found at the following
link.

Setting the Date and Time

The switch contains a battery backed hardware clock that maintains the
time while the switch is powered off and in between reboots. When the
switch is running, the Cumulus Linux operating system maintains its own
software clock.

During boot up, the time from the hardware clock is copied into the
operating system’s software clock. The software clock is then used for
all timekeeping responsibilities. During system shutdown, the software
clock is copied back to the battery backed hardware clock.

You can set the date and time on the software clock using the date
command. First, determine your current time zone:

cumulus@switch$ date +%Z

If you need to reconfigure the current time zone, refer to the
instructions above.

Then, to set the system clock according to the time zone configured:

cumulus@switch$ sudo date -s "Tue Jan 12 00:37:13 2016"

See man date(1) for more information.

You can write the current value of the system (software) clock to the
hardware clock using the hwclock command:

Setting Time Using NTP and NCLU

The ntpd daemon running on the switch implements the NTP protocol. It
synchronizes the system time with time servers listed in
/etc/ntp.conf. The ntpd daemon is started at boot by default. See
man ntpd(8) for ntpd details. You can check this
site for an
explanation of the output.

By default, /etc/ntp.conf contains some default time servers. You can
specify the NTP server or servers you want to use with
NCLU;
include the iburst option to increase the sync speed.

To set the initial date and time via NTP before starting the ntpd
daemon, use ntpd -q. This is the same as ntpdate, which is to be
retired and no longer available. See man ntp.conf(5) for details on
configuring ntpd using ntp.conf.

These commands create the following configuration snippet in the
ntp.conf file:

...
# Specify interfaces
interface listen swp10
...

NTP Default Configuration

The default NTP configuration comprises the following servers, which are
listed in the /etc/ntpd.conf file:

server 0.cumulusnetworks.pool.ntp.org iburst

server 1.cumulusnetworks.pool.ntp.org iburst

server 2.cumulusnetworks.pool.ntp.org iburst

server 3.cumulusnetworks.pool.ntp.org iburst

The contents of the /etc/ntpd.conf file are listed below.

Default ntpd.conf file ...

# /etc/ntp.conf, configuration for ntpd; see ntp.conf(5) for help
driftfile /var/lib/ntp/ntp.drift
# Enable this if you want statistics to be logged.
#statsdir /var/log/ntpstats/
statistics loopstats peerstats clockstats
filegen loopstats file loopstats type day enable
filegen peerstats file peerstats type day enable
filegen clockstats file clockstats type day enable
# You do need to talk to an NTP server or two (or three).
#server ntp.your-provider.example
# pool.ntp.org maps to about 1000 low-stratum NTP servers. Your server will
# pick a different set every time it starts up. Please consider joining the
# pool: <http://www.pool.ntp.org/join.html>
server 0.cumulusnetworks.pool.ntp.org iburst
server 1.cumulusnetworks.pool.ntp.org iburst
server 2.cumulusnetworks.pool.ntp.org iburst
server 3.cumulusnetworks.pool.ntp.org iburst
# Access control configuration; see /usr/share/doc/ntp-doc/html/accopt.html for
# details. The web page <http://support.ntp.org/bin/view/Support/AccessRestrictions>
# might also be helpful.
#
# Note that "restrict" applies to both servers and clients, so a configuration
# that might be intended to block requests from certain clients could also end
# up blocking replies from your own upstream servers.
# By default, exchange time with everybody, but don't allow configuration.
restrict -4 default kod notrap nomodify nopeer noquery
restrict -6 default kod notrap nomodify nopeer noquery
# Local users may interrogate the ntp server more closely.
restrict 127.0.0.1
restrict ::1
# Clients from this (example!) subnet have unlimited access, but only if
# cryptographically authenticated.
#restrict 192.168.123.0 mask 255.255.255.0 notrust
# If you want to provide time to your local subnet, change the next line.
# (Again, the address is an example only.)
#broadcast 192.168.123.255
# If you want to listen to time broadcasts on your local subnet, de-comment the
# next lines. Please do this only if you trust everybody on the network!
#disable auth
#broadcastclient
# Specify interfaces, don't listen on switch ports
interface listen eth0

Precision Time Protocol (PTP) Boundary Clock

With the growth of low latency and high performance applications,
precision timing has become increasingly important. Precision Time
Protocol (PTP) is used to synchronize clocks in a network and is capable
of sub-microsecond accuracy. The clocks are organized in a master-slave
hierarchy. The slaves are synchronized to their masters, which can be
slaves to their own masters. The hierarchy is created and updated
automatically by the best master clock (BMC) algorithm, which runs on
every clock. The grandmaster clock is the top-level master and is
typically synchronized by using a Global Positioning System (GPS) time
source to provide a high-degree of accuracy.

A boundary clock has multiple ports; one or more master ports and one or
more slave ports. The master ports provide time (the time can originate
from other masters further up the hierarchy) and the slave ports receive
time. The boundary clock absorbs sync messages in the slave port, uses
that port to set its clock, then generates new sync messages from this
clock out of all of its master ports.

Cumulus Linux includes the linuxptp package for PTP, which uses the
phc2sys daemon to synchronize the PTP clock with the system clock.

If you do not perform a binary (full image) install of Cumulus Linux
3.6, you need to install the linuxptp package with the apt-get install linuxptp command.

PTP is supported in boundary clock mode only (the switch provides
timing to downstream servers; it is a slave to a higher-level clock
and a master to downstream clocks).

The switch uses hardware time stamping to capture timestamps from an
Ethernet frame at the physical layer. This allows PTP to account for
delays in message transfer and greatly improves the accuracy of time
synchronization.

Only IPv4/UDP PTP packets are supported.

Only a single PTP domain per network is supported. A PTP domain is a
network or a portion of a network within which all the clocks are
synchronized.

In the following example, boundary clock 2 receives time from Master 1
(the grandmaster) on a PTP slave port, sets its clock and passes the
time down from the PTP master port to boundary clock 1. Boundary clock 1
receives the time on a PTP slave port, sets its clock and passes the
time down the hierarchy through the PTP master ports to the hosts that
receive the time.

Enabling the PTP Boundary Clock on the Switch

To enable the PTP boundary clock on the switch:

Open the /etc/cumulus/switchd.conf file in a text editor and add
the following line:

ptp.timestamping = TRUE

Restart switchd:

cumulus@switch:~$ sudo systemctl restart switchd.service

Configuring the PTP Boundary Clock

To configure a boundary clock:

Configure the interfaces on the switch that you want to use for PTP.
Each interface must be configured as a layer 3 routed interface with
an IP address.

Set the gm-capable option to no to configure the switch to
be a boundary clock.

Set the priority, which selects the best master clock. You can
set priority 1 or 2. For each priority, you can use a number
between 0 and 255. The default priority is 255. For the boundary
clock, use a number above 128. The lower priority is applied
first.

Add the time-stamping parameter. The switch automatically
enables hardware time-stamping to capture timestamps from an
Ethernet frame at the physical layer. If you are testing PTP in
a virtual environment, hardware time-stamping is not available;
however the time-stamping parameter is still required.

Add the PTP master and slave interfaces. You do not specify
which is a master interface and which is a slave interface; this
is determined by the PTP packet received.

Example Configuration

In the following example, the boundary clock on the switch receives time
from Master 1 (the grandmaster) on PTP slave port swp3s0, sets its clock
and passes the time down through PTP master ports swp3s1, swp3s2, and
swp3s3 to the hosts that receive the time.

The configuration for the above example is shown below. The example
assumes that you have already configured the layer 3 routed interfaces
(swp3s0, swp3s1, swp3s2, and swp3s3) you want to use for PTP.

Using NTP in a DHCP Environment

If you use DHCP and want to specify your NTP servers, you must specify
an alternate configuration file for NTP.

Before you create the file, ensure that the DHCP-generated configuration
file exists. In Cumulus Linux 3.6.1 and later (which uses NTP 1:4.2.8),
the DHCP-generated file is named /run/ntp.conf.dhcp while in Cumulus
Linux 3.6.0 and earlier (which uses NTP 1:4.2.6) the file is named
/var/lib/ntp/ntp.conf.dhcp. This file is generated by the
/etc/dhcp/dhclient-exit-hooks.d/ntp script and is a copy of the
default /etc/ntp.conf with a modified server list from the DHCP
server. If this file does not exist and you plan on using DHCP in the
future, you can copy your current /etc/ntp.conf file to the location
of the DHCP file.

To use an alternate configuration file that persists across upgrades of
Cumulus Linux, create a systemd unit override file called
/etc/systemd/system/ntp.service.d/config.conf and add the following
content: