adjust rdate example

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

adjust rdate example

Ted Unangst-6
The sample server doesn't work for me, and while the example is a fun hint at
the alternate universe of "right" and "legal" times, I don't think this is a
good place to suggest actually changing the system timezone.

Demonstrate printing a time modified by TZ instead.


Index: rdate.8
===================================================================
RCS file: /cvs/src/usr.sbin/rdate/rdate.8,v
retrieving revision 1.37
diff -u -p -r1.37 rdate.8
--- rdate.8 10 Feb 2015 13:10:27 -0000 1.37
+++ rdate.8 6 Jan 2019 03:18:48 -0000
@@ -93,18 +93,9 @@ Always show the adjustment.
 record of date resets and time changes
 .El
 .Sh EXAMPLES
-To get the legal time in Germany, set the
-.Pa /etc/localtime
-symlink to
-.Pa /usr/share/zoneinfo/right/Europe/Berlin
-and issue the following command:
+To print the legal time in Germany, issue the following command:
 .Pp
-.D1 Li "# rdate -v ptbtime1.ptb.de"
-.Pp
-The command of course assumes you have a working internet connection
-and DNS set up to connect to the server at
-.Sy Physikalisch-Technische Bundesanstalt
-in Braunschweig, Germany.
+.D1 Li "$ env TZ=right/Europe/Berlin rdate -p pool.ntp.org"
 .Sh SEE ALSO
 .Xr date 1 ,
 .Xr adjtime 2 ,

Reply | Threaded
Open this post in threaded view
|

Re: adjust rdate example

Theo de Raadt-2
First off, what a weird example you found.

But more on the matter.  Is your change even good advice?  pool.ntp.org
is attackable via unauthenticated DNS, and based upon past experience
who can say if their administrators can even keep their infrastructure
secure.  Furthermore, the ntp protocol has no security and can be
man-in-the-middled to provide lies (in a ntp daemon one can listen to
many replies and get some confidence, but this rdate example is
one-shot).

So at best this gives you a potentially correct answer about Germany,
not considering the leap second, and not considering TZ database changes
which seem to be happening continually and "Legally".

So an alternative proposal: Should this weird EXAMPLES section be deleted?

Ted Unangst <[hidden email]> wrote:

> The sample server doesn't work for me, and while the example is a fun hint at
> the alternate universe of "right" and "legal" times, I don't think this is a
> good place to suggest actually changing the system timezone.
>
> Demonstrate printing a time modified by TZ instead.
>
>
> Index: rdate.8
> ===================================================================
> RCS file: /cvs/src/usr.sbin/rdate/rdate.8,v
> retrieving revision 1.37
> diff -u -p -r1.37 rdate.8
> --- rdate.8 10 Feb 2015 13:10:27 -0000 1.37
> +++ rdate.8 6 Jan 2019 03:18:48 -0000
> @@ -93,18 +93,9 @@ Always show the adjustment.
>  record of date resets and time changes
>  .El
>  .Sh EXAMPLES
> -To get the legal time in Germany, set the
> -.Pa /etc/localtime
> -symlink to
> -.Pa /usr/share/zoneinfo/right/Europe/Berlin
> -and issue the following command:
> +To print the legal time in Germany, issue the following command:
>  .Pp
> -.D1 Li "# rdate -v ptbtime1.ptb.de"
> -.Pp
> -The command of course assumes you have a working internet connection
> -and DNS set up to connect to the server at
> -.Sy Physikalisch-Technische Bundesanstalt
> -in Braunschweig, Germany.
> +.D1 Li "$ env TZ=right/Europe/Berlin rdate -p pool.ntp.org"
>  .Sh SEE ALSO
>  .Xr date 1 ,
>  .Xr adjtime 2 ,
>

Reply | Threaded
Open this post in threaded view
|

Re: adjust rdate example

Ingo Schwarze
Hi Ted,

Theo de Raadt wrote on Sat, Jan 05, 2019 at 08:31:27PM -0700:
> Ted Unangst <[hidden email]> wrote:

>> The sample server doesn't work for me,

The sample server does work for me:

   $ host ptbtime1.ptb.de
  ptbtime1.ptb.de has address 192.53.103.108
   $ env TZ=UTC rdate -p ptbtime1.ptb.de
  Sun Jan  6 03:51:29 UTC 2019

However, while decades ago, there probably wasn't much wrong with
abusing central infrastructure like this for examples, nowadays,
that looks like a bad idea.

>> and while the example is a fun
>> hint at the alternate universe of "right" and "legal" times, I don't
>> think this is a good place to suggest actually changing the system
>> timezone.
>>
>> Demonstrate printing a time modified by TZ instead.

Congrats, you found a documentation bug.

Apparently, the rdate(8) program supports the TZ environment variable,
but the manual page does not say so.  An ENVIRONMENT section is missing
and should be added.  It is not a good idea to give EXAMPLES for stuff
that is accidentally undocumented.

> First off, what a weird example you found.
>
> But more on the matter.  Is your change even good advice?  pool.ntp.org
> is attackable via unauthenticated DNS, and based upon past experience
> who can say if their administrators can even keep their infrastructure
> secure.  Furthermore, the ntp protocol has no security and can be
> man-in-the-middled to provide lies (in a ntp daemon one can listen to
> many replies and get some confidence, but this rdate example is
> one-shot).
>
> So at best this gives you a potentially correct answer about Germany,
> not considering the leap second, and not considering TZ database changes
> which seem to be happening continually and "Legally".
>
> So an alternative proposal: Should this weird EXAMPLES section be deleted?

Even though i occasionally took the time to actually visit Brauschweig
during the last few years, i agree with deleting the example.  If all
you want to do is print the date and time, date(1) is almost certainly
the better tool - because you have made sure that your machine keeps
correct time, right?  Or if you are in the process of fixing the system
time on your machine, then ntpd(8) looks like the better tool.

I hardly see any remaining use case for rdate(8), so an example does
not seem helpful.

If you decide to keep the example, please use

  .Dl foo bar

instead of

  .D1 Li "foo bar"

while there.  As i just discussed with Jason, .Li is almost never
useful, so let's simplify things and get rid of it.  See the "Li"
entry in the mdoc(7) manual.

Yours,
  Ingo


> > Index: rdate.8
> > ===================================================================
> > RCS file: /cvs/src/usr.sbin/rdate/rdate.8,v
> > retrieving revision 1.37
> > diff -u -p -r1.37 rdate.8
> > --- rdate.8 10 Feb 2015 13:10:27 -0000 1.37
> > +++ rdate.8 6 Jan 2019 03:18:48 -0000
> > @@ -93,18 +93,9 @@ Always show the adjustment.
> >  record of date resets and time changes
> >  .El
> >  .Sh EXAMPLES
> > -To get the legal time in Germany, set the
> > -.Pa /etc/localtime
> > -symlink to
> > -.Pa /usr/share/zoneinfo/right/Europe/Berlin
> > -and issue the following command:
> > +To print the legal time in Germany, issue the following command:
> >  .Pp
> > -.D1 Li "# rdate -v ptbtime1.ptb.de"
> > -.Pp
> > -The command of course assumes you have a working internet connection
> > -and DNS set up to connect to the server at
> > -.Sy Physikalisch-Technische Bundesanstalt
> > -in Braunschweig, Germany.
> > +.D1 Li "$ env TZ=right/Europe/Berlin rdate -p pool.ntp.org"
> >  .Sh SEE ALSO
> >  .Xr date 1 ,
> >  .Xr adjtime 2 ,

Reply | Threaded
Open this post in threaded view
|

Re: adjust rdate example

Ted Unangst-6
In reply to this post by Theo de Raadt-2
Theo de Raadt wrote:

> First off, what a weird example you found.
>
> But more on the matter.  Is your change even good advice?  pool.ntp.org
> is attackable via unauthenticated DNS, and based upon past experience
> who can say if their administrators can even keep their infrastructure
> secure.  Furthermore, the ntp protocol has no security and can be
> man-in-the-middled to provide lies (in a ntp daemon one can listen to
> many replies and get some confidence, but this rdate example is
> one-shot).
>
> So at best this gives you a potentially correct answer about Germany,
> not considering the leap second, and not considering TZ database changes
> which seem to be happening continually and "Legally".
>
> So an alternative proposal: Should this weird EXAMPLES section be deleted?

Heh, I did that first, but then I thought there was some value here. Give the
user a few hints about things to search for, although my own searching
indicates that TAI time isn't legal time. So drop that noise.

Here's a slightly simpler example that mentions lack of authentication.

Index: rdate.8
===================================================================
RCS file: /cvs/src/usr.sbin/rdate/rdate.8,v
retrieving revision 1.37
diff -u -p -r1.37 rdate.8
--- rdate.8 10 Feb 2015 13:10:27 -0000 1.37
+++ rdate.8 6 Jan 2019 04:05:19 -0000
@@ -93,18 +93,9 @@ Always show the adjustment.
 record of date resets and time changes
 .El
 .Sh EXAMPLES
-To get the legal time in Germany, set the
-.Pa /etc/localtime
-symlink to
-.Pa /usr/share/zoneinfo/right/Europe/Berlin
-and issue the following command:
+Print the time in Germany, from an unauthenticated public pool:
 .Pp
-.D1 Li "# rdate -v ptbtime1.ptb.de"
-.Pp
-The command of course assumes you have a working internet connection
-and DNS set up to connect to the server at
-.Sy Physikalisch-Technische Bundesanstalt
-in Braunschweig, Germany.
+.D1 Li "$ env TZ=Europe/Berlin rdate -p pool.ntp.org"
 .Sh SEE ALSO
 .Xr date 1 ,
 .Xr adjtime 2 ,

Reply | Threaded
Open this post in threaded view
|

Re: adjust rdate example

Ted Unangst-6
In reply to this post by Ingo Schwarze
Ingo Schwarze wrote:
> Congrats, you found a documentation bug.
>
> Apparently, the rdate(8) program supports the TZ environment variable,
> but the manual page does not say so.  An ENVIRONMENT section is missing
> and should be added.  It is not a good idea to give EXAMPLES for stuff
> that is accidentally undocumented.

fix below.

> > So an alternative proposal: Should this weird EXAMPLES section be deleted?
>
> Even though i occasionally took the time to actually visit Brauschweig
> during the last few years, i agree with deleting the example.  If all

ok, that's two thumbs down. it's dead.

Index: rdate.8
===================================================================
RCS file: /cvs/src/usr.sbin/rdate/rdate.8,v
retrieving revision 1.37
diff -u -p -r1.37 rdate.8
--- rdate.8 10 Feb 2015 13:10:27 -0000 1.37
+++ rdate.8 6 Jan 2019 04:14:24 -0000
@@ -87,24 +87,28 @@ Do not print the time.
 Verbose output.
 Always show the adjustment.
 .El
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev TZ
+The time zone to use when displaying dates.
+It is normally specified as a pathname relative to
+.Pa /usr/share/zoneinfo ,
+though see
+.Xr tzset 3
+for more information.
+If this variable is not set, the time zone is determined based on
+.Pa /etc/localtime ,
+which the administrator adjusts using
+the
+.Fl l
+option of
+.Xr zic 8 .
+.El
 .Sh FILES
 .Bl -tag -width /var/log/wtmp -compact
 .It Pa /var/log/wtmp
 record of date resets and time changes
 .El
-.Sh EXAMPLES
-To get the legal time in Germany, set the
-.Pa /etc/localtime
-symlink to
-.Pa /usr/share/zoneinfo/right/Europe/Berlin
-and issue the following command:
-.Pp
-.D1 Li "# rdate -v ptbtime1.ptb.de"
-.Pp
-The command of course assumes you have a working internet connection
-and DNS set up to connect to the server at
-.Sy Physikalisch-Technische Bundesanstalt
-in Braunschweig, Germany.
 .Sh SEE ALSO
 .Xr date 1 ,
 .Xr adjtime 2 ,

Reply | Threaded
Open this post in threaded view
|

Re: adjust rdate example

Theo de Raadt-2
In reply to this post by Ingo Schwarze
Ingo Schwarze <[hidden email]> wrote:

> >> Demonstrate printing a time modified by TZ instead.
>
> Congrats, you found a documentation bug.
>
> Apparently, the rdate(8) program supports the TZ environment variable,
> but the manual page does not say so.  An ENVIRONMENT section is missing
> and should be added.  It is not a good idea to give EXAMPLES for stuff
> that is accidentally undocumented.

I have no idea where you come to this conclusion.

TZ isn't supported by the program.

Rather it is supported by libc.  This program happens to call libc
functionality which is mandated to honour the environment variable, but
so what?  TZ is fundamental, all time_t to text translations use TZ, it
is unavoidable and intrinsic to Unix.

Do you intend to add an ENVIRONMENT section documenting TZ to a hundred
or so programs which print times?  I think it is unsustainable and
wasteful effort, obscuring far more important messaging.

Digging through the tree..

I see that date(1) documents the trickery that you can do with -l.
ssh(1) documents it is handed to .. ok ssh is documenting it incorrectly
I think.

I see that ls(1) has it documented as doing what you expect.  I cannot
figure out why it is documented, since it is an obvious part of Unix,
and ls isn't doing something special or out of the ordinary.  A distracting
waste of letters.

I do not think programs should document behavioural aspects derived from
the system behaviour as a whole, unless that aspect is unique, surprising,
or altered by the program.

Reply | Threaded
Open this post in threaded view
|

Re: adjust rdate example

Theo de Raadt-2
In reply to this post by Ted Unangst-6
Ted Unangst <[hidden email]> wrote:

> Ingo Schwarze wrote:
> > Congrats, you found a documentation bug.
> >
> > Apparently, the rdate(8) program supports the TZ environment variable,
> > but the manual page does not say so.  An ENVIRONMENT section is missing
> > and should be added.  It is not a good idea to give EXAMPLES for stuff
> > that is accidentally undocumented.
>
> fix below.
>
> > > So an alternative proposal: Should this weird EXAMPLES section be deleted?
> >
> > Even though i occasionally took the time to actually visit Brauschweig
> > during the last few years, i agree with deleting the example.  If all
>
> ok, that's two thumbs down. it's dead.
>
> Index: rdate.8
> ===================================================================
> RCS file: /cvs/src/usr.sbin/rdate/rdate.8,v
> retrieving revision 1.37
> diff -u -p -r1.37 rdate.8
> --- rdate.8 10 Feb 2015 13:10:27 -0000 1.37
> +++ rdate.8 6 Jan 2019 04:14:24 -0000
> @@ -87,24 +87,28 @@ Do not print the time.
>  Verbose output.
>  Always show the adjustment.
>  .El
> +.Sh ENVIRONMENT
> +.Bl -tag -width Ds
> +.It Ev TZ
> +The time zone to use when displaying dates.
> +It is normally specified as a pathname relative to
> +.Pa /usr/share/zoneinfo ,
> +though see
> +.Xr tzset 3
> +for more information.
> +If this variable is not set, the time zone is determined based on
> +.Pa /etc/localtime ,
> +which the administrator adjusts using
> +the
> +.Fl l
> +option of
> +.Xr zic 8 .
> +.El

Oh good grief, don't do that.

Unless you are going to add the same text to every man page in usr.sbin
on the following list.

ac bgpd dhcpd httpd ldapd mrouted npppctl nsd ntpd radiusd rdate relayd
slaacctl smtpd syslogd tcpdump unbound

They all call strftime.  So TZ affects them.  There are other API that
get involved.  You could be adding this text to 400 manual pages.

But now you've seen my previous mail arguing against this practice.
It is pointless to document "system behaviour" in every program.

Wait until you see my diff that documents PATH in every program that
calls execve() or system, or HOME in every program that... you get
the idea!!!!

>  .Sh FILES
>  .Bl -tag -width /var/log/wtmp -compact
>  .It Pa /var/log/wtmp
>  record of date resets and time changes
>  .El
> -.Sh EXAMPLES
> -To get the legal time in Germany, set the
> -.Pa /etc/localtime
> -symlink to
> -.Pa /usr/share/zoneinfo/right/Europe/Berlin
> -and issue the following command:
> -.Pp
> -.D1 Li "# rdate -v ptbtime1.ptb.de"
> -.Pp
> -The command of course assumes you have a working internet connection
> -and DNS set up to connect to the server at
> -.Sy Physikalisch-Technische Bundesanstalt
> -in Braunschweig, Germany.
>  .Sh SEE ALSO
>  .Xr date 1 ,
>  .Xr adjtime 2 ,

Yes to this.

Reply | Threaded
Open this post in threaded view
|

Re: adjust rdate example

Ingo Schwarze
Hi Theo,

Theo de Raadt wrote on Sat, Jan 05, 2019 at 09:23:46PM -0700:

> Oh good grief, don't do that.
>
> Unless you are going to add the same text to every man page in usr.sbin
> on the following list.
>
> ac bgpd dhcpd httpd ldapd mrouted npppctl nsd ntpd radiusd rdate relayd
> slaacctl smtpd syslogd tcpdump unbound
>
> They all call strftime.  So TZ affects them.  There are other API that
> get involved.  You could be adding this text to 400 manual pages.
>
> But now you've seen my previous mail arguing against this practice.
> It is pointless to document "system behaviour" in every program.
>
> Wait until you see my diff that documents PATH in every program that
> calls execve() or system, or HOME in every program that... you get
> the idea!!!!

Hm, you have a point.

I guess i got confused by my experience with LC_CTYPE; even though
that is also a standard variable, its effects on different programs
vary wildly, so the text for LC_CTYPE reads very differently in
different utility manual pages, and it is often relevant which
aspects are supported and which are not.

For TZ, the effect is probably mostly the same everywhere, with few
exceptions like mail.local(8), and describing it properly gets
somewhat wordy.  So the full explanation is probably best placed
located in environ(7).  Utilities where it is unusually important,
like date(1), might benefit from a short pointer below ENVIRONMENT,
though, to help beginners, like it exists in ls(1).

   $ man -M /usr/share/man -k Ev=TZ
  date(1) - display or set date and time
  ls(1) - list directory contents
  ps(1) - display process status
  ssh(1) - OpenSSH SSH client (remote login program)
  tzset, tzsetwall(3) - initialize time conversion information
  environ(7) - user environment
  mail.local(8) - store mail in a mailbox

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: adjust rdate example

Theo de Raadt-2
Ingo Schwarze <[hidden email]> wrote:
> Hm, you have a point.
>
> I guess i got confused by my experience with LC_CTYPE; even though
> that is also a standard variable, its effects on different programs
> vary wildly, so the text for LC_CTYPE reads very differently in
> different utility manual pages, and it is often relevant which
> aspects are supported and which are not.

I think the ENVIRONMENT section should only describe non-default
divergent behaviour, and environ(7) covers the default behaviour.

> So the full explanation is probably best placed
> located in environ(7).  Utilities where it is unusually important,
> like date(1), might benefit from a short pointer below ENVIRONMENT,
> though, to help beginners, like it exists in ls(1).

I disagree on ls(1).  Please explain why you think this is the place
to point people at environ(7).  It is a strongly known part of Unix,
meaning the moment people become aware of any aspect of Unix timezone
handling, they immediately understand it applies to all utilities and
seeing a note burried in the bottom of ls(1) isn't going to help them.

>    $ man -M /usr/share/man -k Ev=TZ
>   date(1) - display or set date and time

date is fine, TZ documentation should stay due to -l and -j being weird.

>   ssh(1) - OpenSSH SSH client (remote login program)

this talks about how TZ is replicated, so it should stay.

>   mail.local(8) - store mail in a mailbox

I concur, this one should stay.

>   tzset, tzsetwall(3) - initialize time conversion information
>   environ(7) - user environment

those should stay.


>   ls(1) - list directory contents
>   ps(1) - display process status

But I think it should TZ documentation should be deleted from ls(1) and ps(1)