<!-- $Id: Timestamps.html,v 1.4 2007/06/28 17:41:29 castaglia Exp $ -->
<!-- $Source: /cvsroot/proftp/proftpd/doc/howto/Timestamps.html,v $ -->
<html>
<head>
<title>ProFTPD mini-HOWTO - ProFTPD and Timestamps</title>
</head>
<body bgcolor=white>
<hr>
<center><h2><b>ProFTPD and Timestamps</b></h2></center>
<hr>
<p>
There have been various reports that timestamps displayed in various
ProFTPD log files, such as an <code>ExtendedLog</code> or
<code>TransferLog</code>, or even in directory listings, are not as expected.
Other applications (<i>e.g.</i> <code>sshd</code>) on the same machine do
not exhibit the same problem. So is <code>proftpd</code> having issues
with timestamps?
<p>
Depending on the logs at which you are looking, the timestamps will be correct
<i>until</i> the user logs in. After that, the timestamps are wrong. This
is one clue. The other clue is that these wrong timestamps go away when
the <code>DefaultRoot</code> directive is removed from the
<code>proftpd.conf</code> file.
<p>
The answer turns out to be the <code>chroot(2)</code> system call, which
<code>proftpd</code> uses to restrict users to certain directories, usually
their home directory. There are two configuration directives which tell
<code>proftpd</code> to use the <code>chroot(2)</code> system call:
<pre>
<Anonymous>
DefaultRoot
</pre>
The system <code>libc</code> library is responsible for generating times,
based on timezone settings and such. The GNU libc library (called
<code>glibc</code> for short), used on all Linux systems changed in later
versions, and now makes some assumptions. Specifically, <code>glibc</code>
assumes the location of the system timezone files. But once a process
has been chrooted, those assumptions break. The fallback behavior of
<code>glibc</code>, when it cannot find the system timezone files, is to
use GMT.
<p>
The good news is that the above behavior does <b>not</b> happen if the
<code>TZ</code> environment variable is set explicitly, to the required
timezone. That is, if <code>glibc</code> needs to detect the timezone and
it finds that <code>TZ</code> is set, then <code>glibc</code> will use that
<code>TZ</code> setting, rather than falling back to GMT.
<p>
<b>Affected Library Functions</b><br>
Once a process has chrooted, the following <code>libc</code> function
calls will have possibly-bad side effects, with regard to timezone detection:
<code>localtime(3)</code>, <code>ctime(3)</code>, and <code>mktime(3)</code>.
As documented in the man pages for these functions, each of them will
set the <code>tzname</code> global variable to the "current"
timezone. This "current" timezone is what changes, once the
process has become chrooted. (For more information on the <code>tzname</code>
global variable, read the <code>tzset(3)</code> man page.)
<p>
<b>Solutions</b><br>
Recent releases of ProFTPD attempt to work around these issues by
preserving the <code>tzname</code> global variable after calling
<code>localtime(3)</code>, and by automatting setting the <code>TZ</code>
environment variable, is not already set, before calling <code>chroot(2)</code>.
These measures are defensive at best, though.
<p>
The best way to deal with this issue, which is especially prominent on systems
running <code>glibc-2.3</code> or later, is to set the <code>TZ</code>
environment variable explicitly, before starting <code>proftpd</code>. This
can be done in an <code>init</code> script for <code>proftpd</code>, for
example.
<p>
You can also use the <code>SetEnv</code> configuration directive within the
<code>proftpd.conf</code> file to set the <code>TZ</code> environment variable,
<i>e.g.</i>:
<pre>
# Set the TZ environment variable to be Pacific Standard Time (PST)
SetEnv TZ PST
</pre>
Obviously you will need to set the timezone to whatever is appropriate for
your site. For example, some systems expect different values for the
<code>TZ</code> environment variable, <i>e.g.</i>:
<pre>
SetEnv TZ :/etc/localtime
</pre>
These are provided as <i>examples</i>; please consult your system documentation
for the proper syntax to use for the <code>TZ</code> value.
<p><a name="FAQ">
<b>Frequently Asked Questions</b><br>
<p>
<font color=red>Question</font>: Why is the timestamp on my newly uploaded file wrong?<br>
<font color=blue>Answer</font>: If by "wrong" you mean "different from
the timestamp of that file on my client machine", then that is the expected
behavior.
<p>
The modification timestamp on a file is <i>not</i> part of the data uploaded
over the data connection when uploading a file. Timestamps like that are
<i>metadata</i> for that file, not part of the bytes of the file itself.
FTP does not supporting sending of timestamps as part of the upload transfer
process. See below for a common follow-up question.
<p>
<font color=red>Question</font>: Does ProFTPD support changing the timestamp on a file using the <code>MDTM</code> command? That's what my client does.<br>
<font color=blue>Answer</font>: No.
<p>
Why not? For several reasons:
<ul>
<li>The <code>MDTM</code> command is <b>not</b> one of the commands
mandated by <a href="http://www.faqs.org/rfcs/rfc959.html">RFC959</a>.
<li>Some FTP clients use <code>MDTM</code> for <i>retrieving</i> the
modification time, others try to use it to <i>set</i> the modification
time, and still others do both.
<li>Among those FTP clients that do use <code>MDTM</code>, there is no
consistent format of the timestamp used.
</ul>
In short, it is a royal mess. ProFTPD supports <code>MDTM</code> for
retrieving the modification time, in GMT. Period.
<p>
If you want to set the modification time, you can use the
<code>mod_site_misc</code> module's <a href="../contrib/mod_site_misc.html#SITE_UTIME"><code>SITE UTIME</code></a> command.
<p>
<font color=red>Question</font>: I thought that the <code>TimesGMT</code> directive was causing this?<br>
<font color=blue>Answer</font>: No. The <a href="http://www.proftpd.org/docs/directives/linked/config_ref_TimesGMT.html"><code>TimesGMT</code></a> directive
only affects the timestamps as displayed to FTP clients in directory listings;
it does <b>not</b> affect the timestamps used in log files.
<p>
<hr>
<i>$Date: 2007/06/28 17:41:29 $</i><br>
</body>
</html>
