Fork me on GitHub

Using the IP Filter plugin


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’.

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.

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 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 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 file:

# Configuration file for Hippo IP Filter Plugin.
# Set up this file for Hippo CMS and/or site application using either:
# - system property (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

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