Manage all mod_remoteip parameters supported by Apache

manifests/mod/remoteip.pp

@@ -1,28 +1,109 @@
+# @summary Setup and load Apache `mod_remoteip`
+#
+# @see https://httpd.apache.org/docs/current/mod/mod_remoteip.html
+#
+# @param header
+#   The header field in which `mod_remoteip` will look for the useragent IP.
+#
+# @param internal_proxy
+#   A list of IP addresses, IP blocks or hostname that are trusted to set a
+#   valid value inside specified header. Unlike the `$trusted_proxy_ips`
+#   parameter, any IP address (including private addresses) presented by these
+#   proxies will trusted by `mod_remoteip`.
+#
+# @param proxy_ips
+#   *Deprecated*: use `$internal_proxy` instead.
+#
+# @param internal_proxy_list
+#   The path to a file containing a list of IP addresses, IP blocks or hostname
+#   that are trusted to set a valid value inside the specified header. See
+#   `$internal_proxy` for details.
+#
+# @param proxies_header
+#   A header into which `mod_remoteip` will collect a list of all of the
+#   intermediate client IP addresses trusted to resolve the useragent IP of the
+#   request (e.g. `X-Forwarded-By`).
+#
+# @param proxy_protocol
+#   Wether or not to enable the PROXY protocol header handling. If enabled
+#   upstream clients must set the header every time they open a connection.
+#
+# @param proxy_protocol_exceptions
+#   A list of IP address or IP blocks that are not required to use the PROXY
+#   protocol.
+#
+# @param trusted_proxy
+#   A list of IP addresses, IP blocks or hostname that are trusted to set a
+#   valid value inside the specified header. Unlike the `$proxy_ips` parameter,
+#   any private IP presented by these proxies will be disgarded by
+#   `mod_remoteip`.
+#
+# @param trusted_proxy_ips
+#   *Deprecated*: use `$trusted_proxy` instead.
+#
+# @param trusted_proxy_list
+#   The path to a file containing a list of IP addresses, IP blocks or hostname
+#   that are trusted to set a valid value inside the specified header. See
+#   `$trusted_proxy` for details.
+#
+# @param apache_version
+#   A version string used to validate that your apache version supports
+#   `mod_remoteip`. If not specified, `$::apache::apache_version` is used.
+#
 class apache::mod::remoteip (
-  $header            = 'X-Forwarded-For',
-  $proxy_ips         = [ '127.0.0.1' ],
-  $proxies_header    = undef,
-  $trusted_proxy_ips = undef,
-  $apache_version    = undef,
+  String                         $header                    = 'X-Forwarded-For',
+  Optional[Array[Stdlib::Host]]  $internal_proxy            = undef,
+  Optional[Array[Stdlib::Host]]  $proxy_ips                 = undef,
+  Optional[Stdlib::Absolutepath] $internal_proxy_list       = undef,
+  Optional[String]               $proxies_header            = undef,
+  Boolean                        $proxy_protocol            = false,
+  Optional[Array[Stdlib::Host]]  $proxy_protocol_exceptions = undef,
+  Optional[Array[Stdlib::Host]]  $trusted_proxy             = undef,
+  Optional[Array[Stdlib::Host]]  $trusted_proxy_ips         = undef,
+  Optional[Stdlib::Absolutepath] $trusted_proxy_list        = undef,
+  Optional[String]               $apache_version            = undef,
 ) {
   include ::apache
+
   $_apache_version = pick($apache_version, $apache::apache_version)
   if versioncmp($_apache_version, '2.4') < 0 {
     fail('mod_remoteip is only available in Apache 2.4')
   }
 
+  if $proxy_ips {
+    deprecation('apache::mod::remoteip::proxy_ips', 'This parameter is deprecated, please use `internal_proxy`.')
+    $_internal_proxy = $proxy_ips
+  } elsif $internal_proxy {
+    $_internal_proxy = $internal_proxy
+  } else {
+    $_internal_proxy = ['127.0.0.1']
+  }
+
+  if $trusted_proxy_ips {
+    deprecation('apache::mod::remoteip::trusted_proxy_ips', 'This parameter is deprecated, please use `trusted_proxy`.')
+    $_trusted_proxy = $trusted_proxy_ips
+  } else {
+    $_trusted_proxy = $trusted_proxy
+  }
+
   ::apache::mod { 'remoteip': }
 
-  # Template uses:
-  # - $header
-  # - $proxy_ips
-  # - $proxies_header
-  # - $trusted_proxy_ips
+  $template_parameters = {
+    header                    => $header,
+    internal_proxy            => $_internal_proxy,
+    internal_proxy_list       => $internal_proxy_list,
+    proxies_header            => $proxies_header,
+    proxy_protocol            => $proxy_protocol,
+    proxy_protocol_exceptions => $proxy_protocol_exceptions,
+    trusted_proxy             => $_trusted_proxy,
+    trusted_proxy_list        => $trusted_proxy_list,
+  }
+
   file { 'remoteip.conf':
     ensure  => file,
     path    => "${::apache::mod_dir}/remoteip.conf",
     mode    => $::apache::file_mode,
-    content => template('apache/mod/remoteip.conf.erb'),
+    content => epp('apache/mod/remoteip.conf.epp', $template_parameters),
     require => Exec["mkdir ${::apache::mod_dir}"],
     before  => File[$::apache::mod_dir],
     notify  => Class['apache::service'],

spec/classes/mod/remoteip_spec.rb

@@ -30,6 +30,14 @@
 
       it { is_expected.to contain_file('remoteip.conf').with_content(%r{^RemoteIPHeader X-Forwarded-For$}) }
     end
+    describe 'with internal_proxy => [ 10.42.17.8, 10.42.18.99 ]' do
+      let :params do
+        { internal_proxy: ['10.42.17.8', '10.42.18.99'] }
+      end
+
+      it { is_expected.to contain_file('remoteip.conf').with_content(%r{^RemoteIPInternalProxy 10.42.17.8$}) }
+      it { is_expected.to contain_file('remoteip.conf').with_content(%r{^RemoteIPInternalProxy 10.42.18.99$}) }
+    end
     describe 'with proxy_ips => [ 10.42.17.8, 10.42.18.99 ]' do
       let :params do
         { proxy_ips: ['10.42.17.8', '10.42.18.99'] }
@@ -38,14 +46,28 @@
       it { is_expected.to contain_file('remoteip.conf').with_content(%r{^RemoteIPInternalProxy 10.42.17.8$}) }
       it { is_expected.to contain_file('remoteip.conf').with_content(%r{^RemoteIPInternalProxy 10.42.18.99$}) }
     end
+    describe 'with trusted_proxy => [ 10.42.17.8, 10.42.18.99 ]' do
+      let :params do
+        { trusted_proxy: ['10.42.17.8', '10.42.18.99'] }
+      end
+
+      it { is_expected.to contain_file('remoteip.conf').with_content(%r{^RemoteIPTrustedProxy 10.42.17.8$}) }
+      it { is_expected.to contain_file('remoteip.conf').with_content(%r{^RemoteIPTrustedProxy 10.42.18.99$}) }
+    end
+    describe 'with trusted_proxy_ips => [ 10.42.17.8, 10.42.18.99 ]' do
+      let :params do
+        { trusted_proxy: ['10.42.17.8', '10.42.18.99'] }
+      end
+
+      it { is_expected.to contain_file('remoteip.conf').with_content(%r{^RemoteIPTrustedProxy 10.42.17.8$}) }
+      it { is_expected.to contain_file('remoteip.conf').with_content(%r{^RemoteIPTrustedProxy 10.42.18.99$}) }
+    end
     describe 'with Apache version < 2.4' do
       let :params do
         { apache_version: '2.2' }
       end
 
-      it 'fails' do
-        expect { catalogue }.to raise_error(Puppet::Error, %r{mod_remoteip is only available in Apache 2.4})
-      end
+      it { expect { catalogue }.to raise_error(Puppet::Error, %r{mod_remoteip is only available in Apache 2.4}) }
     end
   end
 end

templates/mod/remoteip.conf.epp

@@ -0,0 +1,51 @@
+<%- |
+  String                               $header,
+  Optional[Array[Stdlib::IP::Address]] $internal_proxy            = undef,
+  Optional[Stdlib::Absolutepath]       $internal_proxy_list       = undef,
+  Optional[String]                     $proxies_header            = undef,
+  Boolean                              $proxy_protocol            = undef,
+  Optional[Array[Stdlib::IP::Address]] $proxy_protocol_exceptions = undef,
+  Optional[Array[Stdlib::IP::Address]] $trusted_proxy             = undef,
+  Optional[Stdlib::Absolutepath]       $trusted_proxy_list        = undef,
+| -%>
+# Declare the header field which should be parsed for useragent IP addresses
+RemoteIPHeader <%= $header %>
+
+<%- if $internal_proxy { -%>
+# Declare client intranet IP addresses trusted to present
+# the RemoteIPHeader value
+<%-   [$internal_proxy].flatten.each |$proxy| { -%>
+RemoteIPInternalProxy <%= $proxy %>
+<%-   } -%>
+<%- } -%>
+
+<%- if $internal_proxy_list { -%>
+RemoteIPInternalProxyList <%= $internal_proxy_list %>
+<%- } -%>
+
+<%- if $proxies_header { -%>
+# Declare the header field which will record all intermediate IP addresses
+RemoteIPProxiesHeader <%= $proxies_header %>
+<%- } -%>
+
+<%- if $proxy_protocol { -%>
+RemoteIPProxyProtocol On
+<%- } -%>
+
+<%- if $proxy_protocol_exceptions { -%>
+<%-   [$proxy_protocol_exceptions].flatten.each |$exception| { -%>
+RemoteIPProxyProtocolExceptions <%= $exception %>
+<%-   } -%>
+<%- } -%>
+
+<%- if $trusted_proxy { -%>
+# Declare client intranet IP addresses trusted to present
+# the RemoteIPHeader value
+  <%- [$trusted_proxy].flatten.each |$proxy| { -%>
+RemoteIPTrustedProxy <%= $proxy %>
+  <%- } -%>
+<%- } -%>
+
+<%- if $trusted_proxy_list { -%>
+RemoteIPTrustedProxyList <%= $trusted_proxy_list %>
+<%- } -%>