Introduction to IPSETs¶
This section explains the purpose of IPSETs, and how they benefit you as a server administrator compared to using file-based allow, deny, or blocklists.
About IPSETs¶
When managing a firewall with CSF, you’ll often need to block or allow large numbers of IP addresses or networks. Traditionally, this has been done through file-based lists. When CSF is started, those lists are read into memory, and each IP or CIDR is added as a separate rule in the iptables firewall. As an example:
# # # Example /etc/csf/csf.deny # # # Block a single IP 192.0.2.15 # Block a range of IPs 203.0.113.0/24 # Block with a comment 198.51.100.42 # Suspicious SSH brute force # Block an entire subnet 10.0.0.0/8 If you were to configure the IP addresses listed in the example above within the file /etc//csf/csf.deny and then started up CSF, then CSF would automatically convert that list into iptable rules, and would run the following:
# Block a single IP iptables -A INPUT -s 192.0.2.15 -j DROP # Block a range of IPs iptables -A INPUT -s 203.0.113.0/24 -j DROP # Block with a comment (the comment is ignored by iptables, shown here for clarity) iptables -A INPUT -s 198.51.100.42 -j DROP # Suspicious SSH brute force # Block an entire subnet iptables -A INPUT -s 10.0.0.0/8 -j DROP While this method works, it becomes inefficient when the list grows large. Every incoming or outgoing connection must be checked against each iptables rule, and once the list reaches thousands of entries, it can noticeably slow down your server’s networking performance.
This is where IPSETs come in. An ipset is a special data structure in the Linux kernel that allows you to group many IP addresses, networks, or ranges together, and then reference that group with a single firewall rule. Instead of adding thousands of rules into iptables, CSF can load all of those addresses into an ipset and apply them collectively. This approach is dramatically more efficient, reduces CPU usage, and speeds up packet filtering even when working with massive blocklists.
The key difference is in how the firewall stores and processes the data. A traditional blocklist tells the firewall: “check this IP against every single rule until you find a match.”
An ipset, on the other hand, works more like a fast lookup table: “check if this IP is in the set; if so, apply the rule.” This makes IPSETs especially useful for geographical blocks, abusive IP feeds, or any large-scale list that would otherwise overwhelm a rule-based blocklist.
For many users, blocklists are still perfectly fine if you only manage a handful of entries or want to manually add or remove individual IPs. But if you plan to use automated feeds, block entire regions, or maintain thousands of entries, IPSETs are the better option. They give you the same control as blocklists, but with far less overhead and much better scalability.
It is also recommended that you enable IPSET if you plan on using any of the settings within the CSF config file /etc/csf/csf.conf listed below:
CC_DENYCC_ALLOWCC_ALLOW_FILTER
Notice to Virtuozzo & OpenVZ Users
It's highly unlikely that ipset will function on Virtuozzo/OpenVZ containers even if it has been installed
Install¶
Before you can begin using IPSETs with CSF, you’ll need to ensure the ipset package is installed on your server. Many modern Linux distributions already include IPSET support in the kernel by default, and in some cases the user-space tools (ipset command) are installed out of the box. If not, you can easily install them using your system’s package manager. Or you can build the source from http://ipset.netfilter.org/.
You can install IPSET with the following commands based on your Linux distro:
Once installed, verify that IPSET is available by running:
If installation was successful, this command will display the current running version number. This confirms that your system is ready to start creating and managing IPSETs for CSF.
Enable¶
Once the ipset package is installed, the next step is to enable IPSET support within CSF. By default, CSF ships with IPSETs disabled, so you’ll need to update the configuration file to turn it on.
Open the CSF configuration /etc/csf/csf.conf file in your preferred text editor:
Locate LF_IPSET and change the value from 0 to 1:
After saving your changes, give CSF a restart:
Enabling IPSETs allows CSF to offload large blocklists into efficient kernel-managed sets, significantly improving performance compared to standard iptables rules. This step is essential before you can begin adding and managing IPSET-based blocklists.
Configuration¶
If you have decided to use IPSET integration with CSF; there are a few settings you need to make note of. We'll explain those settings in brief detail here.
LF_IPSET¶
As explained in the previous section Enable IPSET, this setting is what enables IPSET integration within CSF. To use any IPSET feature, you must set this to 1.
Open /etc/csf/csf.conf and change the following:
LF_IPSET_MAXELEM¶
The LF_IPSET_MAXELEM setting defines the maximum number of entries that can be stored within each IPSET created by CSF.
- Setting this value too low may prevent full blocklists from loading, reducing your protection.
- Setting it too high can increase memory usage and potentially affect system performance.
By default, this value is set to 65536 (approximately sixty-five thousand entries per IPSET).
To determine the best value for your system, review the blocklists you plan to enable. In this example, we’ll reference our in-house blocklists:
- master.ipset approximately 350,000 entries
- highrisk.ipset approximately 10,000 entries
The master.ipset blocklist contains roughly 350,000 entries, while highrisk.ipset contains around 10,000.
Since LF_IPSET_MAXELEM applies to each IPSET individually, you should base your configuration on the largest blocklist you intend to use.
For example, because master.ipset has about 350,000 entries, that becomes our minimum requirement. To account for growth as blocklists are updated daily, it’s best to include a buffer.
In this case, we’ll set the value to 500,000 — allowing room for future expansion.
- 350,000 entries = master.ipset (largest blocklist)
- 150,000 entry buffer = for list growth and flexibility
Open /etc/csf/csf.conf and change the following:
This setting is the equivilent to running the following IPSET command manually:
LF_IPSET_HASHSIZE¶
This setting defines the internal hash table size used by each IPSET that CSF creates. It determines how efficiently IP addresses are stored and looked up within each list.
By default, this value is set to 1024.
A larger hash table allows the system to find IPs faster and reduces lookup collisions, but it also increases memory usage.
The value must always be a power of 2 (such as: 1024, 2048, 4096, etc.).
Users often get confused by this setting LF_IPSET_HASHSIZE and the previously explained setting LF_IPSET_MAXELEM. It can be better explained as:
- LF_IPSET_MAXELEM How many books fit on the shelf (total entries allowed).
- LF_IPSET_HASHSIZE How many compartments that shelf is divided into (hash buckets for faster searching).
If your blocklists are small (a few thousand IPs), the default value of 1024 is usually sufficient.
If you are using very large blocklists (hundreds of thousands of entries), increasing this value to 2048 or 4096 can improve lookup performance and stability — at the cost of slightly higher RAM usage.
Open /etc/csf/csf.conf and change the following:
This setting is the equivilent to running the following IPSET command manually:
Build Lists¶
Once you have IPSET installed and enabled within CSF, it's time to populate your IPSET lists. These lists determine which connections are allowed to access your server and which ones will be denied. Populating your IPSET lists correctly helps ensure your firewall operates efficiently while providing strong protection.
There are two primary ways to add IPs to your IPSET lists:
-
- Pre-compiled lists of known malicious IPs.
- See the Blocklists section for more information about blocklists.
-
- Adding specific IPs or subnets you want to allow or deny via a command (or shell script for automation).
Using Blocklists¶
Blocklists are precompiled lists of IP addresses or networks known to be malicious or unwanted. They allow you to automatically deny or restrict traffic from these IPs without having to add each one manually.
For instructions on using official CSF blocklists or custom external blocklists to populate your IPSETs automatically, please refer to the Blocklists chapter. These lists can contain thousands or even millions of IP addresses and are automatically loaded into your IPSETs to save memory and improve firewall performance.
-
Blocklists in CSF allow you to automatically block connections from known malicious IP addresses, helping to protect your server from abusive traffic.
This chapter explains how to configure and use blocklists, including CSF’s official blocklist and third-party sources.
You’ll also learn how to enable blocklists with or without IPSET, ensuring they work efficiently no matter the size of the list.
Using Manual Additions¶
Unlike Blocklists which are a pre-compiled list of IPs you want to allow / deny, the other option is to manually add your own IP addresses to a list. To manually compile your own list, you can do so using the ipset command. This is useful for whitelisting trusted IPs or blocking specific addresses.
To do this, you need to:
- Create a list, this is where all of the IP addresses will be stored
- Add an IP to the list which is who will be allowed or denied access to your server
Create List¶
Create a custom IPSET (if it doesn’t already exist):
You can also expand on this command and specify that you want to store comments, or set a maximum allowed number of IPs in your list.
The following are some of the options you can use when creating your list:
my_whitelist-
- Name list / set you are creating.
- You will reference it later in commands like
ipset add,ipset list, or iniptablesrules.
hash:ip-
- Specifies the type of IP set.
- Other types:
hash:netfor networks, orlist:setfor nested sets.
comment-
- Allows each entry in the set to store a comment.
- Without this option, attempting to add a comment will fail.
hashsize 65536-
- Defines the initial size of the hash table.
- Determines how many “buckets” the hash table will initially have for storing IPs.
- Setting this properly improves performance for large sets:
- too small = collisions
- too large = slightly more memory used
- You can scale it based on the expected number of entries in the set.
Add IP to List¶
These commands let you add single IP addresses to your whitelist or blacklist:
Overlapping IP addresses
Even single IPs can overlap with ranges. Always ensure that whitelists are prioritized in your firewall rules so they aren’t accidentally blocked by broader blacklist ranges.
Adds the IP 192.0.2.15 to your whitelist, granting access to this single address.
If you created your IPSET list with the comment parameter, you can also add a comment to your entry.
Adds the IP 203.0.113.42 to your blacklist, blocking access from this single address.
If you created your IPSET list with the comment parameter, you can also add a comment to your entry.
Add Subnet Range to List¶
These commands let you add a range of IP addresses to either your whitelist or blacklist. This is especially useful when the source server owns multiple IPs within a network block.
Overlapping IP addresses
When working with ranges, overlapping IPs may exist between your whitelist and blacklist. The order of rules in your firewall matters—whitelisted IPs should be checked before blacklist rules to ensure access is correctly allowed.
Check IP in List¶
These commands allow you to confirm whether or not an IP already exists in one of your lists. It will return one of two responses:
192.0.2.15is in setmy_whitelist192.0.2.11is NOT in setmy_whitelist
You can also use a more complex command to search for an IP in any list. Change 1.2.3.4 to the IP you are looking for.
Show List¶
Once you have your lists created, you can print information about the lists or the number of IP addresses within the list by list name. To list all of your IPSET lists, run the command:
You can also show all of the IPs associated with a specific list, or return the total count.
# # # List all IPs in a specific set # # sudo ipset list my_whitelist Name: my_whitelist Type: hash:ip Revision: 6 Header: family inet hashsize 8192 maxelem 65536 comment bucketsize 12 initval 0x8d108d64 Size in memory: 448 References: 0 Number of entries: 1 Members: 192.0.2.15 comment "Localhost device" # # # Count entries # # sudo ipset list my_whitelist -o save | awk '/add/ {print $3}' | wc -l 1 # # # List all IPs in a specific set # # sudo ipset list my_blacklist Name: my_blacklist Type: hash:ip Revision: 6 Header: family inet hashsize 8192 maxelem 65536 comment bucketsize 12 initval 0x65606406 Size in memory: 448 References: 0 Number of entries: 1 Members: 203.0.113.42 comment "Suspicious SSH activity" # # # Count entries # # sudo ipset list my_blacklist -o save | awk '/add/ {print $3}' | wc -l 1
Enable or Disable List¶
Once you have your IPSET list created and have populated it with the addresses you want, it's time to enforce the list and add it to our iptable rules.
The following will enforce your whitelist, ensuring that all IPs within my_whitelist will be allowed through the INPUT and FORWARD chains.
sudo iptables -I INPUT -m set --match-set my_whitelist src -j ACCEPT sudo iptables -I FORWARD -m set --match-set my_whitelist src -j ACCEPT If you want to remove the rules and stop enforcing your whitelist, run the same command with the -D flag:
The following will enforce your blacklist, ensuring that all IPs within my_whitelist will be denied through the INPUT and FORWARD chains.
sudo iptables -I INPUT -m set --match-set my_blacklist src -j DROP sudo iptables -I FORWARD -m set --match-set my_blacklist src -j DROP If you want to remove the rules and stop enforcing your whitelist, run the same command with the -D flag:
From this point forward, your IPSET lists will be enforced.
- If a user with the IP
192.0.2.15tries to access your server; allow them - If a user with the IP
203.0.113.42tries to access your server; deny them
Delete IP from List¶
If you decide to remove an IP from your whitelist or blacklist, you can use the following commands:
Delete List¶
If you have decided that you no longer need an IPSET list, you need to remove the iptables rule, and then delete the IPSET list itself.
The following will remove your whitelist iptables rule
After deleting the iptables rule, we can delete the IPSET list:
Save List¶
You can save your entire IPSET list to a file which allows you to back it up and restore it later.
Restore List¶
If you would like to restore a backed up IPSET list, you can do so with the following commands:
Overwriting Existing Rules
If you attempt to import white or blacklisted IPs which are already in a list; the import will fail. The list must first be destroyed, or the IP must be deleted from the list before the import of that rule will be successful.
If you have an existing list that needs to be destroyed first and then import the list again; run the commands:
You can also restore, but ignore any errors that occur and continue importing the rest of the list. This means that duplicate IPs that already exist will be skipped, but any new IPs in the restore file that you may not already have, will be restored and added to the IPSET.
Flush List¶
Flushing an IPSET list differs from deleting.
- When you delete a list, you destroy the entire list and all IPs in the list.
- When you flush a list, you delete all IPs in the list, but keep the list itself intact so that you can add more IPs later.
To flush a list:
Rename List¶
You can change the name of a list with the following commands:
Apply Lists¶
By this point in the guide, you should have:
- Installed copy of CSF
- Installed IPSET package
- Enable ipset setting within /etc/csf/csf.conf
- Set maximum values in /etc/csf/csf.conf with appropriate values
- Configured and enabled desired blocklists
After everything above is done, give CSF a restart:
You should now have CSF running, IPSET properly configured, and your blocklists should be loaded and operational.
Troubleshooting¶
The following are a list of common issues or errors, and potential solutions for correcting these issues.
IPSET blocklist max IP count change does not take affect on next restart¶
When you enable a blocklist for the first, it must be defined within /etc/csf/csf.blocklists as the following:
In the example above:
| Value | Description |
|---|---|
CSF_HIGHRISK | Name of the blocklist |
43200 | Blocklist cache time. List will not be refreshed until this time expires. |
0 | Max IPs to load in a blocklist; 0 is unlimited |
https://blocklist.configserver.dev/highrisk.ipset | Blocklist to load |
After CSF is started, a list of IPs are fetched from the above URL and stored as a cached file within /var/lib/csf/. The cached file will take on the name of your loaded blocklist, such as /var/lib/csf/csf.block.CSF_HIGHRISK.
If you change the maximum number of IPs to load and want it to take affect immediately, you MUST delete the cached file /var/lib/csf/csf.block.CSF_HIGHRISK.
open3: exec of /sbin/ipset flush failed: No such file or directory at /usr/sbin/csf¶
This error means that you have enabled IPSET within CSF, but do not have the package itself installed. Open terminal and run the command:
Set cannot be destroyed: it is in use by a kernel component¶
This error appears when you try to delete an IPSET list while it’s still in use by iptables. Before removing the set itself, you must first delete any iptables rules that reference it. Run the following commands to detach the set from iptables:
sudo iptables -D INPUT -m set --match-set my_list src -j DROP sudo iptables -D FORWARD -m set --match-set my_list src -j DROP Then try to delete the IPSET list again:
Next Steps ¶
Select what documentation you would like to proceed with next ...
-
Blocklists in CSF allow you to automatically block connections from known malicious IP addresses, helping to protect your server from abusive traffic.
This chapter explains how to configure and use blocklists, including CSF’s official blocklist and third-party sources.
You’ll also learn how to enable blocklists with or without IPSET, ensuring they work efficiently no matter the size of the list.
-
Geographical IP Block Integration
Configure geographical restrictions in CSF to whitelist or blacklist specific regions from accessing your server.
This chapter covers enabling the GeoIP blocklist feature using third-party services such as MaxMind (requires an API key), db-ip, ipdeny, or iptoasn.
These services allow you to control access based on location while keeping your server secure.