Skip to content

Block bad visitors with CrowdSec

How-toDeployrr v6.0+CurrentTraefikFirewallLogsSecurity

CrowdSec reads your logs and spots bad visitors, such as password guessers and scanners. It decides which IP addresses to ban. Two add-ons enforce the bans: the Firewall Bouncer blocks the address on your server, and the Traefik Bouncer makes Traefik refuse it. This page shows how to install all three, check they work, and get yourself unblocked.

To see why CrowdSec is worth running, watch Traefik 3 guide: why CrowdSec helps at 51:41 (manual setup). To understand how it works, read UDMS part 22: Understanding CrowdSec (manual setup, background only).

  • A Pro license. All three items need it. See Licenses.
  • All Prerequisites steps are done.
  • For Firewall Bouncer: CrowdSec is installed and running.
  • For Traefik Bouncer: CrowdSec and Traefik are both running. See Set up Traefik.
  • Install Traefik before CrowdSec if you can. CrowdSec reads the Traefik logs only if they exist when you install it. See Read the Traefik logs.

If something is missing, Deployrr shows a Requirements Not Met box that lists it. For example: “License - Pro required” or “CrowdSec - Must be running (Security menu)”.

Open Security from the main menu. The CrowdSec items sit under their own heading. Once installed, CrowdSec and Traefik Bouncer show RUNNING or STOPPED after their name. Firewall Bouncer shows RUNNING while its service runs, and nothing when it is stopped. The main menu also shows a status next to Security, such as CrowdSec Active or 1 Auth + 2 CrowdSec.

  1. Select CrowdSec (“Open-source Collaborative IPS”).
  2. Read the CrowdSec Console box. Connecting to the CrowdSec console (a free web account) is optional. You need it only to share bad IPs with the community and to see metrics online. The box also says that journalctl will be replaced with rsyslog for logging. It has two buttons:
    • Yes, Proceed continues the install.
    • No, Go Back returns to the menu, so you can create the account first.
  3. If you want the console, create an account at https://app.crowdsec.net and add a Security Engine. The page shows an enroll command. Copy the key after -e context.
  4. Select Yes, Proceed.
  5. At “Enter the enroll context key”, paste your key. Leave it empty to skip the console.
  6. If CrowdSec is already installed, Deployrr asks: “CrowdSec appears to be already installed. Do you want to reinstall/reconfigure it? WARNING: This will reset your CrowdSec configuration.” Say no unless you want to start over. If you say yes while CrowdSec runs, the terminal may also ask whether to “force reset the status and continue with installation of CrowdSec”. Answer y.
  7. In the Port Configuration box, accept the suggested port. The default is 8080. Deployrr suggests the first free port from there. On a reinstall, the port CrowdSec uses now counts as taken, so CrowdSec moves to a new port. See After you reinstall CrowdSec.
  8. Wait. The install pulls the image and can take a few minutes. It also installs rsyslog.
  9. If you gave a console key, Deployrr says “Enrollment requires manual approval on CrowdSec Console”. Open https://app.crowdsec.net, approve the enrollment, and press any key. It continues by itself after 120 seconds.
  10. Wait for “All done with CrowdSec setup!”.

During the install, Deployrr prints which logs CrowdSec will watch. It adds each of these only if the file exists on your server:

  • /var/log/auth.log
  • /var/log/syslog
  • /var/log/kern.log
  • /var/log/ufw.log
  • /var/log/mail.log
  • The Traefik logs, from logs/HOSTNAME/traefik/ in your Docker folder. This happens when traefik.log or access.log exists there.

If the Traefik logs are missing, Deployrr says “No Traefik logs found at …” and “Skipping Traefik log acquisition”. Install Traefik, then run CrowdSec again. Running it again means answering Yes to the reinstall question in step 6. That resets your CrowdSec configuration, and the enrollment key prompt appears again. If you already installed a bouncer, run it again afterwards, as in After you reinstall CrowdSec.

CrowdSec also never bans these addresses:

  • Your public IP at install time.
  • 127.0.0.1.
  • The private IPv4 ranges 192.168.0.0/16, 10.0.0.0/8 and 172.16.0.0/12.
  • The private IPv6 ranges fe80::/10 and fc00::/7. The install message lists only the IPv4 ranges, but they are in the file.

If Deployrr can’t read your public IP, it warns “Could not determine public WAN IP - using placeholder”. The list then keeps a placeholder instead of your IP. Replace it in the file below.

The list is appdata/crowdsec/config/parsers/s02-enrich/custom-whitelists.yaml in your Docker folder. Single IPs go under ip: and ranges go under cidr:.

The Firewall Bouncer blocks banned addresses at your server’s firewall. It runs as a service on your server, not as a container.

  1. Select Firewall Bouncer (“Firewall Bouncer for CrowdSec”).
  2. If it is already running, Deployrr asks “Do you want to reinstall it?” and warns that this will regenerate the API key. Say yes only if you want that. Reinstalling deletes the bouncer’s old key and creates a new one.
  3. Wait through the eight steps. Deployrr adds the CrowdSec package source, creates a key for the bouncer, installs the package and starts the service. It shows “API key extracted successfully (stored securely)” and never prints the key.
  4. Wait for “Firewall Bouncer service is active and running”.
  5. Read the Current CrowdSec bouncers list that follows. It should include firewall-bouncer-HOSTNAME, where HOSTNAME is your server’s name.

If you see “Firewall Bouncer service failed to start”, see The Firewall Bouncer won’t start.

What the Firewall Bouncer does to a banned visitor:

  • It covers the INPUT and DOCKER-USER firewall chains. That includes ports that Docker publishes.
  • It blocks banned IPv4 addresses. Packets are dropped without an answer. The page hangs or times out. This is general behavior of a DROP rule, not a Deployrr message.
  • It does not block IPv6 addresses.

The Traefik Bouncer makes Traefik check every visitor against CrowdSec before it reaches an app.

  1. Back up your Docker folder first. See Backups.

  2. Select Traefik Bouncer (“Traefik Bouncer for CrowdSec”).

  3. Read the CrowdSec Traefik Bouncer Setup box. It lists what Deployrr will change:

    • The main compose file.
    • The Traefik compose file. Deployrr adds the CrowdSec plugin there.
    • The CrowdSec compose file.
    • The Traefik rules folder. Deployrr adds the file middlewares-crowdsec-bouncer.yml.
  4. Select Yes to continue.

  5. If the bouncer is already installed, Deployrr asks whether to reinstall it and warns that this will regenerate the API key. Reinstalling deletes the old key and creates a new one.

  6. At Add to Chain Files?, choose Yes unless you edit your chains by hand. Deployrr then adds middlewares-crowdsec-bouncer as the first middleware of every chain-*.yml file in your Traefik rules folder. That includes chain-no-auth, chain-basic-auth, and the Authelia, Authentik, Google OAuth and TinyAuth chains if you installed them.

    Chain files created or replaced later don’t get it. See A chain file lost the bouncer.

    If you choose No, the bouncer is not applied until you add it. Deployrr says: “manually add middlewares-crowdsec-bouncer as the first middleware in your chain files.”

  7. Wait while Deployrr restarts CrowdSec and Traefik. It says “Traefik container restarted and running”. If Traefik is slow, it says “Traefik may not have fully started”. In that case, read the Traefik logs.

  8. Read the Current CrowdSec bouncers list. It should include traefik-bouncer-HOSTNAME.

Expect your apps to be unreachable for a short moment while Traefik restarts. Deployrr does not show a message about this. A banned visitor now gets a 403 Forbidden from Traefik.

By default, middlewares-crowdsec-bouncer.yml trusts 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. The plugin does not check visitors from trusted addresses, so your own network is not checked.

To see how a middleware chain takes extra middlewares such as CrowdSec, watch Traefik middlewares and chains at 18:20 (manual setup). To understand why the bouncer is a Traefik plugin and not a container, read UDMS part 25: Why the plugin is better than the container (manual setup, background only).

For how the chain names relate to login methods, see Choose a login method. To allow only some addresses in the first place, see Allow only some IP addresses to reach an app.

Each command comes in two forms. The short alias works if you installed the Deployrr bash aliases. The long form works anywhere. It is equivalent, and Deployrr prints the same form in its own messages. The aliases run through Docker Compose, and the long form calls Docker directly.

  1. Open Security again. CrowdSec, Firewall Bouncer and Traefik Bouncer should each show RUNNING. For the Traefik Bouncer, RUNNING does not prove that CrowdSec accepts the bouncer’s key. Step 2 checks that.

  2. List the registered bouncers:

    Terminal window
    csbouncers
    Terminal window
    sudo docker exec -t crowdsec cscli bouncers list

    You should see one firewall-bouncer-HOSTNAME and one traefik-bouncer-HOSTNAME, depending on what you installed.

  3. Check the Firewall Bouncer service:

    Terminal window
    csfbstatus
    Terminal window
    sudo systemctl status crowdsec-firewall-bouncer.service

    A healthy systemd service says active (running). That is general systemd output.

  4. List current bans. An empty list is normal on a quiet server. That is general CrowdSec behavior.

    Terminal window
    csdecisions
    Terminal window
    sudo docker exec -t crowdsec cscli decisions list
  5. Test a block. This uses general CrowdSec commands, not a Deployrr feature. Find the public IPv4 address of a device that is not on your home network, such as a phone on mobile data. Ban it for five minutes. Replace TEST_IP with that address:

    Terminal window
    cscli decisions add --ip TEST_IP --duration 5m
    Terminal window
    sudo docker exec -t crowdsec cscli decisions add --ip TEST_IP --duration 5m

    Wait a short while, then open one of your apps from that device. With the Traefik Bouncer you should see 403 Forbidden. With the Firewall Bouncer the page should hang or time out. Then remove the ban:

    Terminal window
    cscli decisions delete --ip TEST_IP
    Terminal window
    sudo docker exec -t crowdsec cscli decisions delete --ip TEST_IP

Deployrr says: “When an IP is blocked, you will see [CSFB_BLOCK] in the logs.” If you installed the aliases, tailkern follows /var/log/kern.log and tailcsfb follows /var/log/crowdsec-firewall-bouncer.log. For the Traefik Bouncer, run sudo docker logs traefik. See Read the Traefik logs.

In the commands below, replace DOCKER_FOLDER with the path to your Docker folder and HOSTNAME with your server’s hostname.

Deployrr says “Firewall Bouncer service failed to start”. Read the service log:

Terminal window
sudo journalctl -u crowdsec-firewall-bouncer -n 50

The bouncer runs on your server and talks to CrowdSec through the port CrowdSec publishes. It fails when that port or its key is wrong. Check both:

  1. Check that CrowdSec runs. Open Security. CrowdSec should show RUNNING.

  2. Compare the ports. The first command shows the address the bouncer uses. The second shows the port CrowdSec uses now. The two port numbers must match.

    Terminal window
    sudo grep api_url /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
    Terminal window
    sudo grep CROWDSEC_PORT DOCKER_FOLDER/.env
  3. Check that the key is still registered. Run csbouncers (or sudo docker exec -t crowdsec cscli bouncers list). The list should show firewall-bouncer-HOSTNAME.

  4. If the ports differ or the bouncer is missing from the list, open Security > Firewall Bouncer again. It writes a fresh configuration with the current port and a new key. If it asks “Do you want to reinstall it?”, say yes.

If Deployrr stops earlier with “Failed to create Firewall Bouncer API key” and “Check if CrowdSec container is running properly”, CrowdSec isn’t running or isn’t ready yet. Start CrowdSec, wait a minute, and run Firewall Bouncer again.

On Arch Linux, Deployrr installs the bouncer package from the AUR with yay or paru. If you have neither, it says “No AUR helper found. Please install crowdsec-firewall-bouncer-iptables manually from AUR.” Install that package yourself, then run Firewall Bouncer again.

Running Security > CrowdSec again and answering yes to the reinstall question affects both bouncers:

  • The port changes. The port CrowdSec used counts as taken, so Deployrr suggests the next free one. If you type the old port, it says the port is already in use and takes the suggestion. The Firewall Bouncer still points to the old port and can no longer reach CrowdSec.
  • The CrowdSec compose file is replaced. The new one no longer has the traefik_proxy network that the Traefik Bouncer added. Traefik can then no longer reach CrowdSec. Depending on the plugin’s settings, visitors may get errors or go through unchecked.

The registered bouncers stay in CrowdSec’s data, so csbouncers still lists them. Don’t rely on that. After a CrowdSec reinstall:

  1. Open Security > Firewall Bouncer and let it run. If it asks “Do you want to reinstall it?”, say yes.
  2. Open Security > Traefik Bouncer. Answer Yes to the setup box and to the reinstall question. It adds the network back and creates a new key. At Add to Chain Files?, choose Yes. Chain files that already have the bouncer are skipped.
  3. Run the checks in Check it worked.

Warnings during the Traefik Bouncer install

Section titled “Warnings during the Traefik Bouncer install”

Most of these don’t stop the install, and the step still ends with a success line. Fix each one by hand. Then run the command in the Fix column.

dcrec traefik and dcrec crowdsec need the Deployrr bash aliases. Without them, run sudo docker compose --profile all -f DOCKER_FOLDER/docker-compose-HOSTNAME.yml up -d --force-recreate traefik. For CrowdSec, end the command with crowdsec instead.

Message What is missing Fix
“Could not find PLUGINS-PLACEHOLDER-DO-NOT-DELETE in Traefik compose” The plugin lines in compose/HOSTNAME/traefik.yml. Without them, Traefik can’t load the CrowdSec plugin. Apps that use a chain with the bouncer may stop working. Add the plugin lines below. Then run dcrec traefik.
“Could not find basic_auth_credentials in Traefik compose, manual addition may be needed” The bouncer key in the secrets: list of the Traefik service. Add - crowdsec_bouncer_traefik_key to that list, in line with the other entries. Then run dcrec traefik.
“Could not find networks section in CrowdSec compose” The traefik_proxy network in compose/HOSTNAME/crowdsec.yml. This only happens when the file was edited by hand and has no networks: section. Add a networks: section to the CrowdSec service, at the same indent as ports:, with - default and - traefik_proxy below it. See the example below the table. Then run dcrec crowdsec.
“CrowdSec did not become ready in time” Nothing was finished. Deployrr stopped. Check sudo docker logs crowdsec, then run Traefik Bouncer again.
“No chain files found in …” or “Could not find inner middlewares section in chain-….yml” The bouncer in your chain files. See A chain file lost the bouncer.
“Bouncer may not appear in list yet, this is normal” Probably nothing. Run csbouncers after a minute. traefik-bouncer-HOSTNAME should be listed.

The plugin lines go in the command: section of the Traefik service in compose/HOSTNAME/traefik.yml. Put them at the end of that section, just before ports:, with the same six-space indent as the other lines:

# CrowdSec Bouncer Plugin
- --experimental.plugins.crowdsec.modulename=github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin
- --experimental.plugins.crowdsec.version=${TRAEFIKBOUNCER_VERSION_PIN}

The Traefik Bouncer install sets TRAEFIKBOUNCER_VERSION_PIN in your .env file.

The networks: section of the CrowdSec service in compose/HOSTNAME/crowdsec.yml uses a four-space indent, like ports::

networks:
- default
- traefik_proxy

Back up a file before you edit it. If Traefik doesn’t come back, put the backup back and run dcrec traefik. See Read the Traefik logs.

The Traefik Bouncer adds itself to the chain files that exist when you install it. These later actions replace a chain file with one that has no bouncer:

  • Running Proxy > Traefik > Preparation again replaces chain-no-auth.yml and chain-basic-auth.yml.
  • Installing or reinstalling Authelia, Authentik, Google OAuth or TinyAuth writes that login app’s chain file.

CrowdSec no longer checks apps that use such a chain, and nothing tells you. To list the chain files that don’t have the bouncer:

Terminal window
sudo grep -L middlewares-crowdsec-bouncer DOCKER_FOLDER/appdata/traefik3/rules/HOSTNAME/chain-*.yml

No output means every chain file has it. To fix the files listed, choose one:

  • Open Security > Traefik Bouncer again, answer Yes to the reinstall question, and choose Yes at Add to Chain Files?. This also creates a new bouncer key and restarts CrowdSec and Traefik.

  • Or edit each listed file. Back it up first. Add - middlewares-crowdsec-bouncer as the first entry under the inner middlewares: line, with the same indent as the other entries. For example:

    http:
    middlewares:
    chain-no-auth:
    chain:
    middlewares:
    - middlewares-crowdsec-bouncer
    - middlewares-rate-limit
    - middlewares-secure-headers

    Traefik watches the rules folder and picks up the change by itself. If an app stops loading, put the backup back and read the Traefik logs.

Run the grep again after you change a login app or rerun Preparation.

If CrowdSec bans your own address, work from another network or from the server’s console, then remove the ban.

  1. Find your public IP. Use a “what is my IP” site from the blocked device. This is general advice.

  2. Check that it is listed:

    Terminal window
    csdecisions
  3. Delete the ban. Replace YOUR_IP with your public IP:

    Terminal window
    cscli decisions delete --ip YOUR_IP
    Terminal window
    sudo docker exec -t crowdsec cscli decisions delete --ip YOUR_IP
  4. To stop it happening again, add your address to custom-whitelists.yaml (see the path above). Put a single IP under ip: and a range under cidr:. Then restart CrowdSec. This step is general CrowdSec practice, not something Deployrr documents:

    Terminal window
    sudo docker restart crowdsec

If your home IP changes, the address Deployrr whitelisted at install time no longer matches your connection. You can add the new one by hand as above. Or run Security > CrowdSec again and answer yes to the reinstall question (step 6 of the install). It rebuilds the file with your current public IP. It also resets your CrowdSec configuration, and your bouncers need to be run again. See After you reinstall CrowdSec. Adding the IP by hand is simpler.

These aliases need the Deployrr bash aliases and a CrowdSec installed by Deployrr. For the full list, see Bash aliases.

Alias What it does
csdecisions Lists current bans.
csalerts Lists alerts CrowdSec has raised.
csinspect ALERT_ID Shows one alert in detail. Replace ALERT_ID with an ID from csalerts.
csbouncers Lists registered bouncers.
csmetrics Shows CrowdSec metrics.
csmachines Lists machines linked to CrowdSec.
cshubs Lists hub items.
csparsers Lists installed parsers.
cscollections Lists installed collections.
cshubupdate Updates the hub index.
cshubupgrade Upgrades all hub items.
cscli Runs any cscli command inside the CrowdSec container. Use it for cscli decisions delete --ip YOUR_IP.
csfbstatus Shows the Firewall Bouncer service status.
csfbstart, csfbstop, csfbrestart Starts, stops or restarts the Firewall Bouncer.
tailcsfb Follows the Firewall Bouncer log.

The cscli alias runs this command. Replace DOCKER_FOLDER with the path to your Docker folder and HOSTNAME with your server’s hostname. The other cs* aliases build on it:

Terminal window
sudo docker compose --profile all -f DOCKER_FOLDER/docker-compose-HOSTNAME.yml exec -t crowdsec cscli