Installation

cs-routeros-bouncer supports multiple deployment methods. Choose the one that best fits your infrastructure.

Docker Compose

Ideal if you already run CrowdSec in Docker.

Basic setup

services:
  cs-routeros-bouncer:
    image: ghcr.io/jmrplens/cs-routeros-bouncer:latest
    container_name: cs-routeros-bouncer
    restart: unless-stopped
    ports:
      - "2112:2112" # Prometheus metrics (optional)
    environment:
      CROWDSEC_URL: "http://crowdsec:8080/"
      CROWDSEC_BOUNCER_API_KEY: "your-bouncer-api-key"
      MIKROTIK_HOST: "192.168.0.1:8728"
      MIKROTIK_USER: "crowdsec"
      MIKROTIK_PASS: "your-password"

With config file

The Docker image can run from environment variables alone. If you prefer a YAML file, mount it at /etc/cs-routeros-bouncer/config.yaml; the bouncer loads that file automatically when it exists:

services:
  cs-routeros-bouncer:
    image: ghcr.io/jmrplens/cs-routeros-bouncer:latest
    container_name: cs-routeros-bouncer
    restart: unless-stopped
    ports:
      - "2112:2112"
    volumes:
      - ./config.yaml:/etc/cs-routeros-bouncer/config.yaml

Start the service:

docker compose up -d

Tip

All configuration options can be set via environment variables. See the Configuration section for the full list.

Binary + systemd

Automatic setup (recommended)

1. Download the latest release

   # Replace architecture as needed: amd64, arm64, armv7
   wget https://github.com/jmrplens/cs-routeros-bouncer/releases/latest/download/cs-routeros-bouncer_linux_amd64.tar.gz
   tar xzf cs-routeros-bouncer_linux_amd64.tar.gz

2. Run automated install

   sudo ./cs-routeros-bouncer setup

3. Configure

   sudo nano /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml
   sudo systemctl restart cs-routeros-bouncer

The automated setup copies the binary, creates the config directory, writes a hardened systemd unit, enables the service, and starts it.

The setup subcommand accepts optional flags:

| Flag | Default | Description | | ------------- | ------------------------------------ | --------------------------------- | | -bin | /usr/local/bin/cs-routeros-bouncer | Installation path for the binary | | -config-dir | /etc/cs-routeros-bouncer | Directory for configuration files |

The generated config is /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml unless -config-dir changes the directory.

Manual setup

Manual installation steps (click to expand)

# Download
wget https://github.com/jmrplens/cs-routeros-bouncer/releases/latest/download/cs-routeros-bouncer_linux_amd64.tar.gz
tar xzf cs-routeros-bouncer_linux_amd64.tar.gz

# Install binary
sudo install -m 755 cs-routeros-bouncer /usr/local/bin/

# Create config directory and copy config
sudo mkdir -p /etc/cs-routeros-bouncer
sudo cp cs-routeros-bouncer.yaml /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml

# Edit configuration
sudo nano /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml

# Create systemd service
sudo tee /etc/systemd/system/cs-routeros-bouncer.service > /dev/null << 'EOF'
[Unit]
Description=CrowdSec RouterOS Bouncer
After=network-online.target crowdsec.service
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/cs-routeros-bouncer -c /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml
Restart=on-failure
RestartSec=10
TimeoutStopSec=90
LimitNOFILE=65536

# Hardening
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/log
PrivateTmp=yes

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now cs-routeros-bouncer

Uninstall

# Keep config files
sudo cs-routeros-bouncer uninstall

# Also remove config
sudo cs-routeros-bouncer uninstall -purge

uninstall also accepts -bin and -config-dir if setup used custom paths. Pass the same -config-dir with -purge to remove that custom configuration directory.

See the CLI Reference for all setup and uninstall flags.

Build from source

Prerequisites

• Go 1.26.3+ — Download
• Make — typically pre-installed on Linux

Build and install

1. Clone and build

   git clone https://github.com/jmrplens/cs-routeros-bouncer.git
   cd cs-routeros-bouncer
   make build

   The binary is created at bin/cs-routeros-bouncer.

2. Install

   # Option 1: Automated install
   sudo bin/cs-routeros-bouncer setup
   
   # Option 2: Manual install
   sudo install -m 755 bin/cs-routeros-bouncer /usr/local/bin/

Verify installation

After installing with any method, verify the bouncer is running correctly:

1. Check service status

   # Binary installation
   sudo systemctl status cs-routeros-bouncer
   
   # Docker Compose
   docker compose ps cs-routeros-bouncer

2. Check health endpoint

   curl http://localhost:2112/health
   # {"status":"ok","routeros_connected":true,"version":"vX.Y.Z"}

3. Check logs

   # Binary installation
   sudo journalctl -u cs-routeros-bouncer -f
   
   # Docker Compose
   docker compose logs -f cs-routeros-bouncer

4. Verify router-side rules

   /ip/firewall/filter/print where comment~"crowdsec"
   /ip/firewall/raw/print where comment~"crowdsec"
   /ip/firewall/address-list/print where list=crowdsec-banned

Next: Configuration Reference Customize all bouncer settings including firewall rules, filtering, and metrics.