From 3fb985fd04611082bbfc3622a078e8c5e5edb378 Mon Sep 17 00:00:00 2001
From: Rich Salz <rsalz@akamai.com>
Date: Thu, 29 Apr 2021 16:22:30 -0400
Subject: Allow absolute paths to be set

It was a mistake to allow relative paths for include files (just
like root shouldn't have "." in its PATH), but we probably can't
change it now. Add a new pragma "abspath" that someone can put
in the system-wide config file to require absolute paths.

Also update the config documentation to better explain how file
inclusion works.

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15090)
---
 doc/man5/config.pod | 39 +++++++++++++++++++--------------------
 1 file changed, 19 insertions(+), 20 deletions(-)

(limited to 'doc/man5/config.pod')

diff --git a/doc/man5/config.pod b/doc/man5/config.pod
index 39da6dcb74..6b800b96e1 100644
--- a/doc/man5/config.pod
+++ b/doc/man5/config.pod
@@ -47,11 +47,21 @@ inside the B<pathname> are B<ignored>.  Similarly, if a file is opened
 while scanning a directory, and that file has an B<.include> directive
 that specifies a directory, that is also ignored.
 
-As a general rule, the B<pathname> should be an absolute path.  Relative
-paths are evaluated based on the current working directory, so unless the
-file with the B<.include> directive is application-specific, the inclusion
-will not work as expected.  The environment variable B<OPENSSL_CONF_INCLUDE>,
-if it exists, will be prepended to all B<.include> B<pathname>'s.
+As a general rule, the B<pathname> should be an absolute path; this can
+be enforced with the B<relpath> pragma, described below.
+The environment variable B<OPENSSL_CONF_INCLUDE>, if it exists,
+is prepended to all relative pathnames.
+If the pathname is still relative, it is interpreted based on the
+current working directory.
+
+To require all file inclusions to name absolute paths, use the following
+directive:
+
+ .progma [=] abspath:value
+
+The default behavior, where the B<value> is B<false> or B<off>, is to allow
+relative paths. To require all B<.include> pathnames to be absolute paths,
+use a B<value> of B<true> or B<on>.
 
 In these files, the dollar sign, B<$>, is used to reference a variable, as
 described below.  On some platforms, however, it is common to treat B<$>
@@ -60,22 +70,11 @@ done with the following directive:
 
  .pragma [=] dollarid:value
 
-Where B<value> is one of the following:
-
-=over 4
-
-=item B<off> or B<false>
-
-This is the default behavior. For example, C<foo$bar> is interpreted as
-C<foo> followed by the expansion of the variable C<bar>.
-
-=item B<on> or B<true>
-
-This specifies that dollar signs are part of the symbol name and
+The default behavior, where the B<value> is B<false> or B<off>, is to treat
+the dollarsign as indicating a variable name; C<foo$bar> is interpreted as
+C<foo> followed by the expansion of the variable C<bar>. If B<value> is
+B<true> or B<on>, then C<foo$bar> is a single seven-character name nad
 variable expansions must be specified using braces or parentheses.
-For example, C<foo$bar> is treated as a single seven-character name.
-
-=back
 
 =head2 Settings
 
-- 
cgit v1.2.3