108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# CrowdSec Troubleshooting
|
|
|
|
Keep Cerberus terminology and the Configuration Packages flow in mind while debugging Hub presets.
|
|
|
|
## Quick checks
|
|
|
|
- Cerberus is enabled and you are signed in with admin scope.
|
|
- `cscli` is available (preferred path); HTTPS CrowdSec Hub endpoints only.
|
|
- Docker images (v1.7.4+): cscli is pre-installed.
|
|
- Bare-metal deployments: install cscli for Hub preset sync or use HTTP fallback with HUB_BASE_URL.
|
|
- HUB_BASE_URL points to a JSON hub endpoint (default: <https://hub-data.crowdsec.net/api/index.json>). Redirects to HTML will be rejected.
|
|
- Proxy env is set when required: HTTP(S)_PROXY and NO_PROXY are respected by the hub client.
|
|
- For slow or proxied networks, increase HUB_PULL_TIMEOUT_SECONDS (default 25) and HUB_APPLY_TIMEOUT_SECONDS (default 45) to avoid premature timeouts.
|
|
- Preset workflow: pull from Hub using cache keys/ETags → preview changes → apply with automatic backup and reload flag.
|
|
- Preset pull/apply requires either cscli or cached presets.
|
|
- Offline/curated presets remain available at all times.
|
|
|
|
## Common issues
|
|
|
|
- Hub unreachable (503): retry once, then Charon falls back to cached Hub data if available; otherwise stay on curated/offline presets until connectivity returns.
|
|
- Hub returns HTML/redirect: set HUB_BASE_URL to the JSON endpoint above or install cscli so the index is fetched locally.
|
|
- Bad preset slug (400): the slug must match Hub naming; correct the slug before retrying.
|
|
- Apply failed: review the apply response and restore from the backup that was taken automatically, then retry after fixing the underlying issue.
|
|
- Apply not supported (501): use curated/offline presets; Hub apply will be re-enabled when supported in your environment.
|
|
- **Security Engine Offline**: If your dashboard says "Offline", it means CrowdSec LAPI is not running.
|
|
- **Fix**: Ensure CrowdSec is **enabled via GUI toggle** in the Security dashboard. Do NOT use environment variables.
|
|
- **Action**: Go to Security dashboard, toggle CrowdSec ON, wait 15 seconds, verify status shows "Active".
|
|
|
|
## Tips
|
|
|
|
- Keep the CrowdSec Hub reachable over HTTPS; HTTP is blocked.
|
|
- If you switch to offline mode, clear pending Hub pulls before retrying so cache keys/ETags refresh cleanly.
|
|
- After restoring from a backup, re-run preview before applying again to verify changes.
|
|
|
|
## Console Enrollment
|
|
|
|
### Prerequisites
|
|
|
|
Before attempting Console enrollment, ensure:
|
|
|
|
✅ **CrowdSec is enabled** — Toggle must be ON in Security dashboard
|
|
✅ **LAPI is running** — Check with: `docker exec charon cscli lapi status`
|
|
✅ **Feature flag enabled** — `feature.crowdsec.console_enrollment` must be ON
|
|
✅ **Valid token** — Obtain from crowdsec.net
|
|
|
|
### "missing login field" or CAPI errors
|
|
|
|
Charon automatically attempts to register your instance with CrowdSec's Central API (CAPI) before enrolling. Ensure your server has internet access to `api.crowdsec.net`.
|
|
|
|
### Enrollment shows "enrolled" but not on crowdsec.net
|
|
|
|
**Root cause:** LAPI was not running when enrollment was attempted.
|
|
|
|
**Solution:**
|
|
|
|
1. Verify LAPI status:
|
|
```bash
|
|
docker exec charon cscli lapi status
|
|
```
|
|
|
|
2. If LAPI is not running:
|
|
- Go to Security dashboard
|
|
- Toggle CrowdSec OFF
|
|
- Wait 5 seconds
|
|
- Toggle CrowdSec ON
|
|
- Wait 15 seconds
|
|
- Re-check LAPI status
|
|
|
|
3. Re-submit enrollment token (same token works!)
|
|
|
|
### CrowdSec won't start via GUI toggle
|
|
|
|
**Solution:**
|
|
|
|
1. Check container logs:
|
|
```bash
|
|
docker logs charon | grep -i crowdsec
|
|
```
|
|
|
|
2. Verify config directory:
|
|
```bash
|
|
docker exec charon ls -la /app/data/crowdsec/config
|
|
```
|
|
|
|
3. If missing, restart container:
|
|
```bash
|
|
docker compose restart
|
|
```
|
|
|
|
4. Remove any deprecated environment variables from docker-compose.yml:
|
|
```yaml
|
|
# REMOVE THESE:
|
|
- CHARON_SECURITY_CROWDSEC_MODE=local
|
|
- CERBERUS_SECURITY_CROWDSEC_MODE=local
|
|
```
|
|
|
|
5. Restart and try GUI toggle again
|
|
|
|
### Environment Variable Migration
|
|
|
|
🚨 **DEPRECATED:** The `CHARON_SECURITY_CROWDSEC_MODE` environment variable is no longer used.
|
|
|
|
If you have this in your docker-compose.yml, remove it and use the GUI toggle instead. See [Migration Guide](../migration-guide.md) for step-by-step instructions.
|
|
|
|
### Configuration File
|
|
|
|
Charon uses the configuration located in `data/crowdsec/config.yaml`. Ensure this file exists and is readable if you are manually modifying it.
|