repo_zf1/documentation/manual/en/module_specs/Zend_TimeSync.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.timesync.introduction">
    <title>Introduction</title>

    <para>
        <classname>Zend_TimeSync</classname> is able to receive internet or network time from a time
        server using the <emphasis>NTP</emphasis> or <emphasis>SNTP</emphasis> protocol.
        With <classname>Zend_TimeSync</classname>, Zend Framework is able to act independently from
        the time settings of the server where it is running.
    </para>

    <para>
        To be independent from the actual time of the server, <classname>Zend_TimeSync</classname>
        works with the difference of the real time which is sent through NTP or SNTP and the
        internal server's time.
    </para>

    <note>
        <title>Background</title>

        <para>
            <classname>Zend_TimeSync</classname> is not able to change the server's time, but it
            will return a <link linkend="zend.date.introduction">Zend_Date</link> instance from
            which the difference from the server's time can be worked with.
        </para>
    </note>

    <sect2 id="zend.timesync.introduction.why">
        <title>Why Zend_TimeSync ?</title>

        <para>
            So why would someone use <classname>Zend_TimeSync</classname> ?
        </para>

        <para>
            Normally every server within a multi-server farm will have a service running which
            synchronizes its own time with a time server. So within a standard environment it should
            not be necessary to use <classname>Zend_TimeSync</classname>. But it can become handy if
            there is no service available and if you don't have the right to install such a service.
        </para>

        <para>
            Here are some example use cases, for which <classname>Zend_TimeSync</classname> is
            perfect suited:
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    <emphasis>Server without time service</emphasis>
                </para>

                <para>
                    If your application is running on a server and this server does not have any
                    time service running, it may make sense to use
                    <classname>Zend_TimeSync</classname> in your application.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Separate database server</emphasis>
                </para>

                <para>
                    If your database is running on a different server and this server is not
                    connected with <emphasis>NTP</emphasis> or <emphasis>SNTP</emphasis>
                    to the application server, you might have problems using storing and using time
                    stamp data.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Multiple servers</emphasis>
                </para>

                <para>
                    If your application is running on more than one server and these servers' time
                    bases are not syncronized, you can expect problems within your application when
                    part of the application is coming from one server and another part from another
                    server.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Batch processing</emphasis>
                </para>

                <para>
                    If you want to work with a time service within a batch file or within a
                    command line application, <classname>Zend_TimeSync</classname> may be of use.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <classname>Zend_TimeSync</classname> may provide a good solution in all of these cases
            and can be used if you are unable to run any services on your server.
        </para>
    </sect2>

    <sect2 id="zend.timesync.introduction.ntp">
        <title>What is NTP ?</title>

        <para>
            The Network Time Protocol (<emphasis>NTP</emphasis>) is a protocol
            for synchronizing multiple systems' clocks over packet-switched, variable-latency data
            networks. NTP uses UDP port 123 as its transport layer. See the <ulink
                url="http://en.wikipedia.org/wiki/Network_Time_Protocol">wikipedia article</ulink>
            for details about this protocol.
        </para>
    </sect2>

    <sect2 id="zend.timesync.introduction.sntp">
        <title>What is SNTP?</title>

        <para>
            The Simple Network Time Protocol (<emphasis>SNTP</emphasis>) is a
            protocol synchronizing multiple systems' clocks over packet-switched, variable-latency
            data networks. SNTP uses UDP port 37 as its transport layer. It is closely related to
            the Network Time Protocol, but simpler.
        </para>
    </sect2>

    <sect2 id="zend.timesync.introduction.problematic">
        <title>Problematic usage</title>

        <para>
            Be warned that when you are using <classname>Zend_TimeSync</classname> you will have to
            think about some details related to the structure of time sync and the internet itself.
            Correct usage and best practices will be described here. Read carefully before you begin
            using <classname>Zend_TimeSync</classname>.
        </para>
    </sect2>

    <sect2 id="zend.timesync.introduction.decision">
        <title>Decide which server to use</title>

        <para>
            You should select the time server that you want to use very carefully according to the
            following criteria:
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    Distance
                </para>

                <para>
                    The distance from your application server to the time server. If your server is
                    in Europe, it would make little sense to select a time server in Tahiti. Always
                    select a server which is not far away. This reduces the request time and overall
                    network load.
                </para>
            </listitem>

            <listitem>
                <para>
                    Speed
                </para>

                <para>
                    How long it takes to receive the request is also relevant. Try different servers
                    to get the best result. If you are requesting a server which is never
                    accessible, you will always have an unnecessary delay.
                </para>
            </listitem>

            <listitem>
                <para>
                    Splitting
                </para>

                <para>
                    Do not always use the same server. All time servers will lock out requests from
                    servers that are flooding the server. If your application requires heavy use of
                    time servers, you should consider one of the pools described later.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            So where can you find a time server? Generally you can use any timeserver you can
            connect to. This can be a time server within your LAN or any public time server you have
            access to. If you decide to use a public time server, you should consider using a server
            pool. Server pools are public addresses from which you will get a random, pooled time
            server by requesting the time. This way you will not have to split your requests. There
            are public server pools available for many regions which you may use to avoid problems
            mentioned above.
        </para>

        <para>
            See <ulink url="http://www.pool.ntp.org">pool.ntp.org</ulink> to find your nearest
            server pool. For example, if your server is located within Germany you can connect to
            <emphasis>0.europe.pool.ntp.org</emphasis>.
        </para>
    </sect2>
</sect1>