CrowdSec Setup Guide¶
Protect your websites from hackers, bots, and other bad actors. This guide walks you through setting up CrowdSec with Charon—even if you've never touched security software before.
What Is CrowdSec?¶
Imagine a neighborhood watch program, but for the internet. CrowdSec watches the traffic coming to your server and identifies troublemakers—hackers trying to guess passwords, bots scanning for vulnerabilities, or attackers probing your defenses.
When CrowdSec spots suspicious behavior, it blocks that visitor before they can cause harm. Even better, CrowdSec shares information with thousands of other users worldwide. If someone attacks a server in Germany, your server in California can block them before they even knock on your door.
What CrowdSec Catches:
- 🔓 Password guessing — Someone trying thousands of passwords to break into your apps
- 🕷️ Malicious bots — Automated scripts looking for security holes
- 💥 Known attackers — IP addresses flagged as dangerous by the global community
- 🔍 Reconnaissance — Hackers mapping out your server before attacking
How Charon Makes It Easy¶
Here's the good news: Charon handles most of the CrowdSec setup automatically. You don't need to edit configuration files, run terminal commands, or understand networking. Just flip a switch in the Settings.
What Happens Behind the Scenes¶
When you enable CrowdSec in Charon:
- Charon starts the CrowdSec engine — A security service begins running inside your container
- A "bouncer" is registered — This allows Charon to communicate with CrowdSec (more on this below)
- Your websites are protected — Bad traffic gets blocked before reaching your apps
- Decisions sync in real-time — You can see who's blocked in the Security dashboard
All of this happens in about 15 seconds after you flip the toggle.
Quick Start: Enable CrowdSec¶
Prerequisites:
- Charon is installed and running
- You can access the Charon web interface
Steps:
- Open Charon in your browser (usually
http://your-server:8080) - Click Security in the left sidebar
- Find the CrowdSec card
- Flip the toggle to ON
- Wait about 15 seconds for the status to show "Active"
That's it! Your server is now protected by CrowdSec.
✨ New in Recent Versions
Charon now automatically generates and registers your bouncer key the first time you enable CrowdSec. No terminal commands needed—just flip the switch and you're protected!
Verify It's Working¶
After enabling, the CrowdSec card should display:
- Status: Active (with a green indicator)
- PID: A number like
12345(this is the CrowdSec process) - LAPI: Connected
If you see these, CrowdSec is running properly.
Installing a Hub Preset (Optional)¶
- Go to Settings → Security → Hub Presets and pick a preset.
- Click Pull to download and preview it.
- Click Apply. Charon installs exactly what you previewed.
Most installs take a few seconds. Charon takes a backup first and puts everything back if the install fails or takes longer than 120 seconds. If you see a message you do not understand, check Hub preset messages. More details are in the CrowdSec feature guide.
Understanding "Bouncers" (Important!)¶
A bouncer is like a security guard at a nightclub door. It checks each visitor's ID against a list of banned people and either lets them in or turns them away.
In CrowdSec terms:
- The CrowdSec engine decides who's dangerous and maintains the ban list
- The bouncer enforces those decisions by blocking bad traffic
Critical Point: For the bouncer to work, it needs a special password (called an API key) to communicate with the CrowdSec engine. This key must be generated by CrowdSec itself—you cannot make one up.
✅ Good News: Charon Handles This For You!
When you enable CrowdSec for the first time, Charon automatically:
- Starts the CrowdSec engine
- Registers a bouncer and generates a valid API key
- Saves the key so it survives container restarts
You don't need to touch the terminal or set any environment variables.
⚠️ Common Mistake Alert
If you set
CHARON_SECURITY_CROWDSEC_API_KEY=mySecureKey123in your docker-compose.yml, it won't work for a made-up value. CrowdSec has never heard of "mySecureKey123" and will reject it. Charon then creates its own key and saves it, and the made-up value is ignored.Solution: Remove any manually-set API key and let Charon generate one automatically. If you do want your own key, see Providing Your Own Key.
How Auto-Registration Works¶
When you flip the CrowdSec toggle ON, here's what happens behind the scenes:
- Charon starts CrowdSec and waits for it to be ready
- A bouncer is registered with the name
caddy-bouncer - The API key is saved to
/app/data/crowdsec/bouncer_key - Caddy connects using the saved key
Your Key Is Saved Forever¶
The bouncer key is stored in your data volume at:
This means:
- ✅ Your key survives container restarts
- ✅ Your key survives Charon updates
- ✅ You don't need to re-register after pulling a new image
Finding Your Key in the Logs¶
When Charon registers a new bouncer key, it writes a short notice to the container logs:
Look for a section like this:
════════════════════════════════════════════════════════════════════
🔐 CrowdSec Bouncer Registered Successfully
────────────────────────────────────────────────────────────────────
Bouncer Name: caddy-bouncer
Saved To: /app/data/crowdsec/bouncer_key
────────────────────────────────────────────────────────────────────
⚠️ SECURITY: Full API key saved to file (permissions: 0600)
────────────────────────────────────────────────────────────────────
💡 TIP: Charon saved this key and uses it. If docker-compose.yml still
sets an old CrowdSec key variable, remove it.
🔄 ROTATE: Change API keys regularly and never commit to version control
════════════════════════════════════════════════════════════════════
To see the full key, open the CrowdSec card on the Security page and click the copy button.
If the line says Not Saved instead of Saved To, Charon could not write the key file. Give Charon write access to the data folder, then restart CrowdSec.
Providing Your Own Key (Advanced)¶
This is optional and not needed for a normal setup, since Charon generates and registers a key for you. If you prefer to use your own pre-registered bouncer key, you can set it as an environment variable:
How it works:
- If Charon already has a saved key that CrowdSec accepts, that saved key is kept and your variable is ignored (Charon logs a note).
- If there is no working saved key, Charon checks your key with CrowdSec. If CrowdSec accepts it, Charon saves it. If CrowdSec rejects it, Charon creates its own key instead.
- To switch to your key later, change the variable and delete the saved file
/app/data/crowdsec/bouncer_key. Then restart Charon.
⚠️ Important: This key must be registered with CrowdSec first using
cscli bouncers add. See Manual Bouncer Registration for details.
Viewing Your Bouncer Key in the UI¶
Need to see your bouncer key? Charon makes it easy:
- Open Charon and go to Security
- Look at the CrowdSec card
- Your bouncer key is displayed (masked for security)
- Click the copy button to copy the full key to your clipboard
This is useful when:
- 🔧 Troubleshooting connection issues
- 📋 Sharing the key with another application
- ✅ Verifying the correct key is in use
Environment Variables Reference¶
Here's everything you can configure for CrowdSec. For most users, you don't need to set any of these—Charon's defaults work great.
Safe to Set¶
| Variable | Description | Default | When to Use |
|---|---|---|---|
CHARON_SECURITY_CROWDSEC_CONSOLE_KEY |
Your CrowdSec Console enrollment token | None | When enrolling in CrowdSec Console (optional) |
Do NOT Set Manually¶
| Variable | Description | Why You Should NOT Set It |
|---|---|---|
CHARON_SECURITY_CROWDSEC_API_KEY |
Bouncer authentication key | Must be generated by CrowdSec, not invented |
CHARON_SECURITY_CROWDSEC_MODE |
Enable/disable mode (retired) | Retired. Use the CrowdSec Protection switch on the Security page instead |
Correct Docker Compose Example¶
services:
charon:
image: ghcr.io/wikid82/charon:latest
container_name: charon
restart: unless-stopped
ports:
- "8080:8080" # Charon web interface
- "80:80" # HTTP traffic
- "443:443" # HTTPS traffic
volumes:
- ./data:/app/data
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
- CHARON_ENV=production
# ✅ CrowdSec is enabled via the GUI, no env vars needed
# ✅ API key is auto-generated, never set manually
Manual Bouncer Registration¶
In rare cases, you might need to create the key yourself instead of letting Charon do it. This is useful if:
- You're recovering from a broken configuration
- Automatic registration failed
Most people should skip this section. Charon creates and saves its own key automatically.
How it works: You paste the key into your compose file. Charon then checks it with CrowdSec, and saves it if CrowdSec accepts it. The check at startup always uses the CrowdSec engine inside Charon.
Step 1: Open the Container Terminal¶
Step 2: Create the Key¶
CrowdSec prints a key that looks something like this:
Api key for 'caddy-bouncer':
f8a7b2c9d3e4a5b6c7d8e9f0a1b2c3d4
Please keep it safe, you won't be able to retrieve it!
If CrowdSec says the bouncer already exists, first delete it with the steps in How to Delete and Re-Register a Bouncer, then run this command again.
Copy the key now and keep it safe. Then type exit to leave the container terminal.
Step 3: Put the Key in Your Compose File¶
Open your docker-compose.yml and add this line under environment: (replace the example text with your key):
Charon uses this variable only when it does not already have a working saved key. Once Charon has saved the key, you can leave the line in place.
Step 4: Restart Charon¶
Step 5: Check the Result¶
Open the Security page and look at the CrowdSec card. It should show a bouncer key and say it is registered.
- If CrowdSec does not accept your key, Charon makes its own key instead. Check the key in your compose file for typos, or delete that line and let Charon register its own key.
- If the card shows an error about saving the key, give Charon write access to the data folder, then restart CrowdSec.
CrowdSec Console Enrollment (Optional)¶
The CrowdSec Console is a free online dashboard where you can:
- 📊 View attack statistics across all your servers
- 🌍 See threats on a world map
- 🔔 Get email alerts about attacks
- 📡 Subscribe to premium blocklists
Getting Your Enrollment Key¶
- Go to app.crowdsec.net and create a free account
- Click Engines in the sidebar
- Click Add Engine
- Copy the enrollment key (a long string starting with
clapi-)
Enrolling Through Charon¶
- Open Charon and go to Security
- Click on the CrowdSec card to expand options
- Find Console Enrollment
- Paste your enrollment key
- Click Enroll
Within 60 seconds, your instance should appear in the CrowdSec Console.
Enrollment via Command Line¶
If the GUI enrollment isn't working:
Replace YOUR_ENROLLMENT_KEY with the key from your Console.
Troubleshooting¶
"Access Forbidden" Error¶
Symptom: Logs show "API error: access forbidden" when CrowdSec tries to connect.
Cause: The bouncer API key is invalid or was never registered with CrowdSec.
Solution:
- Check if you're manually setting an API key:
- If you find one, remove it:
-
Follow the Manual Bouncer Registration steps above
-
Restart the container:
"Connection Refused" to LAPI¶
Symptom: CrowdSec shows "connection refused" errors.
Cause: CrowdSec is still starting up (takes 30-60 seconds) or isn't running.
Solution:
-
Wait 60 seconds after container start
-
Check if CrowdSec is running:
-
If you see "connection refused," try toggling CrowdSec OFF then ON in the GUI
-
Check the logs:
Bouncer Status Check¶
To see all registered bouncers:
You should see caddy-bouncer with a "validated" status.
How to Delete and Re-Register a Bouncer¶
If the bouncer is corrupted or misconfigured:
# Delete the existing bouncer
docker exec charon cscli bouncers delete caddy-bouncer
# Restart. Charon registers a fresh key on its own.
docker restart charon
If the key file is still there and CrowdSec no longer accepts it, Charon replaces it automatically. To force a fresh key, also delete the file bouncer_key in the crowdsec folder inside your data folder before restarting.
Console Shows Engine "Offline"¶
Symptom: CrowdSec Console dashboard shows your engine as "Offline" even though it's running.
Cause: Network issues preventing heartbeats from reaching CrowdSec servers.
Check connectivity:
# Test DNS
docker exec charon nslookup api.crowdsec.net
# Test HTTPS connection
docker exec charon curl -I https://api.crowdsec.net
Required outbound connections:
| Host | Port | Purpose |
|---|---|---|
api.crowdsec.net |
443 | Console heartbeats |
hub.crowdsec.net |
443 | Security preset downloads |
If you're behind a corporate firewall, you may need to allow these connections.
Advanced Configuration¶
Using an External CrowdSec Instance (No Longer Supported)¶
Connecting Charon to a CrowdSec server you run somewhere else is not supported. If your compose file still has CHARON_SECURITY_CROWDSEC_API_URL, remove that line and restart Charon. Charon always talks to the CrowdSec engine that runs inside Charon, so this variable is ignored, and so is any CrowdSec address saved in Charon's settings. Charon writes a single warning to the log when the variable is set to another address.
Installing Security Presets¶
CrowdSec offers pre-built detection rules called "presets" from their Hub. Charon includes common ones by default, but you can add more:
- Go to Security → CrowdSec → Hub Presets
- Browse or search for presets
- Click Install on the ones you want
Popular presets:
- crowdsecurity/http-probing — Detect reconnaissance scanning
- crowdsecurity/http-bad-user-agent — Block known malicious bots
- crowdsecurity/http-cve — Protect against known vulnerabilities
Viewing Active Blocks (Decisions)¶
To see who's currently blocked:
In the GUI:
- Go to Security → Live Decisions
- View blocked IPs, reasons, and duration
Via Command Line:
Manually Banning an IP¶
If you want to block someone immediately:
GUI:
- Go to Security → CrowdSec
- Click Add Decision
- Enter the IP address
- Set duration (e.g., 24h)
- Click Ban
Command Line:
Unbanning an IP¶
If you accidentally blocked a legitimate user:
Summary¶
| Task | Method |
|---|---|
| Enable CrowdSec | Toggle in Security dashboard |
| Verify it's running | Check for "Active" status in dashboard |
| Fix "access forbidden" | Remove hardcoded API key, let Charon generate one |
| Register bouncer manually | docker exec charon cscli bouncers add caddy-bouncer |
| Enroll in Console | Paste key in Security → CrowdSec → Console Enrollment |
| View who's blocked | Security → Live Decisions |
Related Guides¶
- Web Application Firewall (WAF) — Additional application-layer protection
- Access Control Lists — Manual IP blocking and GeoIP rules
- Rate Limiting — Prevent abuse by limiting request rates
- CrowdSec Feature Documentation — Detailed feature reference