MikroTik Configuration

Settings for the MikroTik RouterOS API connection.

Connection

mikrotik.address Required

Env: MIKROTIK_HOST · Default: — (required)

RouterOS API address in host:port format. There is no built-in default: the bouncer exits with mikrotik.address is required if this value is empty. The 192.168.0.1:8728 used below is the sample value shipped in config/cs-routeros-bouncer.yaml, not a default.

• Port 8728 — plaintext API
• Port 8729 — TLS-encrypted API

mikrotik:
  address: "192.168.0.1:8728"

mikrotik.username Required

Env: MIKROTIK_USER · Default: — (required)

The RouterOS API username. There is no built-in default: the bouncer exits with mikrotik.username is required if this value is empty. The crowdsec name is the sample value shipped in config/cs-routeros-bouncer.yaml, not a default. Use a dedicated user with minimal permissions. See Router Setup for creating the user.

mikrotik.password Required

Env: MIKROTIK_PASS · Default: — (required)

The RouterOS API password.

Environment variables

For sensitive values like passwords, use environment variables instead of the config file:

export MIKROTIK_PASS="your-secure-password"

TLS

mikrotik.tls Optional

Env: MIKROTIK_TLS · Default: false

Enable TLS for the RouterOS API connection. Requires the api-ssl service on the router (port 8729).

mikrotik:
  address: "192.168.0.1:8729"
  tls: true

mikrotik.tls_insecure Optional

Env: MIKROTIK_TLS_INSECURE · Default: false

Skip TLS certificate verification. Only needed when the router uses a self-signed certificate.

Caution

Keep tls_insecure: false whenever possible: the recommended production setup is a certificate signed by a CA the bouncer host trusts, so the connection stays both encrypted and verified. Set tls_insecure: true only for self-signed certificates or temporary troubleshooting.

Timeouts

mikrotik.connection_timeout Optional

Env: MIKROTIK_CONN_TIMEOUT · Default: 10s

Maximum time to connect and log in to the API, at startup and on every reconnect; 0 means no limit. Uses Go duration format.

mikrotik.command_timeout Optional

Env: MIKROTIK_CMD_TIMEOUT · Default: 30s

Maximum time to wait for the router while it answers an API command: for the answer to start, and between two parts of a long one. A router that stops answering fails the command; an answer that keeps coming, such as a large address list on a slow router, is not cut off. Increase it if your router is slow to start an answer.

Tip

The bound restarts with every part of an answer, so it does not grow with the list. The longest command is the address-list read at the start of every pass, which scales with how many entries the router holds (~1.8 s for 22,332 entries on an RB5009), but its entries arrive one after another; a bulk chunk takes about 130 ms.

Raise it if you see timeout errors on a slow device. Both timeouts must be >= 0; 0 means no bound, and a negative value is rejected at startup.

Connection Pool

mikrotik.pool_size Optional

Env: MIKROTIK_POOL_SIZE · Default: 4

How many RouterOS API sessions the bouncer can use for parallel work such as reconciliation removals. A higher value increases throughput when reconciliation has many stale address-list entries to delete, and with bulk_add_method: api also when it has many entries to add over a link with latency; on the router’s LAN one session adds fastest, and each extra one holds about 1.7 MiB of router RAM. Live decisions always use the main connection, so they are not affected.

• Valid range: 1–20
• Auto-capping: On startup the bouncer queries the router’s API service max-sessions limit and automatically reduces the effective pool size so it never exceeds max-sessions − 2 (reserving connections for the main client and external tools such as WinBox).

mikrotik:
  pool_size: 8 # Higher parallelism for reconciliation removals

Checking the router limit

The RouterOS API service has a max-sessions setting that limits simultaneous connections. The factory default is 20.

# Check current limit
/ip/service/print where name=api

# Increase it (maximum supported value is 1000)
/ip/service/set api max-sessions=1000

Performance tuning

For small to medium deployments (≤ 5,000 IPs) the default pool_size: 4 is optimal. For very large CAPI lists (20,000+ IPs) increasing to 6–8 can noticeably reduce reconciliation time. Always verify the router’s max-sessions first:

/ip/service/set api max-sessions=1000

Note

Each pool connection is a full RouterOS API session. On resource-constrained routers (e.g., hAP lite) keep pool_size low (1–2) to avoid memory pressure.

Bulk Add Method

mikrotik.bulk_add_method Optional

Env: MIKROTIK_BULK_ADD_METHOD · Default: script

How reconciliation (at startup and every crowdsec.reconciliation_interval) adds the address-list entries the router is missing. Live decisions are not affected: they are always added one API call each.

• script (default): the bouncer sends up to 100 adds as one RouterOS script. On RouterOS 7.8rc1 and later that is a single /execute call that runs the script synchronously: nothing is stored on the router and nothing reaches its log. On older versions, and for a chunk /execute cannot take (over its 64 kB limit, or on a router that turns out to lack it), the bouncer creates a temporary /system/script, runs it and removes it again. Either way the round trips a chunk costs do not depend on how many entries it holds: one through /execute, four as a stored script. Latency to the router therefore weighs far less than with api, which pays a round trip per entry. An add the script cannot make is reported back through /execute and retried with its own API call; if a script fails, that chunk is retried one call per entry.
• api: every entry is added with its own API call, spread over the connection pool (pool_size), or one after another on the main connection when the pool could not be opened. No script is ever created, and the router’s configuration is left alone.

On RouterOS older than 7.8rc1, RouterOS logs every stored script with its full source when it is created, an audit of /system/script shows the bouncer’s scripts coming and going, and each add and remove is a configuration change RouterOS persists; api avoids all of that there. From 7.8rc1 on, script leaves none of it behind either, as long as /execute runs the chunk; the stored-script fallback above still does. api still runs no script at all, and it caches the id of every entry it adds, so a live unban right after a reconciliation pass removes the entry without looking it up first. Address-list entries with a timeout, which is what decisions become, are dynamic and stay in memory either way.

mikrotik:
  bulk_add_method: api
  pool_size: 4 # adds spread over the pool: helps over a link with latency, not on the router's LAN

Tip

Measured on an RB5009 (RouterOS 7.24.4), loading about 24,400 decisions at startup:

• On the router’s LAN (0.2 ms), script through /execute took about 21 s and api with pool_size: 1 about 23 s, each at roughly half the router CPU of a stored script, which took about 36 s. With the default pool_size: 4, api took as long as a stored script, because extra sessions only contend here. A pass that adds a few entries takes milliseconds either way.
• Over a link with latency, every API add pays one round trip, where a script pays one per 100 entries through /execute and four as a stored script. At 36 ms, script took about 33 s through /execute, 70 s as a stored script, and api 76 s with pool_size: 16; at 33 ms it had taken 3.7 min with 4 and 13 min with 1.

Live decisions are applied as they arrive, also while a reconciliation runs: only a command already running on the main connection, such as the address-list read at the start of a pass, holds one back until it ends, and an unban for an address the running pass had already planned to add takes effect when the pass ends. A shutdown stops a running pass: the address-list read at its start, its adds and its removals. The next start finishes it.

Router CPU

mikrotik.cpu_limit Optional

Env: MIKROTIK_CPU_LIMIT · Default: 80

The router’s CPU load, in percent of all its cores, at which the bouncer slows its reconciliation work down. While the load is at or above it, the bouncer pauses before each block of work (a script of 100 adds, 100 single adds or removals, a duplicate lookup) and uses one API connection at a time. The pause starts at 200 ms, doubles for each further busy second up to 5 s, and halves for each second the load is 10 points under the limit (or under half the limit, when that is lower), back to full speed. A periodic pass also waits up to a minute for the load to drop before it reads the address list. Live bans and unbans are never slowed down, and are applied while a pass runs, slowed or not, save an unban for an address the pass had already planned to add, which takes effect when the pass ends. Neither is a shutdown slowed down. 0 turns it off.

The load is RouterOS’ own cpu-load: the average of all cores over the last second, read at most once a second while there is bulk work. One busy second, such as the router’s own periodic jobs, slows nothing down: it takes two in a row.

mikrotik:
  cpu_limit: 80

Note

At the slowest pace a reconciliation adds about 20 entries a second: the 17,000-entry community blocklist then loads in about 14 minutes instead of 14 seconds, but it keeps going. On an RB5009 the default script method stays around 30% of the CPU, so the default 80 never slows it down.