This page is about Caddy 1, but Caddy 2 is now in beta. Click here for Caddy 2. Thank you for your patience as we transition!

User Guide


The ipfilter directive adds the ability to allow or block requests based on the client's IP address.

Full documentation


Filter a specific IP or a CIDR range.
ipfilter / { rule block ip 2001:db8::/122 }

caddy will block any clients with IPs that fall into one of these two ranges and 2001:db8::/122 , or a client that has an IP of explicitly.

Filter clients based on specified IPs stored as file names in the "prefix_dir".
ipfilter / { rule block prefix_dir blacklisted }

caddy will block any client IP that appears as a file name in the blacklisted directory. A relative pathname is relative to the CWD when caddy is started. When putting the blacklisted directory in the web server document tree you should also add an internal directive to ensure those files are not visible via HTTP GET requests. For example, internal /blacklisted/. You can also specify an absolute pathname to locate the blacklist directory outside the document tree. You can create the file in the root of the blacklist directory. This is known as using a "flat" namespace. For example, blacklisted/ or blacklisted/2601:647:4601:fa93:1865:4b6c:d055:3f3. However, putting thousands of files in a single directory may cause poor performance of the lookup function. So you can also, and should, use a "sharded" namespace. This involves creating the file in a subdirectory based on the first two components of the address. For example, blacklisted/127/0/ or blacklisted/2601/647/2601:647:4601:fa93:1865:4b6c:d055:3f3. Note that you can also whitelist IP addresses using this mechanism by specifying rule allow. This may be useful when it follows a more general blocking rule (e.g., by country) and you want to selectively allow some addresses through but don't want to hardcode the addresses in the Caddy config file. This mechanism is most useful when coupled with automated monitoring of your web server activity to detect signals that your server is under attack from malware. All your monitoring software has to do is create a file in the blacklist directory. At this time the content of the file is ignored. In the future the contents will probably be read and exposed as a placeholder variable for use in conjuction with a template to be filled in via the markdown directive. So you should consider putting some explanatory text in the file explaining why the address was blocked.

Filter clients based on their Country ISO Code
ipfilter / { rule allow database /data/GeoLite.mmdb country US JP }

with that in your Caddyfile caddy will only serve users from the United States or Japan. filtering with country codes requires a local copy of the Geo database, can be downloaded for free from MaxMind.

Define a block page
ipfilter / { rule allow blockpage default.html ip 2e80::20:f8ff:fe31:77cf }

caddy will serve only these 2 IPs, eveyone else will get default.html.

Multiple paths
ipfilter /notglobal /secret { rule allow ip }

Only serve under /notglobal and /secret.

Multiple blocks
ipfilter / { rule allow ip } ipfilter /webhook { rule allow ip }

You can use as many ipfilter blocks as you please, the above says: block everyone but, Unless it falls in and requesting a path in /webhook.

Related Links

Access the full documentation for this plugin off-site:

Plugin Help

Get help from the maintainers of the http.ipfilter plugin:

Plugin Website

Visit http.ipfilter's website for more information:

Plugin Author: Abdulelah
Last Updated: 26 Nov 2018, 10:09 PM
This plugin is independent of the Caddy project and is not endorsed or maintained by Caddy developers. Use at your own risk. Do not file issues for this plugin on Caddy's bug tracker.