diff --git a/crowdsec-docs/unversioned/getting_started/health_check.mdx b/crowdsec-docs/unversioned/getting_started/health_check.mdx index 6bf9c3cb5..40d576d92 100644 --- a/crowdsec-docs/unversioned/getting_started/health_check.mdx +++ b/crowdsec-docs/unversioned/getting_started/health_check.mdx @@ -9,12 +9,12 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; -Health Check Version: 0.1.0 +Health Check Version: 0.2.0 -Welcome to the interactive Health-Check of your CrowdSec setup. -We'll guide you through a series of tests to ensure that your Security Stack is fully functional and ready to protect your services: -**Detecting**, **Threat Sharing** and **Remediating**. -*This guide covers cases of protecting common services such as web servers (HTTP) and SSH.* +Welcome to the interactive Health-Check of your CrowdSec setup. +We'll guide you through a series of tests to ensure that your Security Stack is fully functional and ready to protect your services: +**Detecting**, **Threat Sharing** and **Remediating**. +*This guide covers cases of protecting common services such as web servers (HTTP) and SSH.* We'll first test the final functionality of each component (top-down approach) before diving into detailed troubleshooting if issues arise. @@ -23,6 +23,10 @@ This health check is divided into three main sections: - [**๐Ÿ”— Connectivity**](#-crowdsec-connectivity-checks): Verifying communication with the CrowdSec network to receive the community blocklist. - [**๐Ÿ›ก๏ธ Protection**](#-remediation-checks): Confirming that your bouncers automatically block threats detected by CrowdSec +:::tip Your feedback matters! +Help us improve this health check guide by sharing your experience: [๐Ÿ“ **Health Check Feedback Form** โ†—๏ธ](https://forms.gle/DJboC7oisjmA8qt78) +::: + * * * ## ๐Ÿ“ก Detection checks @@ -40,11 +44,23 @@ We'll trigger the dummy scenario `crowdsecurity/http-generic-test` by accessing curl -I https://\/crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl 2๏ธโƒฃ Confirm the alert has triggered for the scenario `crowdsecurity/http-generic-test` -sudo cscli alerts list | grep crowdsecurity/http-generic-test -**Notes:** -- Requests from private IP addresses won't trigger alerts (private IPs are whitelisted by default). - - You can also test via a browser if easier, especially from another device. + + + sudo cscli alerts list -s crowdsecurity/http-generic-testss + + + docker exec crowdsec cscli alerts list -s crowdsecurity/http-generic-test + + + kubectl exec -n crowdsec -it $(kubectl get pods -n crowdsec -l k8s-app=crowdsec -l type=lapi -o name) -- cscli alerts list -s crowdsecurity/http-generic-test + + + +**Notes:** +- โš ๏ธ **Important**: Requests from **private IP addresses won't trigger alerts** (private IPs are whitelisted by default). + - If testing from localhost or your internal network (192.168.x.x, 10.x.x.x, 172.16.x.x), the test will fail. + - **Solution**: Test from an external device with a public IP address, or test via a browser from your phone using mobile data. - This scenario can be triggered again only after a 5-minutes delay. @@ -57,7 +73,19 @@ We'll trigger the dummy scenario `crowdsecurity/ssh-generic-test` by attempting ssh crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl@\ 2๏ธโƒฃ Confirm the alert has triggered for the scenario `crowdsecurity/ssh-generic-test` -sudo cscli alerts list | grep crowdsecurity/ssh-generic-test + + + + sudo cscli alerts list -s crowdsecurity/ssh-generic-test + + + docker exec crowdsec cscli alerts list -s crowdsecurity/ssh-generic-test + + + It's uncommon to have to deal with this scenario in Kubernetes, but if you do: + kubectl exec -n crowdsec -it $(kubectl get pods -n crowdsec -l k8s-app=crowdsec -l type=lapi -o name) -- cscli alerts list -s crowdsecurity/ssh-generic-test + + **Notes:** - This scenario can only be triggered again after a 5-minutes delay. @@ -66,7 +94,7 @@ We'll trigger the dummy scenario `crowdsecurity/ssh-generic-test` by attempting
๐Ÿ›ก๏ธ **AppSec** detection test - CrowdSec WAF -If you've enabled an AppSec-capable bouncer with CrowdSec WAF, you can trigger the `crowdsecurity/appsec-generic-test` dummy scenario. +If you've enabled an AppSec-capable bouncer with CrowdSec WAF with the [Virtual Patching collection](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching), you can trigger the `crowdsecurity/appsec-generic-test` dummy scenario. It would have triggered along with the HTTP detection test, but it is worth mentioning here as well. We'll trigger the dummy scenario `crowdsecurity/appsec-generic-test` by accessing a **probe path** on your web server. @@ -75,7 +103,18 @@ We'll trigger the dummy scenario `crowdsecurity/appsec-generic-test` by accessin curl -I https://\/crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl 2๏ธโƒฃ Confirm the alert has triggered for the scenario `crowdsecurity/appsec-generic-test` -sudo cscli alerts list | grep crowdsecurity/appsec-generic-test + + + + sudo cscli alerts list -s crowdsecurity/appsec-generic-test + + + docker exec crowdsec cscli alerts list -s crowdsecurity/appsec-generic-test + + + kubectl exec -n crowdsec -it $(kubectl get pods -n crowdsec -l k8s-app=crowdsec -l type=lapi -o name) -- cscli alerts list -s crowdsecurity/appsec-generic-test + + **Notes:** - This scenario can only be triggered again after a 1-minute delay. @@ -108,9 +147,22 @@ Were all the tests related to your setup successful? Multiple log sources can be defined in the acquisition(s) configuration files and they support diverse datasources (files, syslog, etc.). For more details you can refer to the [datasources documentation](https://doc.crowdsec.net/docs/next/log_processor/data_sources/intro). - We'll look at the security engine **metrics** to see if logs are **being read** and if what's read is **parsed correctly**. + We'll look at the security engine **metrics** to see if logs are **being read** and if what's read is **parsed correctly**. We'll do that using the `cscli metrics` command: - sudo cscli metrics show acquisition parsers + + + + sudo cscli metrics show acquisition parsers + + + docker exec crowdsec cscli metrics show acquisition parsers + + + + for i in $(kubectl get pods -n crowdsec -l k8s-app=crowdsec -l type=agent -o name); do kubectl exec -n crowdsec -it $i -- cscli metrics show acquisition parsers; done + + + Under **Acquisition Metrics** you should see: - The source name of the log files or streams that have been read and the number of lines read and parsed for each of them. @@ -136,99 +188,304 @@ Were all the tests related to your setup successful?
๐Ÿ“ฅ Acquisition Troubleshooting -- Are your logs properly declared as datasources - CrowdSec needs to know where to **read your logs**. This is handled by the **acquisition configuration**, usually found in `acquis.yaml` or in files under `acquis.d/` inside the CrowdSec config directory. - On Debian like OS it is typically located in `/etc/crowdsec/`. + CrowdSec needs to know where to **read your logs**. The configuration varies by deployment method: + + + - To troubleshoot: + The **acquisition configuration** is usually found in `acquis.yaml` or in files under `acquis.d/` inside the CrowdSec config directory. + On Debian-like OS it is typically located in `/etc/crowdsec/`. + + **To troubleshoot:** - The detailed doc about the acquisition configuration can be found [here](https://doc.crowdsec.net/docs/next/log_processor/acquisition/intro). - Check your acquisition files exist and that the datasources are properly setup. - - ๐Ÿ’ก Hint: + - ๐Ÿ’ก Hint: - The hub page of the collection you installed provides an example of the acquisition configuration file to create. - For example: - - The [NGINX collection hub page โ†—๏ธ](https://app.crowdsec.net/hub/author/crowdsecurity/collections/nginx) + - The [NGINX collection hub page โ†—๏ธ](https://app.crowdsec.net/hub/author/crowdsecurity/collections/nginx) - Or the [SSHD collection hub page โ†—๏ธ](https://app.crowdsec.net/hub/author/crowdsecurity/collections/sshd) (that is contained in the Linux Collection). - - Make sure that the **type** declared in the matches the **parser** expected to be used: nginx, apache, syslog, etc. + - Make sure that the **type** declared matches the **parser** expected to be used: nginx, apache, syslog, etc. + + + + + In Docker, logs must be accessible to the container through volumes. + + **Common issues:** + - **Missing volume mounts** & **Shared log volumes**: Ensure log directories are mounted in your container and available in multi-container setup. + Example if your service logs are in `/var/log` on the host or in a `logs` shared volume: + ```yaml + volumes: + - /var/log:/var/log:ro # Example for mounting logs as read-only + - logs:/logs:ro # Example for shared log volume between containers + ``` + - **Acquisition configuration**: Your `acquis.yaml` or `acquis.d/*.yaml` files should reference paths inside the container. + - **Log file permissions**: CrowdSec container user must have read access to log files. + + **To check your acquisition config:** + ```bash + docker exec crowdsec cat /etc/crowdsec/acquis.yaml # or acquis.d/*.yaml + ``` + + + + + In Kubernetes, CrowdSec reads logs from `/var/log/containers` which is mounted into pods by the helm chart. + + **Configuration is done in your Helm values file:** + ```yaml + agent: + acquisition: + - namespace: your-namespace + podName: your-pod-* + program: nginx # Reference used by the FILTER function of your installed parsers + ``` + + **Common issues:** + - **Wrong namespace or pod names**: Verify pods exist with `kubectl get pods -n ` + - **Incorrect program name**: The `program` field must match the FILTER of your installed parser (nginx, traefik, apache, etc.) + - **Container runtime mismatch**: Set `container_runtime: containerd` or `container_runtime: docker` in values.yaml + + **Note:** Unlike standalone deployments, you use `program:` instead of `type:` in Kubernetes acquisitions. + + + +
๐Ÿ“ฆ Collection Troubleshooting -- Are the right parsers and scenarios installed? CrowdSec, via its [**Hub** โ†—๏ธ](https://app.crowdsec.net/hub/collections) uses collections to package correct parsers and detection scenarios for your services. - - On regular **host** installations, CrowdSec usually detects your services (like nginx or ssh) and installs the appropriate collections automatically. - - On **Docker**, **Kubernetes**, or **custom setups**, you may need to install them manually. - #### ๐Ÿ” To check what's currently installed: - sudo cscli collections list + + - You can also list individual parsers and scenarios with: - sudo cscli parsers list - sudo cscli scenarios list - - - Look for entries related to your service (e.g., nginx, apache, ssh). - - If theyโ€™re listed, the right collection is likely installed. + On regular **host** installations, CrowdSec usually detects your services (like nginx or ssh) and installs the appropriate collections automatically. - #### ๐Ÿ“ฅ Install missing collections - 1. Visit the [CrowdSec Hub โ†—๏ธ](https://hub.crowdsec.net/) and search for a collection matching your service, like: - - [nginx โ†—๏ธ](https://app.crowdsec.net/hub/author/crowdsecurity/collections/nginx) - - [apache โ†—๏ธ](https://app.crowdsec.net/hub/author/crowdsecurity/collections/apache) - - [linux โ†—๏ธ](https://app.crowdsec.net/hub/author/crowdsecurity/collections/linux) - - etc... - 2. Follow the installation instructions on the collectionโ€™s page, including any required acquisition setup. + **๐Ÿ” To check what's currently installed:** + ```bash + sudo cscli collections list + ``` + + You can also list individual parsers and scenarios with: + ```bash + sudo cscli parsers list + sudo cscli scenarios list + ``` - #### โš ๏ธ Log format mismatch - - If your logs donโ€™t follow the expected format (e.g., theyโ€™ve been customized), CrowdSec might not parse them properly. - - You can find more information on how to create your own parsers in the [CrowdSec documentation](https://doc.crowdsec.net/docs/next/log_processor/parsers/format). + - Look for entries related to your service (e.g., nginx, apache, ssh). + - If they're listed, the right collection is likely installed. + + **๐Ÿ“ฅ Install missing collections:** + 1. Visit the [CrowdSec Hub โ†—๏ธ](https://hub.crowdsec.net/) and search for a collection matching your service + 2. Install with: + ```bash + sudo cscli collections install crowdsecurity/nginx + sudo systemctl reload crowdsec + ``` + + + + + In Docker, collections must be installed via the `COLLECTIONS` environment variable. + + **๐Ÿ” To check what's currently installed:** + ```bash + docker exec crowdsec cscli collections list + ``` + + **๐Ÿ“ฅ Install collections:** + + ```yaml + environment: + COLLECTIONS: "crowdsecurity/nginx crowdsecurity/linux" + ``` + Then **restart the container**. + + + + + In Kubernetes, collections must be specified in your Helm values file. + + **๐Ÿ” To check what's currently installed:** + ```bash + for i in $(kubectl get pods -n crowdsec -l k8s-app=crowdsec -l type=agent -o name); do kubectl exec -n crowdsec -it $i -- cscli collections list; done + ``` + + **๐Ÿ“ฅ Install collections:** + + Add to your `values.yaml`: + ```yaml + agent: + env: + - name: COLLECTIONS + value: "crowdsecurity/traefik crowdsecurity/nginx" + ``` + + Then upgrade your Helm release: + ```bash + helm upgrade crowdsec crowdsec/crowdsec -n crowdsec -f values.yaml + ``` + + + + + **โš ๏ธ Log format mismatch:** + - If your logs don't follow the expected format (e.g., they've been customized), CrowdSec might not parse them properly. + - **Check which log format the Hub parser expects:** + - Each parser on the Hub documents the expected log format. For example: + - [**NGINX parser** โ†—๏ธ](https://app.crowdsec.net/hub/author/crowdsecurity/log-parsers/nginx-logs) expects the default combined log format + - [**Apache parser** โ†—๏ธ](https://app.crowdsec.net/hub/author/crowdsecurity/log-parsers/apache2-logs) expects the standard combined format + - Compare your actual log format with the expected format to identify mismatches + - **For custom log formats:** + - **Example**: If you use a custom NGINX log format like `log_format custom '$remote_addr - $request - $status';`, you'll need a custom parser + - Use the [**CrowdSec Playground** โ†—๏ธ](https://playground.crowdsec.net/) to test and develop your parsers interactively + - The playground lets you test GROK patterns, parsers, and scenarios in real-time before deploying them + - Full guide on creating parsers: [CrowdSec Parser Documentation](https://doc.crowdsec.net/docs/next/log_processor/parsers/format)
โš™๏ธ CrowdSec Service Troubleshooting -- is the CrowdSec service running? - Letโ€™s check if the CrowdSec service is active: - sudo systemctl status crowdsec - - โ˜‘๏ธ You should see: "**active (running)**" - - If the service is not running, you can start it manually: - sudo systemctl start crowdsec - - ๐Ÿ’ก make sure it will be up after restart, activate the service + + - If the service fails to start, you can check the logs for more information: - For linux systems, the logs are typically located in `/var/log/crowdsec.log`. - less /var/log/crowdsec.log + Let's check if the CrowdSec service is active: + ```bash + sudo systemctl status crowdsec + ``` + - โ˜‘๏ธ You should see: "**active (running)**" - Common reasons the service might fail:: - - Misconfiguration in the `config.yaml` file. - - Port conflicts with other services. By default, CrowdSec uses port 8080 for the Local API (LAPI) and port 6060 for the Local API metrics. - - The port configuration can be setup in `config.yaml` file or by setting the environment variables depending on your implementation - - Insufficient permissions to access the log files or directories. - - Acquisition files format errors. + **If the service is not running:** + ```bash + sudo systemctl start crowdsec + sudo systemctl enable crowdsec # Ensure it starts on boot + ``` + + **Check logs for errors:** + ```bash + # Start by checking crowdsec logs + less /var/log/crowdsec.log + + # Eventually check systemd journal logs + sudo journalctl -u crowdsec -n 50 + ``` + + **Common issues:** + - Misconfiguration in `/etc/crowdsec/config.yaml` + - Port conflicts (default: 8080 for LAPI, 6060 for metrics) + - Insufficient permissions to access log files + - Acquisition files format errors + + + + + Check if the container is running: + ```bash + docker ps | grep crowdsec + ``` + + **If not running, check container logs:** + ```bash + docker logs crowdsec + ``` + + **Make sure your container starts without error** + + **Common issues:** + - **Volume mount errors**: Ensure `/etc/crowdsec/` and `/var/lib/crowdsec/data/` are properly mounted + - **Missing data volume**: Since v1.7.0, `/var/lib/crowdsec/data/` must be persisted + - **Port conflicts**: Check if 8080 is available on host + - **Log access**: Ensure log volumes are correctly mounted and readable + - **Environment variables**: Verify `COLLECTIONS` and other env vars are set correctly + + **Check container status:** + ```bash + docker inspect crowdsec + ``` + + + + + Check if pods are running: + ```bash + kubectl get pods -n crowdsec + ``` + + You should see LAPI and agent pods in `Running` status. + + **Check pod logs:** + ```bash + # LAPI logs + kubectl logs -n crowdsec -l k8s-app=crowdsec -l type=lapi + + # Agent logs + kubectl logs -n crowdsec -l k8s-app=crowdsec -l type=agent + ``` + + **Describe pod for more details:** + ```bash + kubectl describe pod -n crowdsec + ``` + + **Common issues:** + - **ConfigMap errors**: Verify configuration is valid + ```bash + kubectl get configmap -n crowdsec + ``` + - **Resource limits**: Check if pods have sufficient CPU/memory + - **Network policies**: Ensure pods can communicate with each other + - **PVC issues**: If using persistent volumes, ensure PVCs are bound + ```bash + kubectl get pvc -n crowdsec + ``` + - **Image pull errors**: Check if the CrowdSec image is accessible, could happen if you have registry conflicts + + **Upgrade your Helm** + ```bash + helm upgrade crowdsec crowdsec/crowdsec -n crowdsec -f values.yaml + ``` + + +
## ๐Ÿ”Œ CrowdSec Connectivity checks -### Is your Security Engine receiving community blocklists? +### *Check CAPI status* -Letโ€™s confirm that your Security Engine can communicate with the CrowdSec Central API (CAPI). +Let's confirm that your Security Engine can communicate with the CrowdSec Central API (CAPI). This connection allows you to: - Receive **Community Blocklists** -- curated IPs flagged as malicious by the global CrowdSec network. - Receive additional Blocklists of your choice among the ones available to you. - Contribute back -- sharing detected Malicious IPs triggering installed scenarios.
- ๐Ÿ”Œ CrowdSec Central API connectivity + ๐Ÿ”Œ CrowdSec Central API connectivity test - The most direct way to verify connectivity is to see if your instance has already received decisions from the Community Blocklist. + Check your CAPI connection status: - 1๏ธโƒฃ List decisions coming from CAPI - sudo cscli decisions list --origin CAPI + + + sudo cscli capi status + + + docker exec crowdsec cscli capi status + + + kubectl exec -n crowdsec -it $(kubectl get pods -n crowdsec -l k8s-app=crowdsec -l type=lapi -o name) -- cscli capi status + + - โ˜‘๏ธ If you see decisions, you're connected and receiving threat intel. + โ˜‘๏ธ You should see: `INFO You can successfully interact with Central API (CAPI)` **Notes:** - - On a fresh install, it might take a few minutes before any decisions appear. - - Restarting the CrowdSec service will force it to perform a first pull. + - On a fresh install, credentials might need to be registered (see troubleshooting below). + - The output also shows information about the connectivity config file path and enrollment status with CrowdSec Console.
### Were all the tests successful ? @@ -241,23 +498,65 @@ Were all the tests related to your setup successful?
๐Ÿž Connectivity Troubleshooting - Letโ€™s verify your CAPI connection step-by-step. - - Check CAPI status: - sudo cscli capi status - - **Should show:** - - `INFO You can successfully interact with Central API (CAPI)` - - Along with information about the connectivity config file path and if your Security engine is enrolled in CrowdSec console. - - **Common issues include:** - - Missing `online_api_credentials.yaml` in your CrowdSec config directory - - If they don't exist, you can create them by running the command: - sudo cscli capi register - - Firewall rules blocking outbound connections to the CrowdSec Central API (api.crowdsec.net) - - DNS resolution issues. - - Proxy server configuration. - - Connectivity issues within Docker containers. + If the CAPI status check fails, here are the most common issues and solutions: + + + + + **Common issues:** + - **Missing credentials**: If `online_api_credentials.yaml` is missing: + ```bash + sudo cscli capi register + sudo systemctl reload crowdsec + ``` + - **Firewall blocking**: Ensure outbound network access (API endpoints, blocklists, etc.). See [Network Management](https://docs.crowdsec.net/docs/next/configuration/network_management/) for full requirements + - **DNS issues**: Verify DNS resolution works: + ```bash + nslookup api.crowdsec.net + ``` + - **Proxy configuration**: If behind a proxy, configure in `/etc/crowdsec/config.yaml` + + + + + **Common issues:** + - **No internet from container**: Ensure container can reach external networks + ```bash + docker exec crowdsec ping -c 3 api.crowdsec.net + ``` + - **Missing credentials**: Register if credentials are missing: + ```bash + docker exec crowdsec cscli capi register + docker restart crowdsec + ``` + - **Volume not persisted**: Ensure `/etc/crowdsec/` volume persists the credentials file + - **Network mode**: If using custom networks, verify routing and DNS + - **Proxy issues**: Set `HTTP_PROXY` and `HTTPS_PROXY` environment variables if needed + + + + + **Common issues:** + - **No external connectivity**: Test from pod: + ```bash + kubectl exec -n crowdsec -it $(kubectl get pods -n crowdsec -l k8s-app=crowdsec -l type=lapi -o name) -- ping -c 3 api.crowdsec.net + ``` + - **NetworkPolicy blocking**: Check if NetworkPolicies allow egress to api.crowdsec.net + - **DNS issues**: Verify CoreDNS is working correctly + - **Proxy configuration**: Configure proxy via environment variables in values.yaml: + ```yaml + lapi: + env: + - name: HTTP_PROXY + value: "http://proxy:8080" + - name: HTTPS_PROXY + value: "http://proxy:8080" + ``` + - **PVC not bound**: If credentials aren't persisting, check PVC status + - **Enrollment key**: If using console enrollment, verify `ENROLL_KEY` is set correctly in values.yaml + + +
@@ -286,7 +585,18 @@ OR do it from a device with a different public IP address than the client you're curl api.ipify.org 2๏ธโƒฃ Add a ban decision for your IP (valid for 1 minute): -sudo cscli decisions add --ip \ --duration 1m --reason "CrowdSec remediation test" + + + + sudo cscli decisions add --ip \ --duration 1m --reason "CrowdSec remediation test" + + + docker exec crowdsec cscli decisions add --ip \ --duration 1m --reason "CrowdSec remediation test" + + + kubectl exec -n crowdsec -it $(kubectl get pods -n crowdsec -l k8s-app=crowdsec -l type=lapi -o name) -- cscli decisions add --ip \ --duration 1m --reason "CrowdSec remediation test" + + โณ *Wait a few seconds to ensure the decision is processed by the bouncer.* 3๏ธโƒฃ Try accessing your service (e.g. website, API). from the same public IP address. @@ -313,30 +623,93 @@ You might want to continue to the next recommended steps:
Is your Bouncer Installed and Connected to your Security engine - - - Check bouncers linked to your Security Engine: - sudo cscli bouncers list - You should see: + + + + + **Check bouncers linked to your Security Engine:** + ```bash + sudo cscli bouncers list + ``` + + **You should see:** - The bouncer name - - A tick in the valid column indicating that the bouncer is properly registered and connected to your Security Engine. - - a recent `Last API pull` datasources - - - If your bouncer is not valid or not pulling it might be an issue with the bouncer configuration authentication in its configuration file. - - If you don't see your bouncer listed, you should add it - - You can try to re-register your bouncer with the command: - sudo cscli bouncers add - - Copy the provided token and paste it in your bouncer configuration file. - - Then restart the bouncer service. - - - If your bouncer is on a different machine, ensure it can reach the Security Engine Local API. - - If you are using a bouncer in a container, ensure that the container can reach the Security Engine Local API. + - A โœ“ in the valid column indicating proper registration + - A recent `Last API pull` timestamp + + **Common issues:** + - **Bouncer not valid or not pulling**: Check authentication in bouncer config file + - **Bouncer not listed**: Register it: + ```bash + sudo cscli bouncers add my-bouncer-name + ``` + Copy the token and add it to your bouncer's configuration, then restart the bouncer service. + + - **Bouncer on different machine**: Ensure it can reach the LAPI endpoint (default: `http://crowdsec-server:8080`) + - **Firewall blocking**: Verify port 8080 is accessible from bouncer machine + + + + + **Check bouncers linked to your Security Engine:** + ```bash + docker exec crowdsec cscli bouncers list + ``` + + **Common issues:** + - **Bouncer in separate container**: Ensure containers are on the same Docker network + - **LAPI URL**: Bouncer config should point to `http://crowdsec:8080` (using container name) + - **Register bouncer**: You can pre-create bouncer keys using environment variables: + ```yaml + environment: + BOUNCER_KEY_mybouncer: "my-secret-api-key" + ``` + - **Network connectivity**: Test from bouncer container: + ```bash + docker exec my-bouncer ping crowdsec + ``` + + + + + **Check bouncers linked to your Security Engine:** + ```bash + kubectl exec -n crowdsec -it $(kubectl get pods -n crowdsec -l k8s-app=crowdsec -l type=lapi -o name) -- cscli bouncers list + ``` + + **Common issues:** + - **Service discovery**: Bouncer should connect to `http://crowdsec-service.crowdsec.svc.cluster.local:8080` + - **Register bouncer**: + ```bash + # Generate API key with a tool of your choice + # Then fill the values.yaml accordingly to dictates the bouncer name and api key use for this communication with LAPI + # values.yaml + lapi: + env: + - name: BOUNCER_KEY_ + value: "api-key-you-want-this-bouncer-to-use" + ``` + - **Network policies**: Ensure bouncer namespace can reach crowdsec namespace + - **Service accessibility**: Verify the LAPI, named `crowdsec-service` is accessible: + ```bash + kubectl get svc -n crowdsec crowdsec-service + ``` + + **For Ingress Nginx bouncer:** + - Ensure the bouncer has the correct LAPI URL in its ConfigMap + - Check bouncer logs for connection errors: + ```bash + kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller + ``` + + + +
-## ๐Ÿ’ฌ Your feedback is important! - -Help us improve this health check guide! -Give us feedback via this form: [๐Ÿ“ Health Check Feedback Form โ†—๏ธ](https://forms.gle/DJboC7oisjmA8qt78) +## ๐Ÿ’ฌ Get Help & Give Feedback -[๐Ÿ“จ Open an issue on GitHub โ†—๏ธ](https://github.com/crowdsecurity/crowdsec-docs/issues/new) or -๐Ÿ—ฃ๏ธ Join the conversation on [Discord โ†—๏ธ](https://discord.gg/wGN7ShmEE8) \ No newline at end of file +- ๐Ÿ“ [Health Check Feedback Form โ†—๏ธ](https://forms.gle/DJboC7oisjmA8qt78) +- ๐Ÿ“จ [Open an issue on GitHub โ†—๏ธ](https://github.com/crowdsecurity/crowdsec-docs/issues/new) +- ๐Ÿ—ฃ๏ธ [Join us on Discord โ†—๏ธ](https://discord.gg/wGN7ShmEE8) \ No newline at end of file diff --git a/crowdsec-docs/unversioned/getting_started/introduction.mdx b/crowdsec-docs/unversioned/getting_started/introduction.mdx index 1a3886def..c3f885fca 100644 --- a/crowdsec-docs/unversioned/getting_started/introduction.mdx +++ b/crowdsec-docs/unversioned/getting_started/introduction.mdx @@ -81,6 +81,10 @@ CrowdSec Security Engine uses the following default ports (bound to localhost/lo * 6060/tcp: Prometheus metrics port * 8080/tcp: API port +## Next Steps + +After installing CrowdSec, use our **[interactive Health-Check guide](health_check.mdx)** to verify your setup is working correctly. It will walk you through testing detection, connectivity, and remediation to ensure your Security Stack is fully functional. + ## Resources diff --git a/crowdsec-docs/unversioned/troubleshooting/intro.md b/crowdsec-docs/unversioned/troubleshooting/intro.md index d1f5d3dee..3072d0979 100644 --- a/crowdsec-docs/unversioned/troubleshooting/intro.md +++ b/crowdsec-docs/unversioned/troubleshooting/intro.md @@ -4,18 +4,21 @@ id: intro --- :::info -You may see CrowdSec referred to as "Security Engine" and Bouncers referred to as "Remediation Components" within new documentation. This is to better reflect the role of each component within the CrowdSec ecosystem. +You may see the **IDPS/WAF of CrowdSec** referred to as **"Security Engine"** and **Bouncers** referred to as **"Remediation Components"** within new documentation. +This is to better reflect the role of each component within the CrowdSec ecosystem. ::: # Troubleshooting -We have extended our troubleshooting documentation to cover more common issues and questions. If you have any suggestions for this please open an [issue here](https://github.com/crowdsecurity/crowdsec-docs). +We have extended our troubleshooting documentation to cover more common issues and questions. +If you have any suggestions for this please open an [issue here](https://github.com/crowdsecurity/crowdsec-docs). -### [Security Engine Troubleshooting](/troubleshooting/security_engine.mdx) +Also, checkout our ๐Ÿฉบ [**Stack Health-Check page**](/u/getting_started/health_check) to make sure your **Detection**, **Community Sharing** and **Remediation** are working properly -### [Remediation Components Troubleshooting](/troubleshooting/remediation_components.mdx) - -### [CTI Troubleshooting](/troubleshooting/cti.mdx) +Here you'll also find Troubleshooting by topic: +* [Security Engine Troubleshooting](/troubleshooting/security_engine.mdx) +* [Remediation Components Troubleshooting](/troubleshooting/remediation_components.mdx) +* [CTI Troubleshooting](/troubleshooting/cti.mdx) ## Community support