Configuration Overview

cs-routeros-bouncer can be configured via YAML file and/or environment variables. Environment variables override values from the config file.

Config file

When running the binary directly, pass the config path with -c unless all required settings are supplied via environment variables:

cs-routeros-bouncer -c /path/to/config.yaml

Deployment helpers choose their own paths:

| Deployment method | Config path used | | ----------------------- | -------------------------------------------------------------------------------------------------- | | setup systemd service | /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml | | Docker image | Environment variables by default; /etc/cs-routeros-bouncer/config.yaml is auto-loaded if mounted | | Direct binary execution | No implicit file; use -c |

YAML string values may contain explicit ${VAR} placeholders. Only braced placeholders are expanded; literal $ characters in secrets are preserved.

A full annotated reference is included in the repository at config/cs-routeros-bouncer.yaml.

Configuration sections

CrowdSec LAPI connection, polling, decision filtering.

CAPI Blocklists Community blocklists, local-only mode, and scale guidance.

MikroTik RouterOS API connection, TLS, and timeouts.

Firewall IPv4/IPv6, filter/raw rules, output blocking, logging.

Logging & Metrics Log level/format, Prometheus metrics endpoint.

Performance Tuning Pool size, bulk operations, timeouts, and reconciliation cadence.

Examples Complete configuration examples for common scenarios.

Quick reference

All options at a glance. See the dedicated pages for detailed descriptions.

Basic parameters

The essential settings to get the bouncer running. Most deployments only need these.

| Config Key | Env Variable | Default | Description | | ------------------------- | -------------------------- | ------------------------ | ------------------------------------------- | | crowdsec.api_url | CROWDSEC_URL | http://localhost:8080/ | CrowdSec LAPI URL | | crowdsec.api_key | CROWDSEC_BOUNCER_API_KEY | (required) | Bouncer API key | | mikrotik.address | MIKROTIK_HOST | 192.168.0.1:8728 | RouterOS API address (host:port) | | mikrotik.username | MIKROTIK_USER | crowdsec | API username | | mikrotik.password | MIKROTIK_PASS | (required) | API password | | firewall.ipv4.enabled | FIREWALL_IPV4_ENABLED | true | Enable IPv4 blocking | | firewall.ipv6.enabled | FIREWALL_IPV6_ENABLED | true | Enable IPv6 blocking | | firewall.filter.enabled | FIREWALL_FILTER_ENABLED | true | Create filter firewall rules | | firewall.raw.enabled | FIREWALL_RAW_ENABLED | true | Create raw/prerouting rules | | firewall.deny_action | FIREWALL_DENY_ACTION | drop | Action: drop or reject | | logging.level | LOG_LEVEL | info | Log level: debug, info, warn, error |

Advanced parameters

Fine-tuning options for decision filtering, TLS, performance, firewall customization, and observability. The defaults work well for most setups.

CrowdSec — polling, filtering & TLS

| Config Key | Env Variable | Default | Description | | ------------------------------------ | ----------------------------------- | ---------------- | ------------------------------------------------------------------- | | crowdsec.update_frequency | CROWDSEC_UPDATE_FREQUENCY | 10s | Poll interval | | crowdsec.reconciliation_interval | CROWDSEC_RECONCILIATION_INTERVAL | 15m | Periodic address-list reconciliation (0 = disabled, minimum 1m) | | crowdsec.lapi_metrics_interval | CROWDSEC_LAPI_METRICS_INTERVAL | 15m | Usage metrics reporting interval (0 = disabled) | | crowdsec.origins | CROWDSEC_ORIGINS | [] (all) | Filter by origin | | crowdsec.scopes | CROWDSEC_SCOPES | ["ip","range"] | Decision scopes | | crowdsec.supported_decisions_types | CROWDSEC_DECISIONS_TYPES | ["ban"] | Decision types (only ban is implemented) | | crowdsec.scenarios_containing | CROWDSEC_SCENARIOS_CONTAINING | [] | Include only matching scenarios | | crowdsec.scenarios_not_containing | CROWDSEC_SCENARIOS_NOT_CONTAINING | [] | Exclude matching scenarios | | crowdsec.retry_initial_connect | CROWDSEC_RETRY_INITIAL_CONNECT | true | Retry on startup | | crowdsec.insecure_skip_verify | CROWDSEC_INSECURE_SKIP_VERIFY | false | Skip TLS verify | | crowdsec.cert_path | CROWDSEC_CERT_PATH | | Client cert path | | crowdsec.key_path | CROWDSEC_KEY_PATH | | Client key path | | crowdsec.ca_cert_path | CROWDSEC_CA_CERT_PATH | | CA cert path |

CROWDSEC_ORIGINS is space-separated when set as an environment variable, for example CROWDSEC_ORIGINS="crowdsec cscli".

MikroTik — TLS & performance

| Config Key | Env Variable | Default | Description | | ----------------------------- | ----------------------- | ------- | ------------------------------- | | mikrotik.tls | MIKROTIK_TLS | false | Use TLS | | mikrotik.tls_insecure | MIKROTIK_TLS_INSECURE | false | Skip TLS verify | | mikrotik.connection_timeout | MIKROTIK_CONN_TIMEOUT | 10s | Connect timeout | | mikrotik.command_timeout | MIKROTIK_CMD_TIMEOUT | 30s | Command timeout | | mikrotik.pool_size | MIKROTIK_POOL_SIZE | 4 | Parallel API connections (1–20) |

Firewall — rules, interfaces & logging

| Config Key | Env Variable | Default | Description | | ------------------------------------------- | ------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | firewall.ipv4.address_list | FIREWALL_IPV4_ADDRESS_LIST | crowdsec-banned | IPv4 list name | | firewall.ipv6.address_list | FIREWALL_IPV6_ADDRESS_LIST | crowdsec6-banned | IPv6 list name | | firewall.filter.chains | FIREWALL_FILTER_CHAINS | ["input"] | Filter chains; comma-separated env values trim whitespace around each entry | | firewall.raw.chains | FIREWALL_RAW_CHAINS | ["prerouting"] | Raw chains; comma-separated env values trim whitespace around each entry | | firewall.rule_placement | FIREWALL_RULE_PLACEMENT | top | Simple string shorthand for global placement | | firewall.rule_placement.strategy | FIREWALL_RULE_PLACEMENT_STRATEGY | top | Object-form strategy: top, bottom, position, before_comment, or after_comment | | firewall.rule_placement.comment | FIREWALL_RULE_PLACEMENT_COMMENT | | Anchor comment for comment placement | | firewall.rule_placement.comment_match | FIREWALL_RULE_PLACEMENT_COMMENT_MATCH | exact | Comment match mode: exact or contains | | firewall.rule_placement.position | FIREWALL_RULE_PLACEMENT_POSITION | | Required zero-based RouterOS print position when strategy is position | | firewall.rule_placement.fallback | FIREWALL_RULE_PLACEMENT_FALLBACK | top | Fallback for comment placement: top or bottom | | firewall.rule_placement.filter | YAML only | | Filter-table override; inherits unspecified fields from global placement | | firewall.rule_placement.raw | YAML only | | Raw-table override; inherits unspecified fields from global placement | | firewall.ipv4.rule_placement | YAML only | | IPv4-only placement override; inherits unspecified fields from global placement | | firewall.ipv4.rule_placement.filter | YAML only | | IPv4 filter-table override; inherits from global and IPv4 placement | | firewall.ipv4.rule_placement.raw | YAML only | | IPv4 raw-table override; inherits from global and IPv4 placement | | firewall.ipv6.rule_placement | YAML only | | IPv6-only placement override; inherits unspecified fields from global placement | | firewall.ipv6.rule_placement.filter | YAML only | | IPv6 filter-table override; inherits from global and IPv6 placement | | firewall.ipv6.rule_placement.raw | YAML only | | IPv6 raw-table override; inherits from global and IPv6 placement | | firewall.comment_prefix | FIREWALL_COMMENT_PREFIX | crowdsec-bouncer | Comment prefix | | firewall.log | FIREWALL_LOG | false | Enable rule logging | | firewall.log_prefix | FIREWALL_LOG_PREFIX | crowdsec-bouncer | Global log prefix | | firewall.reject_with | FIREWALL_REJECT_WITH | | Reject type when deny_action=reject: icmp-network-unreachable, icmp-host-unreachable, icmp-port-unreachable, icmp-protocol-unreachable, icmp-network-prohibited, icmp-host-prohibited, icmp-admin-prohibited, tcp-reset | | firewall.filter.log_prefix | FIREWALL_FILTER_LOG_PREFIX | | Override log prefix for filter rules | | firewall.filter.connection_state | FIREWALL_FILTER_CONNECTION_STATE | | Comma-separated states: new, established, related, invalid, untracked; whitespace around entries is trimmed; lowercase only, no negation | | firewall.raw.log_prefix | FIREWALL_RAW_LOG_PREFIX | | Override log prefix for raw rules | | firewall.block_input.interface | FIREWALL_BLOCK_INPUT_INTERFACE | | Restrict input/raw rules to interface (empty = all) | | firewall.block_input.interface_list | FIREWALL_BLOCK_INPUT_INTERFACE_LIST | | Restrict input/raw rules to interface list (empty = all) | | firewall.block_input.whitelist | FIREWALL_BLOCK_INPUT_WHITELIST | | Address-list for input whitelist (accept before drop) | | firewall.block_output.enabled | FIREWALL_BLOCK_OUTPUT | false | Block outbound | | firewall.block_output.interface | FIREWALL_BLOCK_OUTPUT_INTERFACE | | WAN interface | | firewall.block_output.interface_list | FIREWALL_BLOCK_OUTPUT_INTERFACE_LIST | | WAN interface list | | firewall.block_output.log_prefix | FIREWALL_BLOCK_OUTPUT_LOG_PREFIX | | Override log prefix for output rules | | firewall.block_output.passthrough_v4 | FIREWALL_BLOCK_OUTPUT_PASSTHROUGH_V4 | | IPv4 client to bypass output blocking | | firewall.block_output.passthrough_v4_list | FIREWALL_BLOCK_OUTPUT_PASSTHROUGH_V4_LIST | | IPv4 list to bypass output blocking | | firewall.block_output.passthrough_v6 | FIREWALL_BLOCK_OUTPUT_PASSTHROUGH_V6 | | IPv6 client to bypass output blocking | | firewall.block_output.passthrough_v6_list | FIREWALL_BLOCK_OUTPUT_PASSTHROUGH_V6_LIST | | IPv6 list to bypass output blocking |

Backward-compatible aliases such as FIREWALL_INPUT_* and FIREWALL_OUTPUT_* are still accepted for older deployments. Prefer the explicit FIREWALL_BLOCK_INPUT_* and FIREWALL_BLOCK_OUTPUT_* names in new configs.

Logging & Metrics — format, file output & Prometheus

| Config Key | Env Variable | Default | Description | | -------------------------------- | -------------------------------- | --------- | --------------------------------------------------------------- | | logging.format | LOG_FORMAT | text | Log format: text or json | | logging.file | LOG_FILE | | Log file path (empty = stdout only) | | metrics.enabled | METRICS_ENABLED | false | Enable Prometheus /metrics endpoint | | metrics.listen_addr | METRICS_ADDR | 0.0.0.0 | Listen address | | metrics.listen_port | METRICS_PORT | 2112 | Listen port | | metrics.routeros_poll_interval | METRICS_ROUTEROS_POLL_INTERVAL | 30s | RouterOS system metrics poll interval (0 to disable) | | metrics.track_processed | METRICS_TRACK_PROCESSED | true | Create passthrough counting rules for processed traffic metrics |