<contrib><ulinkurl="http://tldp.fsf.hu/HOWTO/TimePrecision-HOWTO-hu/index.html">Hungarian translation (magyar forditas)</ulink>, the chorny section and the very first section</contrib>
<sectionid="why"><title>Why do We Need a Precise Clock?</title>
<para>If our computer never connects to other computers (or other devices that use a clock), the precision of the clock is not critical itself, it depends on the need of the user. However, programs that some way use the net are dependent on a precise date and time. Some examples, when you may need precise clock:</para>
<itemizedlist>
<listitem><para>Softwares that deal with transactions</para></listitem>
<listitem><para>Websites that use cookies</para></listitem>
<listitem><para>Distributed web applications</para></listitem>
<listitem><para>Web services</para></listitem>
<listitem><para>Distributed component-based applications as <acronym>J2EE</acronym>, <acronym>.NET</acronym>, etc</para></listitem>
<listitem><para>Advanced modern and paralel filesystems, as AFS, DFS, GFS, GPFS, etc</para></listitem>
</itemizedlist>
<para>And of course, to use the computer to adjust our wristwatch clock.</para>
<sectionid="why.pcclock"><title>On What Factors Does the Hardware-Clock Depend?</title>
<para>Here we talk a little about the hardware-clock precision.</para>
<para>In PCs we find quartz-oscillators maintaining the hardware clock. The frequency of the oscillator is divided, and at the end we get a counter stepping once in one second (in reality it is more complicated, but now it's enough for us). The clock-oscillator runs even if the computer is switched off, so after starting the computer (and starting Linux) the hardware clock can give the values of the actual time. The stability of this clock is mostly dependent on the temperature of its surroundings, but it is also dependent on the air-pressure and the stability of the power supply voltage. The hardware clock is inaccurate in short term, however in the long term it shows a certain difference from the exact time. As we continously can compare the frequency of our hardware clock and an exact clock, we can calculate the frequency of the hardware clock and so to create the exact time. If this exact clock is inside your LAN (local area network), the accuracy of your Linux machine clock is within 0.01 sec. If you use the internet for this purpose, the accuracy of your clock will be within 0.2 sec regarding to the exact time.</para>
<para>For computers, there is also the hardware clock, which is used as a base by the OS to set its time.</para>
<para>OS date and time (we'll use only date <emphasis>or</emphasis> time from now on) is set on boot, by some script that reads the hardware clock, makes Time Zone calculations (there is no time zone data stored in <acronym>BIOS</acronym>) and sets the OS. After this synchronization, <acronym>BIOS</acronym> and OS time are independent from each other. So after a while they may have some seconds of difference. Which one is correct? If you don't make special configurations, none of them.</para>
<para>Time Zones are a geographical world globe division of 15<superscript>o</superscript> each, starting at Greenwich, in England, created to help people know what time is it now in another part of the world.</para>
<para>Nowadays it is much more a political division than geographical, because sometimes people needs to have the same time as other people in not-so-far locations. And for energy savings reasons, we have today the <linklinkend="tz.dst">Daylight Savings Time</link>, that are also a Time Zone variation.</para>
<para>Time Zones are usually defined by your country government or some astronomical institute, and is represented by 3 or 4 letters. See <xreflinkend="tz.examples"/> for examples.</para>
<para>For energy savings reasons, governments created the Daylight Savings Time. Our clocks are forwarded one hour, and this makes our days look longer. In fact, what really happens is only a Time Zone change. The primitive time (<acronym>UTC</acronym>) is still, and will allways be, the same.</para>
<para>Later we'll see how to enable and disable <acronym>DST</acronym> automatically in Linux.</para>
</section>
<sectionid="tz.examples"><title>Time Zones Examples</title>
<para>There is nothing better than examples:</para>
<tablepgwide="0"id="tz.ex.br"><title>Brazilian Time Zones. Shifts relative to <acronym>UTC</acronym></title>
<tgroupcols="3">
<thead>
<row>
<entry>Name and Shift</entry>
<entry><linklinkend="tz.dst"><acronym>DST</acronym></link> Name and Shift</entry>
<entry>Locations</entry>
</row>
</thead>
<tbody>
<row>
<entry>BREST -2:00</entry>
<entry>BREDT -1:00</entry>
<entry>Fernando de Noronha</entry>
</row>
<row>
<entry>BRST -3:00</entry>
<entry>BRDT -2:00</entry>
<entry>São Paulo, Rio, Brasilia, Minas Gerais, North East Region, South Region,etc</entry>
<sectionid="tz.linux"><title>Time Zone Mechanism on Linux</title>
<para>Linux systems uses the GLIBC dynamic Time Zones, based on <filename>/etc/localtime</filename>. This file is a link to (or a copy of) a zone information file, usually located under <filenameclass="directory">/usr/share/zoneinfo</filename> directory.</para>
<para>From a geophysical perspective, there is only 360<superscript>o</superscript>/15<superscript>o</superscript>=24 Time Zones in the world. But to make things easy to people, and to accommodate all the political variations (like Daylight Savings Time), you'll find hundreds of zoneinfo files in <filenameclass="directory">/usr/share/zoneinfo</filename>, each for every world city, country, etc.</para>
<para>Some countries, like Brazil, don't have a fixed day to start Daylight Savings Time. It is defined every year, a couple of months before summer, and you may end up in a situation you'll have to change your zoneinfo file, which was compiled by <command>zic</command> from a text file like this.</para>
<example><title>Brazilian Zone Info text file</title>
<para>The <command>Rule</command> block defines the date and time we change the Time Zone, while in the <command>Zone</command> block we reference the <command>Rule</command> will manage it. Note that the <command>Zone</command> name is actually the file name under <filenameclass="directory">/usr/share/zoneinfo</filename> directory, and here we defined several different names for the same Time Zone, just to be easyer for people to find their zone.</para>
<para>This file's comments explains how to install these time zones, using the <command>zic</command> zoneinfo compiler (which already installs them also). To make it effective, you only have to link (or copy) the zoneinfo file to <filename>/etc/localtime</filename>. In some distributions, there is a higher level (and preferred) way to set the Time Zone, described in <xreflinkend="set.tz"/>.</para>
<para>After making <filename>/etc/localtime</filename> pointing to the correct zoneinfo file, you are already under that zone rules and <acronym>DST</acronym> changes are automatic -- you don't have to change time manually.</para>
Fri Mar 29 20:14:03 <emphasis>BRST</emphasis> 2002</screen>
<para>At 20:13, I was in my default brazilian Time Zone (BRST), then I switched to GMT and my system time changed to 23:13! When your Time Zone enters DST, you'll see a similar effect, but the rules are all inside your Time Zone (<filename>/etc/localtime</filename> link doesn't change like this example).</para>
<para>An application running in this machine (eg. web-server generating access logs) will feel this change, so it is very important for developers to remember that the full Time Concept is the current <emphasis>time</emphasis> plus current <emphasis>Time Zone</emphasis>, as described in <xreflinkend="time"/>.</para>
<para>In the end, I switched back to my correct Time Zone.</para>
</section>
</section>
<sectionid="set"><title>The Correct Settings for Your Linux Box</title>
<para>For any OS installation, you must know your Time Zone. This is expressed in terms of a city, a state or a country. You must also decide how to set <acronym>BIOS</acronym> time, and we may follow two strategies here:</para>
<variablelist>
<varlistentry><term><emphasis>Linux Only Machine</emphasis></term>
<listitem>
<para>In this case you should set <acronym>BIOS</acronym> time to <acronym>UTC</acronym> time. <acronym>DST</acronym> changes will be dynamically managed by <linklinkend="tz.linux">Time Zone configurations</link>.</para>
</listitem>
</varlistentry>
<varlistentry><term><emphasis>Dual Boot Linux and MS Windows Machine</emphasis></term>
<listitem>
<para>Windows handles time in a more primitive way than Linux. For Windows, <acronym>BIOS</acronym> time is allways your local time, so <acronym>DST</acronym> changes are more aggressive because they directly change hardware clock. And since both Linux and Windows initially get and set time from the hardware, when they are together, Linux must handle it in the same way. So set <acronym>BIOS</acronym> time to your localtime.</para>
</listitem>
</varlistentry>
</variablelist>
<sectionid="set.tz"><title>Setting Time Zone</title>
<para>On Red Hat Linux and derived systems, you can set the hardware clock strategy and Time Zone using the <command>timeconfig</command> command, that shows a user-friendly dialog. You can also use it non-interactively:</para>
<example><title>Time Configuration Tool</title>
<screen><prompt>bash# </prompt><command>timeconfig "Brasil/East"</command> # set HC to localtime, and TZ to "Brazil/East"
<prompt>bash# </prompt><command>timeconfig --utc "Brasil/East"</command> # set HC to UTC, and TZ to "Brazil/East"</screen>
</example>
<para>Anyway, it changes <filename>/etc/sysconfig/clock</filename> file that is read at boot time. You can edit it by hand, and that is how it looks:</para>
<para>I encourage you to set your hardware clock only after understanding how to get accurate time, described on <xreflinkend="ntp"/>.</para>
<para>The <command>hwclock</command> command reads and sets the hardware clock, based on several options you give to it, documented in its man page. But you don't have to use it if you have a modern Linux distribution. After defining your hardware clock strategy and Time Zone, you can use the high level <command>setclock</command> command to correctly set your hardware clock. You don't need to pass any parameters because <command>setclock</command> intelligently calls <command>hwclock</command> to set the <acronym>BIOS</acronym> based on your OS current date and time. <emphasis>So you should always use the <command>setclock</command> command.</emphasis></para>
<para>Since the OS time is independent from the hardware clock, any <acronym>BIOS</acronym> change we make will take place in the next boot.</para>
<para>Another option to change HC is rebooting and accessing your computer <acronym>BIOS</acronym> screens. On <ulinkurl="http://ibm.com/servers/eserver/zseries/os/linux/">IBM e-server zSeries</ulink> platforms you'll have to do it on z/VM level, because Linux here runs on virtual machines created by z/VM.</para>
</section>
</section>
<sectionid="ntp"><title>Accurate Global Time Synchronization</title>
<para>To have accurate time in all your systems is as important as having a solid network security strategy (achieved by much more than simple firewall boxes). It is one of the primary components of a system administration based on good practices, which leads to organization and security. Specially when administering distributed applications, web-services, or even a distributed security monitoring tool, accurate time is a must.</para>
<para>We won't discuss here the protocol, but how this wonderful invention, added to the pervasivenes of the Internet, can be useful for us. You can find more about it at <ulinkurl="http://www.ntp.org/">www.ntp.org</ulink>.</para>
<para>Once your system is properly setup, <acronym>NTP</acronym> will manage to keep its time accurate, making very small adjustments to not impact the running applications.</para>
<para>People can get exact time using hardware based on atom's electrons frequency. There is also a method based on <acronym>GPS</acronym> (Global Positioning System). The first is more accurate, but the second is pretty good also. Atomic clocks require very special and expensive equipment, but their maintainers (usually universities and research labs) connect them to computers, that run an <acronym>NTP</acronym> daemon, and some of them are connected to the Internet, that finally let us access them for free. And this is how we'll synchronize our systems.</para>
<listitem><para>Choose some <acronym>NTP</acronym> servers. You can use the public server <ulinkurl="http://www.fortytwo.ch/time/">pool.ntp.org</ulink>, or choose some from the <ulinkurl="http://www.eecis.udel.edu/~mills/ntp/clock2a.html">stratum 2 public time servers</ulink> on <acronym>NTP</acronym> website. If you don't have an Internet access, your <acronym>WAN</acronym> administrator (must be a clever guy) can provide you some internal addresses.</para></listitem>
<listitem><para>Have the <acronym>NTP</acronym> package installed in all systems you want to synchronize. You can find RPMs in your favorite Linux distribution CD, or <ulinkurl="http://rpmfind.net/linux/rpm2html/search.php?query=ntp">make a search</ulink> on <ulinkurl="http://rpmfind.net/">rpmfind.net</ulink>.</para></listitem>
</orderedlist>
<para>Here is an example of good architecture:</para>
<figure><title>Local Relay Servers for NTP</title>
<para>If you have several machines to synchronize, <emphasis>do not</emphasis> make them all access the remote <acronym>NTP</acronym> servers you chose. Only 2 of your server farm's machines must access remote <acronym>NTP</acronym> servers, and the other machines will sync with these 2. We will call them the <emphasis>Relay Servers</emphasis>.</para>
<para>Your Relay Servers can be any machine already available in your network. <acronym>NTP</acronym> consumes low memory and CPU. You don't need a dedicated machine for it.</para>
<tip><para>It is a good idea to create hostname aliases for your local Relay Servers like ntp1.my.com and ntp2.my.com, and use only these names when configuring the client machines. This way you can move the <acronym>NTP</acronym> functionality to a new Relay Server (with a different IP and hostname), without having to reconfigure the clients. Ask your <acronym>DNS</acronym> administrator to create such aliases.</para></tip>
<para>Again, you can use the public server <ulinkurl="http://www.fortytwo.ch/time/">pool.ntp.org</ulink>, or get a list of <ulinkurl="http://www.eecis.udel.edu/~mills/ntp/clock2a.html">public stratum 2 time servers</ulink> from <acronym>NTP</acronym> website.</para>
<para>If your machine has a UTC time difference bigger than some minutes comparing to the <acronym>NTP</acronym> servers, <acronym>NTP</acronym> will not work. So you must do a first full sync, and I recommend you to do it in a non-production hour. You need to do it only when you are making the initial <acronym>NTP</acronym> setup. Never more:</para>
<para>Now you have everything setup. <acronym>NTP</acronym> will softly keep your machine time synchronized. You can watch this process using the NTP Query (<command>ntpq</command> command):</para>
<para>Is the name of the remote <acronym>NTP</acronym> server. If you use the <option>-n</option> switch, you will see the IP addresses of these servers instead of their hostnames.</para>
<para>Indicates where each server is getting its time right now. It can be a server hostname or something like <acronym>.GPS.</acronym>, indicating a Global Positioning System source.</para>
<para><emphasis>Stratum</emphasis> is a number from 1 to 16, to indicate the remote server precision. 1 is the most accurate, 16 means 'server unreachable'. Your Stratum will be equal to the accurate remote server plus 1. Never connect to a Stratum 1 server, use Stratum 2 servers! Stratum 2 servers are also good for our purposes, and this policy is good for reducing the traffic to the Stratum 1 servers.</para>
<para>The polling interval (in seconds) between time requests. The value will range between the minimum and maximum allowed polling values. Initially the value will be smaller to allow synchronization to occur quickly. After the clocks are 'in sync' the polling value will increase to reduce network traffic and load on popular time servers.</para>
<para>This is an octal representation of an array of 8 bits, representing the last 8 times the local machine tried to reach the server. The bit is set if the remote server was reached.</para>
<para>The most important value. The difference of time between the local and remote server. In the course of synchronization, the offset time lowers down, indicating that the local machine time is getting more accurate.</para>
<para>Dispersion, also called Jitter, is a measure of the statistical variance of the offset across several successive request/response pairs. Lower dispersion values are preferred over higher dispersion values. Lower dispersions allow more accurate time synchronization.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist><title>The meaning of the signs before server hostname</title>
<varlistentry><term><emphasis>-</emphasis></term>
<listitem>
<para>Means the local NTP service doesn't like this server very much</para>
</listitem>
</varlistentry>
<varlistentry><term><emphasis>+</emphasis></term>
<listitem>
<para>Means the local NTP service likes this server</para>
<para>If your machine is up and running for a long time (months, years) without rebooting, you'll find a big discrepancy between the inaccurate hardware clock and the (now very accurate) system time. Modern Linux distributions copy OS time to the HC everytime the system is shutdown, using a <linklinkend="set.hwclock">mechanism similar to the <command>setclock</command> command</link>. This way, in the next OS boot, you'll get date and time almost as accurate as it was when you shutdown the machine.</para>
</section>
</section>
<sectionid="ntp.chrony"><title>Precise Time with the <command>chrony</command> Program</title>
<sectionid="ntp.chrony.diff"><title>How <command>chrony</command> Differs from the <command>ntp</command> Suite?</title>
<para><command>chrony</command> also uses the <acronym>NTP</acronym> protocol, and is also designed to make Linux clock more accurate. It is also suitable for systems that do not have an Internet connection. Then the source of the exact time can be any accurate clock, from which we can read the time and type it to the program. In addition, it is also capable of calculating the inaccuracy of the hardware clock, and based on that, adjust the hardware clock at boot time.</para>
<para><command>chrony</command> 1.20 does not support built-in hardware clocks like GPS and DCF receivers, but the structure of the program makes such development possible.</para>
</section>
<sectionid="ntp.chrony.how"><title>How to Use <command>chrony</command>?</title>
<para><command>chrony</command> consists of two parts: <command>chronyd</command> daemon and a user interface <command>chronyc</command>.</para>
<para>You can find <command>chrony</command> at <ulinkurl="http://chrony.sunsite.dk/index.php/">chrony.sunsite.dk/index.php</ulink></para>
<para>This document must be distributed under the terms of <ulinkurl="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation License</ulink>. Please translate, adapt, improve, redistribute using the original XML DocBook source right bellow. Let me know if you want me to put a link to your translation/adaptation/improvement here.</para>
<listitem><para><ulinkurl="http://en.tldp.org/HOWTO/TimePrecision-HOWTO/">TLDP, as a HOWTO</ulink> [<ulinkurl="http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/TimePrecision-HOWTO.html">single page</ulink>] [<ulinkurl="http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/TimePrecision-HOWTO.pdf">PDF</ulink>]</para></listitem>
<listitem><para>SHAKI <sha-ki at narod.ru><ulinkurl="http://computerlib.narod.ru/html/linuxtime.htm">russian translation</ulink></para></listitem>
<listitem><para>Kemal Ökmen <kemal AT comu edu tr><ulinkurl="http://www.belgeler.org/howto/time-precision-howto.html">Turkish translation - Türkçe çeviri</ulink></para></listitem>
<para>When translating, feel free to change all brazilian-related configuration examples to your country's. And please send me an e-mail containing the translator's name, e-mail address, the language that this doc was translated to, the phrase "[YOUR LANGUAGE] translation" in your language, all UTF-8 encoded. This way I can put, in the original document, in your language, a link to your translation. Also, please let the <ulinkurl="http://tldp.org">TLDP</ulink> folks be aware of your translation, so they can add it to the collection of HOWTOs in your language.</para>