Update the cupsd.conf man page to better explain what @IF(name) and @LOCAL do

(Issue #5604)

diff --git a/CHANGES.md b/CHANGES.md
index aea1045b34f2e15eb8431e9386c8a52c8540174d..61e857f193b76e0e4d7118e709aca79a81e82e57 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@ CHANGES - 2.3.0 - 2019-07-16
 Changes in CUPS v2.3.0
 ----------------------
 
+- Documentation updates (Issue #5604)
 - Fixed a bug in the scheduler job cleanup code (Issue #5588)
 - Fixed builds when there is no TLS library (Issue #5590)
 - Eliminated some new GCC compiler warnings (Issue #5591)

diff --git a/doc/help/man-cupsd.conf.html b/doc/help/man-cupsd.conf.html
index 10101dbbed178650083478e1493d7043ffa7e647..1668eee8afdaef64d82a191596e85e1ea7df382b 100644 (file)
--- a/doc/help/man-cupsd.conf.html
+++ b/doc/help/man-cupsd.conf.html
@@ -457,6 +457,8 @@ The following directives may be placed inside Location and Limit sections in the
 <dd style="margin-left: 5.0em"><dt><b>Allow @IF(</b><i>name</i><b>)</b>
 <dd style="margin-left: 5.0em"><dt><b>Allow @LOCAL</b>
 <dd style="margin-left: 5.0em">Allows access from the named hosts, domains, addresses, or interfaces.
+The @IF(name) form uses the current subnets configured for the named interface.
+The @LOCAL form uses the current subnets configured for all interfaces that are not point-to-point, for example Ethernet and Wi-Fi interfaces are used but DSL and VPN interfaces are not.
 The Order directive controls whether Allow lines are evaluated before or after Deny lines.
 <dt><b>AuthType None</b>
 <dd style="margin-left: 5.0em"><dt><b>AuthType Basic</b>
@@ -476,6 +478,8 @@ The value "Default" corresponds to the DefaultAuthType value.
 <dd style="margin-left: 5.0em"><dt><b>Deny @IF(</b><i>name</i><b>)</b>
 <dd style="margin-left: 5.0em"><dt><b>Deny @LOCAL</b>
 <dd style="margin-left: 5.0em">Denies access from the named hosts, domains, addresses, or interfaces.
+The @IF(name) form uses the current subnets configured for the named interface.
+The @LOCAL form uses the current subnets configured for all interfaces that are not point-to-point, for example Ethernet and Wi-Fi interfaces are used but DSL and VPN interfaces are not.
 The Order directive controls whether Deny lines are evaluated before or after Allow lines.
 <dt><b>Encryption IfRequested</b>
 <dd style="margin-left: 5.0em"><dt><b>Encryption Never</b>
@@ -585,6 +589,9 @@ On Linux this is typically done using the
 command, while on macOS the
 <b>launchctl</b>(8)
 command is used instead.
+<p>The @LOCAL macro name can be confusing since the system running
+<b>cupsd</b>
+often belongs to a different set of subnets from its clients.
 <h2 class="title"><a name="CONFORMING_TO">Conforming To</a></h2>
 The <b>cupsd.conf</b> file format is based on the Apache HTTP Server configuration file format.
 <h2 class="title"><a name="EXAMPLES">Examples</a></h2>

diff --git a/man/cupsd.conf.5 b/man/cupsd.conf.5
index 75d0602790553e7e71553b3fc5a9a1443c3a56a3..00b1a22d66af8ef410a5337f516e810a2be0e3ba 100644 (file)
--- a/man/cupsd.conf.5
+++ b/man/cupsd.conf.5
@@ -7,7 +7,7 @@
 .\" Licensed under Apache License v2.0.  See the file "LICENSE" for more
 .\" information.
 .\"
-.TH cupsd.conf 5 "CUPS" "2 May 2019" "Apple Inc."
+.TH cupsd.conf 5 "CUPS" "16 July 2019" "Apple Inc."
 .SH NAME
 cupsd.conf \- server configuration file for cups
 .SH DESCRIPTION
@@ -690,6 +690,8 @@ The following directives may be placed inside Location and Limit sections in the
 .TP 5
 \fBAllow @LOCAL\fR
 Allows access from the named hosts, domains, addresses, or interfaces.
+The @IF(name) form uses the current subnets configured for the named interface.
+The @LOCAL form uses the current subnets configured for all interfaces that are not point-to-point, for example Ethernet and Wi-Fi interfaces are used but DSL and VPN interfaces are not.
 The Order directive controls whether Allow lines are evaluated before or after Deny lines.
 .TP 5
 \fBAuthType None\fR
@@ -724,6 +726,8 @@ The value "Default" corresponds to the DefaultAuthType value.
 .TP 5
 \fBDeny @LOCAL\fR
 Denies access from the named hosts, domains, addresses, or interfaces.
+The @IF(name) form uses the current subnets configured for the named interface.
+The @LOCAL form uses the current subnets configured for all interfaces that are not point-to-point, for example Ethernet and Wi-Fi interfaces are used but DSL and VPN interfaces are not.
 The Order directive controls whether Deny lines are evaluated before or after Allow lines.
 .TP 5
 \fBEncryption IfRequested\fR
@@ -862,6 +866,10 @@ On Linux this is typically done using the
 command, while on macOS the
 .BR launchctl (8)
 command is used instead.
+.PP
+The @LOCAL macro name can be confusing since the system running
+.B cupsd
+often belongs to a different set of subnets from its clients.
 .SH CONFORMING TO
 The \fBcupsd.conf\fR file format is based on the Apache HTTP Server configuration file format.
 .SH EXAMPLES