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