Using the IP Filter plugin
Configuration
During installation of IP Filter plugin, configuration for localhost is bootstrapped into /hippo:configuration/hippo:modules/ipfilter/hippo:moduleconfig/localhost. To make the configuration work on other environments, please make a copy of this node with a descriptive name like ‘staging’ or ‘production’. Alternatively, if you want one configuration set, rename it to ‘all-envs’.
Configuration set matching
By default, we match a host configuration set based on X-Forwarded-Host header. To override this, you can add an optional multi-valued string property named forwarded-host-header, containing additional header names. This property must be set on hippo:moduleconfig node and this setting is applied to all configurations. Please note that we always add X-Forwarded-Host by default.
Properties of a configuration set
| Property | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | Enable this configuration or not. |
| hostnames | multiple string | Mandatory list of hostnames, matching a browser request to this configuration set. | |
| allowed-ip-ranges | multiple string | Whitelist of ip address ranges e.g. 2001:4cb8:29d:1::/64. Controls access the both CMS as the site. | |
| allow-cms-users | boolean | true | To access the site, allow login with CMS credentials, with a basic authentication popup. |
| match-all | boolean | false | To access the site, both IP address must be whitelisted and login with CMS credentials must be successful. |
| ignored-paths | multiple string | List of paths that are ignored by the filters, e.g. /ping/.* | |
| forwarded-for-header | string | X-Forwarded-For | Name of the request header that is used for forwarding. |
| cache-enabled | boolean | true | Enabled by default, cache is used to store authenticated users. |
NOTES - Both hostnames and ignored-paths must be regular expression escaped like *.onehippo\.org or 127\.0\.0\.1 - Either allow-cms-users or allowed-ip-ranges must be enabled for a valid configuration.
Multiple optional subconfigurations for special headers
Below a configuration set node, there may be any number of subnodes of type hipposys:moduleconfig, named freely but descriptively, for example “ignore-fastly”. Such node has the following properties:
| Property | Type | Description |
|---|---|---|
| ignored-header | string | Name of header to ignore, for example ‘X-fastly’. |
| ignored-header-values | multiple string | Values of ignored-header that must be matched for the request to be ignored by the filter. |
External properties file for default set up
Since version 2.2.0, an external properties file hippo-ipfilter.properties can be fed to the filters by either using a system property (by the same name) or just dropping it in Tomcat’s conf directory. It supports values for the allowed-ip-ranges and ignored-paths properties.
Default hippo-ipfilter.properties file:
#
# Configuration file for Hippo IP Filter Plugin.
#
# Set up this file for Hippo CMS and/or site application using either:
# - system property -Dhippo-ipfilter.properties=file://hostname/path (hostname may be omitted if localhost)
# - placement in ${catalina.base}/conf
# - placement in ${catalina.home}/conf
#
# This file supports these properties:
# - allowed-ip-ranges: comma separated whitelist of ip address ranges
# - ignored-paths: comma separated paths that are ignored
#
allowed-ip-ranges=127.0.0.1,0:0:0:0:0:0:0:1
ignored-paths=/ping/.*
System properties to disable the filters
For recovery purposes, should administrators have locked everybody out of the CMS/console by misconfiguration, the possibility exists to disable the filters by setting system properties.
| System Property | Description |
|---|---|
| hippo.cms-ipfilter.disabled | Disables the CMS’s org.onehippo.forge.ipfilter.cms.CmsIpFilter |
| hippo.ipfilter.disabled | Disables the site’s org.onehippo.forge.ipfilter.hst.IpFilter |