Setting the System Time

TODO: {{#todo:Reviewed by MD: Add section about shutting down ntpd if needed|Klint Youngmeyer|oe 4,oe 5,ky,Review,FinalDraft}}

There are two different clocks on a Linux system. The RTC, or hardware clock, is present on most systems and is used to provide a persistent clock using a battery backup and for other purposes like waking the processor up from suspend mode via an alarm interrupt. The hardware clock is generally only accessed to retrieve an initial time when Linux boots and is rarely accessed from a running system. The system clock is implemented in the kernel and is used for timekeeping purposes for the running system. On Linux, time is represented by the number of seconds after the Unix epoch: 00:00:00 UTC on January 1, 1970.

Setting the System Time on EMAC OE Products

Before setting the system time, you must use the following command to ensure that ntpd is not running.

root@emac-oe:~# ps | grep ntpd

ntp     25066     1  0  9958  2260   2 Oct08 ?        00:00:07 /usr/sbin/ntpd -p /var/run/ntpd.pid -g -u 117:126
user    28441 13218  0  3397   920   0 17:48 pts/14   00:00:00 grep --color=auto ntpd

root@emac-oe:~#

If ntpd is not running, please continue to the section: Updating The Clock. If ntpd is running, as shown in the above command output, you will have to shut down the process before updating the clock and restart it afterwards. To shut down the ntpd process, run the following command:

root@emac-oe:~# /etc/init.d/ntp stop

After you have updated the clock using the instructions in the next section, run the following command to restart the ntpd process:

root@emac-oe:~# /etc/init.d/ntp start

You can also view a list of servers in use by ntpd by running the command:

root@emac-oe:~# ntpq -q

Updating The Clock

During boot, they system will call the program ntpdate to set the time from an NTP server. This requires that the device has Internet access. To do this manually run the following command:

root@emac-oe:~# ntpdate pool.ntp.org

The example above uses the server pool.ntp.org which will retrieve a randomly chosen public NTP server. However, the choice of time server is arbitrary and can be set according to the users' needs. If the device does not have Internet access, then the system date can be set using the following command:

root@emac-oe:~# date -s "<date_format>"

The argument <date_format> can be any of the following:

"hh:mm[:ss]"
"[YYYY.]MM.DD-hh:mm[:ss]"
"YYYY-MM-DD hh:mm[:ss]"
"MMDDhhmm[[YY]YY][.ss]"

hh = hour
mm = minute
ss = second
YYYY = four-digit year
MM = month
DD = day
[YY]YY = four-digit year where the first two digits are optional

On shutdown the system time is saved to the hardware clock automatically with the following command:

/etc/init.d/hwclock.sh stop

To do this manually after setting the date run the following command:

/etc/init.d/hwclock.sh restart

Hardware Clock

The hardware clock can be accessed through the hwclock command. Running hwclock with no arguments prints the current value stored in the hardware clock. The --systohc option sets the value of the hardware clock using the system clock. This command is called by the system shutdown scripts using /etc/init.d/hwclock.sh. The --hctosys option can be used to set the system clock using the value stored in the hardware clock. This is used by /etc/init.d/hwclock.sh to initialize the system clock during the boot process. Note that the hardware clock is generally set to UTC regardless of the local timezone. On system shutdown, the current system time is saved to the RTC using the /etc/init.d/save-rtc.sh script.

The system can be configured to use either local time (see Local Timezone) or UTC for the hardware clock. Although the hardware clock only holds an absolute time value and no timezone value, adjustments can be made to account for the timezone when reading and setting the clocks. By default, EMAC OE uses the local time value for the hardware clock. If UTC is used for the system clock, or NTP or another method is used to synchronize the clocks, this will not cause an issue. However, if the hardware clock is the primary method used to initialize the system clock, there will be no way to automatically adjust for Daylight Saving Time changes that occur while the system is off. In these cases, it is best to keep the hardware clock in UTC. This can be done easily by adding the line UTC=yes to /etc/default/rcS. Doing so will cause the /etc/init.d/hwclock.sh script to pass the utc option to the hwclock command when setting the hardware clock and when using it to set the system clock. The following example illustrates how the utc option allows the system to automatically account for the timezone when setting and reading the clocks:

root@emac-oe:~# date

Tue Oct 18 10:34:44 CDT 2011

root@emac-oe:~# hwclock --utc --systohc
root@emac-oe:~# hwclock

Tue Oct 18 15:34:53 2011  0.000000 seconds

root@emac-oe:~# hwclock --utc

Tue Oct 18 10:34:58 2011  0.000000 seconds

root@emac-oe:~# hwclock --utc --hctosys
root@emac-oe:~# date

Tue Oct 18 10:35:07 CDT 2011

root@emac-oe:~#

Local Timezone

By default, EMAC OE systems are set to UTC timezone. Setting the timezone is done by creating a link from /etc/localtime to the desired timezone information file. The most common timezones are installed in the base image; contact EMAC for additional timezone definitions if required. Timezone information files are stored in the /usr/share/zoneinfo directory. For example, for Central Standard Time (CST), the file /usr/share/zoneinfo/America/Chicago or /usr/share/zoneinfo/CST6CDT would be used. This will also allow the system to automatically adjust for Daylight Savings Time.

The example below illustrates the process of setting the timezone. Notice that it is necessary to log out and log back in for the new timezone setting to take effect. The command below that actually sets the timezone is ln -s /usr/share/zoneinfo/America/Chicago /etc/localtime:

root@emac-oe:~# hwclock

Thu Feb  4 22:54:48 2010  0.000000 seconds

root@emac-oe:~# date

Thu Feb  4 22:54:49 UTC 2010

root@emac-oe:~# rm -rf /etc/localtime ### <--- only necessary if this file exists ###
root@emac-oe:~# ### The following line sets the timezone by creating the needed symbolic link: ###
root@emac-oe:~# ln -s /usr/share/zoneinfo/America/Chicago /etc/localtime
root@emac-oe:~# ### The following line shows the symbolic link that was created to set the timezone ###
root@emac-oe:~# ls -l /etc/localtime

lrwxrwxrwx    1 root     root           35 Feb  4 22:55 /etc/localtime -> /usr/share/zoneinfo/America/Chicago

root@emac-oe:~# date

Thu Feb  4 22:55:46 UTC 2010

root@emac-oe:~# logout

....
emac-oe login: root
Password:

root@emac-oe:~# date

Thu Feb  4 16:56:05 CST 2010

root@emac-oe:~# hwclock

Thu Feb  4 22:56:08 2010  0.000000 seconds

root@emac-oe:~#