r4 - 2011-07-25 - 06:11:53 - HarlanStennYou are here: NTP >  Dev Web > DocumentationProject > GenLocInfo
NTP users are strongly urged to take immediate action to ensure that their NTP daemons are not susceptible to being used in distributed denial-of-service (DDoS) attacks. Please also take this opportunity to defeat denial-of-service attacks by implementing Ingress and Egress filtering through BCP38.

ntp-4.2.8p15 was released on 23 June 2020. It addresses 1 medium-severity security issue in ntpd, and provides 13 non-security bugfixes over 4.2.8p13.

Please see the NTP Security Notice for vulnerability and mitigation details.

Are you using Autokey in production? If so, please contact Harlan - he's got some questions for you.


The genLocInfo script

The top-level configure program will run scripts/genLocInfo in order to choose, based on (the version of) the target operating system:

  • where various NTP programs are installed (bin or sbin or, as of 4.2.7p194, libexec)
  • which manual macros should be installed (man or mdoc)
  • which section the manual pages should be installed under (1, 1m, 1M, or 8)

Since we do not want to require the average "installer" to have GNU AutoGen installed, we must pre-generate our documentation.

This means we need to generate two sets of (unformatted) manual pages, one using man macros, and another using mdoc macros.

When we produce the files for installation, the generated Makefile must therefore know:

  • if a program belongs in bin_PROGRAMS or sbin_PROGRAMS or, as of 4.2.7p194, libexec_PROGRAMS
  • which of foo.man or foo.mdoc should be installed in which "section", for the man_MANS variable

The Makefile will know the local policy choices for this because of the autoconf macro NTP_LOCINFO, which is defined in sntp/m4/ntp_locs.m4 .

After a successful run of configure, NTP_LOCINFO will produce a list of substitution variables, like:

Destination bin - either empty, or the name of the program to install in bin/ .
Destination libexec - either empty, or the name of the program to install in libexec/ .
Destination sbin - either empty, or the name of the program to install in sbin/ .
Manual Section - one of 1, 1m, 1M, or 8, specifying where ntp-keygen should have its manual page installed.

Cross-references in NTP's manual pages

The NTP Distribution supports a wide variety of "policy choices" for the manual section that will be preferred by any given system.

If the author of an "outside" manual document knows that the local policy choice for, say ntpd is for it to be in section 8 of the manual pages, the author would code that using .Xr ntpd 8 (to use the mdoc cross-reference macro).

However, NTP documentation authors must use a more general mechanism to allow for the customization of these local policy choices. Therefore, when writing man page documentation using mdoc tags, the author would write .Xr ntpd 1ntpdmdoc or .Xr ntpd 1ntpdman (the choice of ...mdoc or ...man does not matter). This is still a bit unclear - for an example, see sntp/sntp-opts.def and the rules for producing sntp.man.in and sntp.mdoc.in in sntp/Makefile.am.

The complete list of cross-reference "names" can be found by looking at sntp/include/mansec2subst.sed .

Now to describe how all of this works...

Producing manual pages in a Makefile.am

The EXTRA_DIST target in, for example, sntp/Makefile.am includes:

  • sntp.1smtpman
  • sntp.1smtpmdoc
  • sntp.man.in
  • sntp.mdoc.in

This specification means the 4 mentioned files will be included in the tarball distribution.

The noinst_DATA target in that same file includes:

  • $(srcdir)/sntp.man.in
  • $(srcdir)/sntp.mdoc.in

This specification means that the 2 mentioned files should be built.

If you are interested in this, it will probably be best if you look at a working example.

Anyway, GNU AutoGen uses -DMAN_SECTION=1smtpman -Tagman-cmd.tpl to produce sntp.1smtpman using man macros (the suffix is chosen based on the value of -DMAN_SECTION and -Tagman-cmd.tpl says that we're producing an autogen command page using =man=macros.

You can probably guess (or see) how a similar line would produce mdoc pages.

We then have to post-process these generated pages to properly handle cross-references, and that is the job of the rule (again, to continue the example) in sntp/Makefile.am that takes sntp.1.smtpman and turns it in to sntp.man.in .

We produce a .in file here, because when the builder runs configure we choose the target manual sections, and at the end of configure the config.status script is run, and that will convert the selected sntp.man.in or sntp.mdoc.in into sntp.X, where X is the value in SNTP_MS (so it will be 1, 1m, 1M, or 8), and add this filename to the man_MANS target.

This conversion process uses mansec2subst.sed, which is described next.


Any given NTP-related manual page will likely have many cross-references to other NTP programs, and since the manual section is a local policy choice, we must produce the desired manual pages containing the desired manual macros that include proper manual sections for the other programs.

Since we must build the pages in a way that gives us the ability to later emit them with local policy choices, the final step in the creation of the .man.in or .mdoc.in pages is to translate the occurrences of 1smtpman or 1smtpmdoc in the files produced by autogen into "value substitution strings" (in the .man.in and .mdoc.in files).

This task is handled by the Makefile.am rules that call sed -f include/mansec2subst.sed (or similar, depending on the Makefile.am).

-- HarlanStenn - 2011-06-21

Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r4 < r3 < r2 < r1 | More topic actions
SSL security by CAcert
Get the CAcert Root Certificate
This site is powered by the TWiki collaboration platform
IPv6 Ready
Copyright & 1999-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors. Ideas, requests, problems regarding the site? Send feedback