Feature Flags

In order to make it easier for users to test and experiment with new features, CrowdSec uses the concept of "feature flags". New commands and behaviors can be improved by us, according to the user's feedback, before making them available in the default configuration.

Enabling a Feature Flag

A feature flag can be enabled in two ways:

• By adding the feature name as a list item in the file /etc/crowdsec/feature.yaml. For example, to enable the my_new_feature feature flag, you would add the following line to the file:

/etc/crowdsec/feature.yaml

  - my_new_feature

• By setting the CROWDSEC_FEATURE_<feature-name> environment variable to true. For example, to enable the my_new_feature feature flag, you would set the environment variable CROWDSEC_FEATURE_MY_NEW_FEATURE=true. This is recommended when running CrowdSec in containers. If you really want to do this outside of containers (as we do for tests), keep in mind that the variable must be defined for both the crowdsec process and cscli.

You can see if CrowdSec is running with feature flags by calling grep 'feature flags' /var/log/crowdsec.log | tail -1

Retrieving Supported Feature Flags

To retrieve a list of all the supported and enabled feature flags for a given version of CrowdSec, you can use the following command:

$ cscli config feature-flags
 --- Enabled features ---

✓ cscli_setup: Enable cscli setup command (service detection)
✓ papi_client: Enable Polling API client

 --- Disabled features ---

✗ chunked_decisions_stream: Enable chunked decisions stream
✗ disable_http_retry_backoff: Disable http retry backoff

To enable a feature you can: 
  - set the environment variable CROWDSEC_FEATURE_<uppercase_feature_name> to true
  - add the line '- <feature_name>' to the file /etc/crowdsec/feature.yaml

Deprecation, retirement

When a feature is made generally available, or if it's discarded completely, the corresponding feature flag can be deprecated or retired. You can still use the feature flag (with a warning) if it has been deprecated. Using a feature flag that has been retired will have no effect and log an error instead.

In the following example, we deprecated cscli_setup and retired papi, then we attempt to enable both. You can see the warning and the error.

$ CROWDSEC_FEATURE_PAPI_CLIENT=true CROWDSEC_FEATURE_CSCLI_SETUP=true ./tests/local/bin/cscli version
ERRO[02-03-2023 15:55:45] Ignored envvar 'CROWDSEC_FEATURE_PAPI_CLIENT': the flag is retired.  
WARN[02-03-2023 15:55:45] Envvar 'CROWDSEC_FEATURE_CSCLI_SETUP': the flag is deprecated.  
2023/03/02 15:55:45 version: v1.5.0-rc1-13-ge729bf5d-e729bf5d6103894da28818ab4626bab918fbd09d
2023/03/02 15:55:45 Codename: alphaga
2023/03/02 15:55:45 BuildDate: 2023-03-02_15:48:28
2023/03/02 15:55:45 GoVersion: 1.20.1
[...]

Retired flags don't appear in cscli config feature-flags unless you use the --retired option:

$ CROWDSEC_FEATURE_PAPI_CLIENT=true CROWDSEC_FEATURE_CSCLI_SETUP=true ./tests/local/bin/cscli config feature-flags --retired
ERRO[02-03-2023 15:58:38] Ignored envvar 'CROWDSEC_FEATURE_PAPI_CLIENT': the flag is retired.
WARN[02-03-2023 15:58:38] Envvar 'CROWDSEC_FEATURE_CSCLI_SETUP': the flag is deprecated.
 --- Enabled features ---

✓ cscli_setup: Enable cscli setup command (service detection)
  DEPRECATED

 --- Disabled features ---

✗ chunked_decisions_stream: Enable chunked decisions stream
✗ disable_http_retry_backoff: Disable http retry backoff

To enable a feature you can:
  - set the environment variable CROWDSEC_FEATURE_<uppercase_feature_name> to true
  - add the line '- <feature_name>' to the file /home/marco/src/crowdsec/tests/local/etc/crowdsec/feature.yaml

 --- Retired features ---

✗ papi_client: Enable Polling API client
  RETIRED