# Firewall

ApisCP utilizes firewalld for its firewall. Rampart is a module that serves as a wrapper for fail2ban, a brute-force deterrent that blocks threats through firewalld. These two components act in tandem to keep your server secure while exercising some intelligence. Rampart is for ephemeral blocks that automatically expire after a fixed duration (see network/setup-firewall) whereas a separate firewalld permanent whitelist/blacklist is provided.

During installation, ApisCP will detect the connected IP address and whitelist it to avoid triggering a block by fail2ban, for example if you forget your password multiple times. If your IP address changes or you setup ApisCP from behind a proxy, then you can easily update the whitelist with cpcmd

cpcmd scope:set rampart.fail2ban-whitelist ''

To view active fail2ban whitelists use scope:get:

cpcmd scope:get rampart.fail2ban-whitelist

Whitelists may be IP address ( or CIDR range ( rampart.fail2ban-whitelist is an append-only operation. Edit /etc/fail2ban/jail.conf by hand to remove old IP addresses.

Firewall overview

# Whitelisting access

ApisCP restricts access to all ports except for well-known services (HTTP, FTP, mail, SSH) and optional services (CP, user daemons). A second whitelist, which allows access to blocked ports as well as overrides Rampart can be set using cpcmd rampart:whitelist:

cpcmd rampart:whitelist

These entries are permanent and supersede enforcement by fail2ban. A whitelist may be removed by specifying remove as the second parameter, e.g. rampart:whitelist '' 'remove'


Single quotes are not compulsory, but help the shell (Bourne shell) discriminate between boundary arguments. Certain metacharacters, such as $, (, ), ;, and | have special meaning.

# Delegated Whitelisting

Site Administrators can whitelist a limited number of IP addresses by through Account > Whitelisting. This value can be toggled per-site by adjusting rampart,max. If set to DEFAULT it inherits rampart,max service value. A few specific values for rampart,max imply specific meanings:

  • -1: unlimited whitelisting entries (OS limit)

  • 0: disable whitelisting

  • > 0: up to n whitelist entries

A whitelist trumps all other filters, including blacklists. Delegated whitelisting is hierarchically equivalent to an administrative whitelist via cpcmd rampart:whitelist. Each whitelist entry is held by a site. These values are codified in rampart,whitelist as a list of IPv4/IPv6 addresses. When a site is deleted, the whitelist is not released until all sites that hold a reference to the whitelist have been removed.

# Permit 20 whitelisted IPs to domain.com
EditDomain -c rampart,max=20 domain.com
# Allow otherdomain.com unlimited access
EditDomain -c rampart,max=-1 otherdomain.com

Additionally, rampart:whitelist() (without arguments) allows the caller to whitelist its public IP if not previously whitelisted. rampart:temp($ip = null, $duration = 7200) works similarly with a temporary whitelisting that deauthorizes after the set interval (default: 7200 seconds). These features may be invoked with Beacon to simplify batch scripting with dhcp clients.

# Blacklisting

A blacklist exists to explicitly deny addresses that are not blocked by Rampart's adaptive firewall.

cpcmd rampart:blacklist

Blacklists are lower priority than whitelist and higher priority than fail2ban. CIDR ranges also work and can be fed lists for example from IPdeny:

curl -o- http://www.ipdeny.com/ipblocks/data/countries/cn.zone | while read -r IP ; do cpcmd rampart:blacklist "$IP" ; done

All blacklist listings are permanent unless removed with cpcmd rampart:blacklist($ip, 'remove').

# Service filters

fail2ban monitors service logs for failed/anomalous logins. These are referred back to f2b-XXX ipsets when thresholds are reached. By default a 10 minute ban is applied if 3 or more logins occur in a 5 minute period. Specific jails may be overrode by setting per-jail values in Bootstrapper using the cp.bootstrapper Scope. fail2ban configuration variables follow a familiar pattern, f2b_ + jail name + _ + parameter.

All time values are in seconds

# Change monitoring interval to 15 minutes for Dovecot
cpcmd scope:set f2b_dovecot_findtime 900
# Change bantime for SSH to 1 hour
cpcmd scope:set f2b_sshd_bantime 3600
# Change malware trigger threshold to 5 hits
cpcmd scope:set f2b_malware_maxretry 5
# Apply settings
upcp -sb fail2ban/configure-jails

# Recidivism

"Recidivism" is a specific term derived from fail2ban's recidive jail for repeat offenders. If a user repeats a ban across any monitored service 5 times (f2b_recidive_maxretry) in 12 hours (f2b_recidive_findtime), then a 10-day ban (f2b_recidive_bantime) is applied. Values may be altered by changing the parenthesized value with a Scope.

# Ban recidive offenders for 1 month
cpcmd scope:set cp.bootstrapper f2b_recidive_bantime $((86400*30))
upcp -sb fail2ban/configure-jails

# Unbanning IP addresses

All IP addresses automatically unban from Rampart after a fixed duration. To manually unban an address from Rampart use cpcmd:

# Ban in recidive, which is a long-term ban > 1 week
cpcmd rampart:ban recidive
# Validate which jails is present in
cpcmd rampart:is-banned
# Unban from all jails
cpcmd rampart:unban

Permanent blacklist and whitelist entries can be removed with firewall-cmd

# Add to the permanent whitelist
cpcmd rampart:whitelist
# Show all whitelist entries
ipset list whitelist
# Remove from whitelist
cpcmd rampart:whitelist remove

# Public backdoor

ApisCP provides many means to unban an IP address for a legitimate user:

  1. Delegated Whitelisting as described above
  2. cp-proxy, if the proxy is installed on non-hosting server
  3. Automatic expiry as discussed in Service filters
  4. Whitelisted access to ApisCP on 2083 when always_permit_panel_login is True (disabled by default). A Scope, cp.whitelist-access exists to facilitate this. See SECURITY.md for security implications, specifically the Rampart subsystem of ApisCP that guards panel access.