ConfigServer Security & Firewall (CSF) is a popular and powerful firewall solution for Linux servers. This repo contains complete installation guides, and also numerous patches for Docker and OpenVPN firewall support so that you can allow traffic between these services without interruption.
- Summary
- ConfigServer Firewall Features
- How The Patcher Works
- Install ConfigServer Firewall
- Testing the Firewall
- Configuring CSF
- Enabling CSF Firewall
- Managing the Firewall
- Uninstalling CSF
- Enable CSF Firewall Web UI
- Install Docker Patch
- Install OpenVPN Patch
- Download ConfigServer Firewall
- References for More Help
- Contributors ✨
This repository contains several folders:
- 📁
extras: The official CSFconfig.conf - 📁
patches: Custom patches- Docker
- OpenVPN Server
Each release posted on the Releases Page contains two files:
csf-firewall-vxx.xx.tgz- This is the latest version of ConfigServer Firewall. You do not need this if you already have CSF installed on your system.
csf-firewall-vx.x.x-patches.zip- The patches contained in this repository, which include the files:
- 📄 csfpost.sh
- 📄 csfpre.sh
- 📄 docker.sh
- 📄 install.sh
- 📄 openvpn.sh
- 📄 README.md
- 📄 LICENSE
- The patches contained in this repository, which include the files:
This guide will help you with the following:
- Install CSF (ConfigServer Firewall)
- Install CSF WebUI interface
- Install patches
- Docker Integration
- OpenVPN Integration
- Straight-forward SPI iptables firewall script
- Daemon process that checks for login authentication failures for:
- Courier imap, Dovecot, uw-imap, Kerio
- openSSH
- cPanel, WHM, Webmail (cPanel servers only)
- Pure-ftpd, vsftpd, Proftpd
- Password protected web pages (htpasswd)
- Mod_security failures (v1 and v2)
- Suhosin failures
- Exim SMTP AUTH
- Custom login failures with separate log file and regular expression matching
- POP3/IMAP login tracking to enforce logins per hour
- SSH login notification
- SU login notification
- Excessive connection blocking
- UI Integration for cPanel, DirectAdmin, InterWorx, CentOS Web Panel (CWP), VestaCP, CyberPanel - and Webmin
- Easy upgrade between versions from within the control panel
- Easy upgrade between versions from shell
- Pre-configured to work on a cPanel server with all the standard cPanel ports open
- Pre-configured to work on a DirectAdmin server with all the standard DirectAdmin ports open
- Auto-configures the SSH port if it’s non-standard on installation
- Block traffic on unused server IP addresses – helps reduce the risk to your server
- Alert when end-user scripts sending excessive emails per hour – for identifying spamming scripts
- Suspicious process reporting – reports potential exploits running on the server
- Excessive user processes reporting
- Excessive user process usage reporting and optional termination
- Suspicious file reporting – reports potential exploit files in /tmp and similar directories
- Directory and file watching – reports if a watched directory or a file changes
- Block traffic on a variety of Block Lists including DShield Block List and Spamhaus DROP List
- BOGON packet protection
- Pre-configured settings for Low, Medium or High firewall security (cPanel servers only)
- Works with multiple ethernet devices
- Server Security Check – Performs a basic security and settings check on the server (via cPanel/- DirectAdmin/Webmin UI)
- Allow Dynamic DNS IP addresses – always allow your IP address even if it changes whenever you connect to the internet
- Alert sent if server load average remains high for a specified length of time
- mod_security log reporting (if installed)
- Email relay tracking – tracks all email sent through the server and issues alerts for excessive usage (cPanel servers only)
- IDS (Intrusion Detection System) – the last line of detection alerts you to changes to system and application binaries
- SYN Flood protection
- Ping of death protection
- Port Scan tracking and blocking
- Permanent and Temporary (with TTL) IP blocking
- Exploit checks
- Account modification tracking – sends alerts if an account entry is modified, e.g. if the password is changed or the login shell
- Shared syslog aware
- Messenger Service – Allows you to redirect connection requests from blocked IP addresses to preconfigured text and html pages to inform the visitor that they have been blocked in the firewall. This can be particularly useful for those with a large user base and help process support requests more efficiently
- Country Code blocking – Allows you to deny or allow access by ISO Country Code
- Port Flooding Detection – Per IP, per Port connection flooding detection and mitigation to help block DOS attacks
- WHM root access notification (cPanel servers only)
- lfd Clustering – allows IP address blocks to be automatically propagated around a group of servers running lfd. It allows allows cluster-wide allows, removals and configuration changes
- Quick start csf – deferred startup by lfd for servers with large block and/or allow lists
- Distributed Login Failure Attack detection
- Temporary IP allows (with TTL)
- IPv6 Support with ip6tables
- Integrated UI – no need for a separate Control Panel or Apache to use the csf configuration
- Integrated support for cse within the Integrated UI
- cPanel Reseller access to per reseller configurable options Unblock, Deny, Allow and Search IP address blocks
- System Statistics – Basic graphs showing the performance of the server, e.g. Load Averages, CPU Usage, Memory Usage, etc
- ipset support for large IP lists
- Integrated with the CloudFlare Firewall
- …lots more!
You can read this if you want, or skip it. It outlines exactly how the patches work:
- Download all the files in the
/patchfolder to your system. - Set the
install.shfile to be executable.sudo chmod +x install.sh
- Run the
install.shscriptsudo ./install.sh- The script will first check to see if you have ConfigServer Firewall and all of its prerequisites installed. It will install them if they are not installed. This includes:
- ConfigServer Firewall
- ipset package
- iptables / ip6tables package
- Two new files will be added:
/usr/local/csf/bin/csfpre.sh/usr/local/csf/bin/csfpost.sh
- The patches will then be moved onto your system in the locations:
/usr/local/include/csf/post.d/docker.sh/usr/local/include/csf/post.d/openvpn.sh
- The
Dockerpatch will first check to ensure you have the following:- Must have Docker installed
- This script will NOT install docker. You must do that.
- Must have a valid docker network adapter named
docker*orbr-*
- Must have Docker installed
- The
OpenVPNpatch will first check to ensure you have the following:- Must have OpenVPN Server installed
- Must have a valid network tunnel named
tun*(tun0, tun1, etc) - Must have an outside network adapter named either
eth*orenp* - If any of the checks above are not true, OpenVPN patcher will skip
- You can check your list of network adapters using any of the commands below:
ip link showifconfig
- You can check if OpenVPN server is installed by using the commmand:
openvpn --version
- You can check your list of network adapters using any of the commands below:
- If you attempt to run the
install.shany time after the initial setup:- The script will check if ConfigServer Firewall and all prerequisites are installed.
- If they are not installed; they will be installed.
- If they are already installed; nothing will happen. The script does NOT update your packages. It installs the latest version of each package from the time that you run the script and do not already have ConfigServer Firewall installed.
- The script will look at all of the files it added the first time and check the MD5 hash.
- If the
csfpre,csfpost, or patch files do not exist; they will be re-added to your system. - If the patch files are different from the one the patcher comes with, you will be prompted / asked if you wish to overwrite your already installed copy
- If the patch files are the same as the ones which comes with the patcher; nothing will be done and it will skip that step.
- If the
- The script will check if ConfigServer Firewall and all prerequisites are installed.
When you start up the CSF service, the csfpost.sh file will loop through every patch / file added to the post.d folder, and run the code inside of those files. The code inside each patch contains iptable / firewall rules which allow that app to communicate between your system and the outside world.
Even if you were to completely wipe your iptable rules, as soon as you restart the CSF service; those rules will be added right back.
You can install ConfigServer Firewall and all prerequisites one of two ways:
If you would like to install ConfigServer Firewall using this repo's patcher; download the patch:
git clone https://github.com/Aetherinox/csf-firewall.gitSet the permissions for the install.sh file:
sudo chmod +x /csf-firewall/patch/install.shRun the script:
sudo ./csf-firewall/patch/install.shIf ConfigServer Firewall is not already installed on your system; you should see:
Installing package iptables
Installing package ipset
Installing package ConfigServer Firewall
Docker patch will now start ...
These steps explain how to install ConfigServer Firewall manually.
- A Linux server running CentOS, Debian, Ubuntu, or any other compatible Linux distribution.
- Root access or a user account with sudo privileges.
- Perl installed on your server. If Perl is not installed, you can install it by running the following commands:
-
For CentOS/RHEL:
sudo yum install perl ipset
-
For Debian/Ubuntu:
sudo apt-get update sudo apt-get install perl ipset
-
To download and install CSF, follow these steps:
- Log in to your server via SSH.
- Download the latest version of CSF using the wget command:
wget https://download.configserver.com/csf.tgz
- Extract the downloaded archive:
tar -xzf csf.tgz
- Navigate to the extracted directory:
cd csf - Run the installation script:
sudo sh install.sh
CSF will now be installed on your server, along with its Web UI (ConfigServer Firewall & Security) if you have a control panel like cPanel or DirectAdmin installed.
Before enabling and configuring CSF, it is crucial to test whether it is compatible with your server. Run the following command to initiate the test:
sudo perl /usr/local/csf/bin/csftest.plThe test will check for any potential issues or conflicts. If the test completes successfully, you will see the message “RESULT: csf should function on this server.” If there are any problems, the test will provide information on how to resolve them.
Now that CSF is installed, you can start configuring it to suit your server’s requirements. The main configuration file for CSF is located at /etc/csf/csf.conf. You can use your preferred text editor to modify the file, such as nano or vim:
sudo nano /etc/csf/csf.confSome essential settings you may want to modify include:
Note
When you run the patcher install.sh; TESTING MODE will automatically be disabled after everything as successfully completed.
TESTING: Set this value to 0 to disable testing mode and activate the firewall.TCP_INandTCP_OUT: These settings define the allowed incoming and outgoing TCP ports, respectively. Add or remove ports as required, separated by commas.UDP_INandUDP_OUT: These settings define the allowed incoming and outgoing UDP ports, respectively. Add or remove ports as required, separated by commas.DENY_IP_LIMIT: This setting defines the maximum number of IP addresses that can be listed in the /etc/csf/csf.deny file. Adjust this limit as needed.CT_LIMIT: This setting controls the number of connections from a single IP address that are allowed before the IP is temporarily blocked. Adjust this value according to your server’s requirements.
These are just a few of the numerous configuration options available in CSF. Make sure to review the configuration file and adjust the settings to suit your server’s needs. After making changes to the configuration file, save and exit the text editor.
Once you have configured the CSF firewall, it is time to enable it. To do so, run the following command:
sudo csf -eThis command will restart the CSF and LFD (Login Failure Daemon) services, applying your configuration changes and activating the firewall.
CSF provides several commands to manage the firewall, such as:
sudo csf -ssudo csf -fsudo csf -rsudo csf -lsudo csf -a IP_ADDRESSsudo csf -ar IP_ADDRESSsudo csf -d IP_ADDRESSsudo csf -dr IP_ADDRESSsudo csf -td IP_ADDRESSsudo csf -tr IP_ADDRESSThese commands can help you manage your server’s security and monitor incoming and outgoing traffic.
If you decide to uninstall CSF for any reason, follow these steps:
- Navigate to the CSF directory:
cd /etc/csf - Run the uninstallation script:
sudo sh uninstall.sh
The script will remove CSF and its associated files from your server.
ConfigServer Firewall offers a WebUI for the managing firewall from the web interface. This section explains how to install the WebUI.
CSF UI required some of Perl modules to be installed on your system. Use the following commands to install required modules as per your operating system.
Debian based systems:
sudo apt-get install libio-socket-ssl-perl libcrypt-ssleay-perl \
libnet-libidn-perl libio-socket-inet6-perl libsocket6-perlRedhat based systems:
sudo yum install perl-IO-Socket-SSL.noarch perl-Net-SSLeay perl-Net-LibIDN \
perl-IO-Socket-INET6 perl-Socket6To enable CSF web UI edit /etc/csf/csf.conf file in your favorite text editor and update the following values.
sudo vim /etc/csf/csf.conf# 1 to enable, 0 to disable web ui
UI = "1"
# Set port for web UI. The default port is 6666, but
# I change this to 1025 to easy access. Default port create some issue
# with popular chrome and firefox browser (in my case)
UI_PORT = "1025"
# Leave blank to bind to all IP addresses on the server
UI_IP = ""
# Set username for authetnication
UI_USER = "admin"
# Set a strong password for authetnication
UI_PASS = "admin"
Change the following values to your own:
UI_PORTUI_USERUI_PASS
After making changes, edit /etc/csf/ui/ui.allow configuration file and add your public IP to allow access to CSF UI. Change YOUR_PUBLIC_IP_ADDRESS with your public IP address.
sudo echo "YOUR_PUBLIC_IP_ADDRESS" >> /etc/csf/ui/ui.allowWeb UI works under lfd daemon. So restart the lfd daemon on your system using the following command.
sudo service lfd restartIn order to gain access to the online admin panel; you must ensure lfd and csf are running. You can check by running the commands:
sudo service lfd statusYou should see the lfd service running:
● lfd.service - ConfigServer Firewall & Security - lfd
Loaded: loaded (/lib/systemd/system/lfd.service; enabled; preset: enabled)
Active: active (running) since Mon 2024-08-05 11:59:38 MST; 1s ago
Process: 46393 ExecStart=/usr/sbin/lfd (code=exited, status=0/SUCCESS)
Main PID: 46407 (lfd - sleeping)
Tasks: 8 (limit: 4613)
Memory: 121.7M
CPU: 2.180s
CGroup: /system.slice/lfd.service
Next, confirm csf service is also running:
sudo service csf statusCheck the output for errors on service csf. You should see no errors:
● csf.service - ConfigServer Firewall & Security - csf
Loaded: loaded (/lib/systemd/system/csf.service; enabled; preset: enabled)
Active: active (exited) since Mon 2024-08-05 12:04:09 MST; 1s ago
Process: 46916 ExecStart=/usr/sbin/csf --initup (code=exited, status=0/SUCCESS)
Main PID: 46916 (code=exited, status=0/SUCCESS)
CPU: 12.692s
If you see the following error when running csf status:
csf[46313]: open3: exec of /sbin/ipset flush failed: No such file or directory at /usr/sbin/csf line 5650.
You must install ipset:
sudo apt-get update
sudo apt-get install ipsetNow, access CSF UI on your browser with the specified port. For this tutorial; we used 1025 port and accessed the CSF admin panel by opening our browser and going to:
https://127.0.0.1:1025
When prompted for the username and password; the default is:
| Field | Value |
|---|---|
| Username | admin |
| Password | admin |
After successful login, you will find the screen like below.
Allow IP Address: You can use below option to allow any IP quickly. This action adds the entry to the /etc/csf/csf.allow file.
Deny IP Address: You can use below option to deny any IP quickly. This action adds the entry to the /etc/csf/csf.deny file.
Unblock IP Address: You can use below option to quickly unblocked any IP which is already blocked by CSF.
After you have installed CSF, the WebUI, and enabled both lfd and csf services; it's now time to run the docker patcher. The docker patch will check your docker configuration, and add a series of iptable rules so that docker can communicate with the outside world and users can access your containers.
The docker patch does several things:
- Allows for you to restart CSF without having to restart your docker containers.
- Scans every container you have set up in docker and adds a whitelist firewall rule
Within your server, change to whatever directory where you want to download everything (including patch):
cd $HOME/DocumentsClone the repo
git clone https://github.com/Aetherinox/csf-firewall.gitThe Docker patch will automatically be installed if you run the /patch/install.sh script. It is the 2nd step in the process, right after it sets up the pre and post scripts.
If you wish to manually install it, you may run the following commands:
sudo chmod +x /patch/docker.sh
sudo ./patch/docker.shThe /patch/docker.sh file has a few configs you can adjust. Open it in a text editor and change the values to your preference.
DOCKER_INT="docker0"
NETWORK_MANUAL_MODE="false"
NETWORK_ADAPT_NAME="traefik"
CSF_FILE_ALLOW="/etc/csf/csf.allow"
CSF_COMMENT="Docker container whitelist"
DEBUG_ENABLED="false"
IP_CONTAINERS=(
'172.17.0.0/16'
)Each setting is defined below:
| Setting | Description |
|---|---|
DOCKER_INT |
main docker network interface |
NETWORK_MANUAL_MODE |
set true if you are manually assigning the ip address for each docker container |
NETWORK_ADAPT_NAME |
requires NETWORK_MANUAL_MODE="true" name of the adapter you are specifying |
CSF_FILE_ALLOW |
Path to your csf.allow file |
CSF_COMMENT |
comment added to each new whitelisted docker ip |
DEBUG_ENABLED |
debugging / better logs |
IP_CONTAINERS |
list of ip address blocks you will be using for your docker setup. these blocks will be whitelisted through ConfigServer Firewall |
Set the permissions (if needed)
sudo chmod +x /patch/install.shRun the script:
cd /patch/
sudo ./install.shYou can also try:
sudo sh install.shThe docker.sh file will be installed to /usr/local/include/csf/post.d
You can manually run the docker.sh script. It will also allow you to specify arguments such as --dev to get more detailed logging as the firewall is set up. This should only be done if you know what you're doing.
sudo chmod +x /usr/local/include/csf/post.d/docker.sh
sudo /usr/local/include/csf/post.d/docker.shYou can call arguments by running the file using:
sudo /usr/local/include/csf/post.d/docker.sh --devYou can also find out what version you are running by appending --version to either the install.sh or docker.sh file:
./patch/install.sh --versionConfigServer Firewall Configuration - v2.0.0.0
https://github.com/Aetherinox/csf-firewall
Ubuntu | 24.04sudo /usr/local/include/csf/post.d/docker.sh --versionConfigServer Firewall Docker Patch - v2.0.0.0
https://github.com/Aetherinox/csf-firewall
Ubuntu | 24.04This script includes debugging prints / logs. To view these, restart csf.service by running the following command in terminal:
sudo csf -rAll steps performed by the script will be displayed in terminal:
+ POSTROUTING Adding IPs from primary IP list
+ 172.17.0.0/16
+ RULE: -t nat -A POSTROUTING ! -o docker0 -s 172.17.0.0/16 -j MASQUERADE
+ RULE: -t nat -A POSTROUTING -s 172.17.0.0/16 ! -o docker0 -j MASQUERADE
---------------------------------------------------------------------------------------------------
+ BRIDGES Configuring network bridges
BRIDGE e8a57188323a
DOCKER INTERFACE docker0
SUBNET 172.17.0.0/16
+ RULE: -t nat -A POSTROUTING -s 172.17.0.0/16 ! -o docker0 -j MASQUERADE
+ RULE: -t nat -A DOCKER -i docker0 -j RETURN
+ RULE: -A DOCKER-ISOLATION-STAGE-1 -i docker0 ! -o docker0 -j DOCKER-ISOLATION-STAGE-2
+ RULE: -A DOCKER-ISOLATION-STAGE-2 -o docker0 -j DROPThis repo includes an OpenVPN patch which automatically sets up ConfigServer Firewall to accept connections from your OpenVPN server; while still restricting other incoming and outgoing connections you may not want going through.
Within your server, change to whatever directory where you want to download everything (including patch):
cd $HOME/DocumentsClone the repo
git clone https://github.com/Aetherinox/csf-firewall.gitThe OpenVPN patch will automatically be installed if you run the /patch/install.sh script. It is the 3rd step in the process, right after the Docker Patch.
If you wish to manually install it, you may run the following commands:
sudo chmod +x /patch/openvpn.sh
sudo ./patch/openvpn.shThe /patch/openvpn.sh file has a few configs you can adjust. Open it in a text editor and change the values to your preference.
ETH_ADAPTER=$(ip route | grep default | sed -e "s/^.*dev.//" -e "s/.proto.*//")
TUN_ADAPTER=$(ip -br l | awk '$1 ~ "^tun[0-9]" { print $1}')
IP_PUBLIC=$(curl ipinfo.io/ip)
DEBUG_ENABLED="false"
IP_POOL=(
'10.8.0.0/24'
)Each setting is defined below:
| Setting | Description |
|---|---|
ETH_ADAPTER |
primary network adapter |
TUN_ADAPTER |
openvpn tunnel adapter |
IP_PUBLIC |
server's public ip address |
DEBUG_ENABLED |
debugging / better logs |
IP_POOL |
openvpn ip pool |
The script tries to automatically detect the values specified above, however, you can manually specify your own values.
As an example, instead of automatically detecting your server's public IP address or ethernet adapters, you can specify your own by changing the following:
# old code
ETH_ADAPTER=$(ip route | grep default | sed -e "s/^.*dev.//" -e "s/.proto.*//")
TUN_ADAPTER=$(ip -br l | awk '$1 ~ "^tun[0-9]" { print $1}')
IP_PUBLIC=$(curl ipinfo.io/ip)
# manually specified ip
ETH_ADAPTER="eth0"
TUN_ADAPTER="tun0"
IP_PUBLIC="216.55.100.5"After changing the values re-run install.sh
Set the permissions (if needed)
sudo chmod +x /patch/install.shRun the script:
cd /patch/
sudo ./install.shYou can also try:
sudo sh install.shThe openvpn.sh file will be installed to /usr/local/include/csf/post.d
You can manually run the openvpn.sh script. It will also allow you to specify arguments such as --dev to get more detailed logging as the firewall is set up. This should only be done if you know what you're doing.
sudo chmod +x /usr/local/include/csf/post.d/openvpn.sh
sudo /usr/local/include/csf/post.d/openvpn.shYou can call arguments by running the file using:
sudo /usr/local/include/csf/post.d/openvpn.sh --devYou can also find out what version you are running by appending --version to either the install.sh or openvpn.sh file:
./patch/install.sh --versionConfigServer Firewall Configuration - v2.0.0.0
https://github.com/Aetherinox/csf-firewall
Ubuntu | 24.04sudo /usr/local/include/csf/post.d/openvpn.sh --versionConfigServer Firewall OpenVPN Patch - v2.0.0.0
https://github.com/Aetherinox/csf-firewall
Ubuntu | 24.04This script includes debugging prints / logs. To view these, restart csf.service by running the following command in terminal:
sudo csf -rAll steps performed by the script will be displayed in terminal:
+ OPENVPN Adding OpenVPN Rules
+ RULE -A INPUT -i tun+ -j ACCEPT
+ RULE -A FORWARD -i tun+ -j ACCEPT
+ RULE -A FORWARD -o tun0 -j ACCEPT
+ RULE -t nat -A POSTROUTING -o enp0s3 -j MASQUERADE
+ RULE -A FORWARD -i tun+ -o enp0s3 -m state --state RELATED,ESTABLISHED -j ACCEPT
+ RULE -A FORWARD -i enp0s3 -o tun+ -m state --state RELATED,ESTABLISHED -j ACCEPT
+ RULE -t nat -A POSTROUTING -j SNAT --to-source XX.XXX.XXX.XXX
+ RULE -t nat -A POSTROUTING -s 10.8.0.0/24 -o enp0s3 -j MASQUERADEThe latest version of csf can be downloaded from:
If you need additional help apart from this guide to configure CSF; use the following pages for more help:
- Chapter 1: How to Install and Configure CSF Firewall on Linux
- Chapter 2: How to Enable CSF Firewall Web UI
We are always looking for contributors. If you feel that you can provide something useful to Gistr, then we'd love to review your suggestion. Before submitting your contribution, please review the following resources:
Want to help but can't write code?
- Review active questions by our community and answer the ones you know.
The following people have helped get this project going:
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent