Service Discovery

The goals of service discovery are to automatically:

• Detect services on your machine supported by crowdsec
• Install related hub items
• Generate acquisition configuration

Basic Usage

The main way to use the service discovery is with cscli setup interactive or cscli setup unattended.

By default, it will use the detection file provided by crowdsec stored in /var/lib/crowdsec/data/detect.yaml.

In interactive mode, cscli will ask you to choose which service to configure based on those that were detected, and will require confirmation before any operation (installing hub items, generating acquisition config, ...).

It is your responsibility to check the compatibility of the generated acquisitions with the ones you add later or were already on the system.

While cscli setup validates the generated configuration files for syntax errors or invalid configuration, it does not check for duplicate acquisition.

If using a custom detect.yaml, make sure no logs are read multiple times (with the same type label), as this could lead to false positives.

cscli will ask for confirmation before proceeding if:

• there is an acquis.yaml
• there is any non-generated file in acquis.d
• you modified the generated files in acquis.d (there is a checksum to detect modifications). Proceeding could overwrite them.

Files composed by comments only are ignored.

Linux packages (deb or rpm) will automatically call cscli setup unattended during installation. In the case above, instead of asking for confirmation, unattended mode will just skip the service detection.

Generated acquisition files & coexistence with your own files

When you generated the acquisition configuration with cscli setup, cscli writes one file per service as setup.<name>.yaml in the acquisition directory (typically /etc/crowdsec/acquis.d). The content is prefixed with a header that includes a checksum and a comment stating it was generated by cscli setup.

• Files carrying a valid checksum are considered generated and may be overwritten by future runs.
• Files without a valid checksum are treated as manually edited; in interactive mode, cscli shows a colorized diff and asks before overwriting. In unattended flows, the command refuses to proceed if manual files are detected.
• Either way, the safest practice is: don’t edit generated files. If you need changes, delete the generated setup.<name>.yaml and create your own hand‑managed file instead or use a custom detect.yaml to generate the proper configuration automatically.

Tips

• The actual on‑disk path is computed as acquis.d/setup.<filename>.yaml where <filename> comes from acquisition_spec.filename.
• Use --acquis-dir to target a different directory.
• --dry-run prints what would be created without writing files.

Advanced Usage

Use a custom detect.yaml

You can provide a custom detect.yaml in two ways:

# Path flag
cscli setup detect --detect-config /path/to/detect.yaml

# Or via environment variable
CROWDSEC_SETUP_DETECT_CONFIG=/path/to/detect.yaml cscli setup detect

Helpful flags:

• --yaml – render the setup plan as YAML (easy to review/edit); default output is JSON.
• --force <svc> – pretend detection matched for <svc> (repeatable).
• --ignore <svc> – drop <svc> from the plan even if matched (repeatable).
• --skip-systemd – disable systemd‐based detection (default if systemctl can't be run).
• --list-supported-services – print the service keys present in your file and exit.

You can see a list of all the available expr helpers in the dedicated documentation.

For example, if you have configured nginx to log in a non-standard location, you can use a custom detect.yaml to override it.

This example will generate an acquisition with the pattern /srv/logs/nginx/*.log if the nginx service is installed OR if any file matches the glob pattern /srv/logs/nginx/*.log:

# detect.yaml
---
detect:
  nginx-custom:
    when:
      - Systemd.UnitInstalled("nginx.service") or len(Path.Glob("/srv/logs/nginx/*.log")) > 0
    hub_spec:
      collections:
       - crowdsecurity/nginx
    acquisition_spec:
      filename: nginx.yaml
      datasource:
        source: file
        filenames:
          - /srv/logs/nginx/*.log
        labels:
          type: nginx

When using a custom detect configuration, the default one will be fully ignored.

This means that on top of your custom detection, you will most likely want to add the basic OS detection, for example:

detect:
  linux:
    when:
     - Host.OS == "linux"
    hub_spec:
      collections:
       - crowdsecurity/linux
    acquisition_spec:
      filename: linux.yaml
      datasource:
        source: file
        labels:
          type: syslog
        filenames:
          - /var/log/messages
          - /var/log/syslog
          - /var/log/kern.log

Unattended installs with a custom detect file

Linux packages (deb or rpm) will automatically call cscli setup unattended during installation.

You can specify a custom detection file to use by setting CROWDSEC_SETUP_DETECT_CONFIG before installing the package with apt or dnf.

Alternatively, if you want to skip the automatic detection completely, you can set the env var CROWDSEC_SETUP_UNATTENDED_DISABLE to any value.

End-to-end workflow

Behind the scenes, cscli setup use multiple steps to configure crowdsec:

• Generate a YAML plan that contains the detected services, their associated hub items and acquisition configuration
• Validate this file
• Install the hub items
• Write the acquisition config to disk

If you wish, you can manually invoke any of those steps (if you only want to install the hub items for example).

cscli setup detect can be used to generate the setup file:

cscli setup detect --detect-config ./detect.yaml --yaml > setup.yaml

You can then validate its content for syntax error or issues with the acquisition configuration:

cscli setup validate ./setup.yaml

Then, install the hub items:

cscli setup install-hub ./setup.yaml

And finally, write the acquisition config:

cscli setup install-acquisition ./setup.yaml --acquis-dir /etc/crowdsec/acquis.d