balboa for Debian
-----------------

Configuration
=============

The balboa package uses YAML configuration files located in /etc/balboa/:

  * feeders.yaml  - Defines input sources (HTTP, socket, AMQP, NMSG, etc.)
  * backend.yaml  - Defines backend server(s) to send observations to

Service startup arguments are configured in /etc/default/balboa.

The balboa-backend-rocksdb package stores its database in /var/lib/balboa/db/
and is configured via /etc/default/balboa-backend-rocksdb.


Upgrading from 2.0.x to 2.1.x
=============================

Version 2.1.x introduced significant configuration changes. The upgrade
process provides upgrade notices, but manual intervention may be required
in some cases.

Key changes:

1. New backend.yaml configuration file
   The frontend now requires a backend.yaml file to specify which backend(s)
   to connect to. A default configuration is installed automatically.

2. Updated /etc/default/balboa
   If you have a customized /etc/default/balboa from version 2.0.x, you must
   add the -b parameter to specify the backend configuration:

     BALBOA_ARGS=-f /etc/balboa/feeders.yaml -b /etc/balboa/backend.yaml -l /var/log/balboa.log

   The postinst script will print a warning if it detects an old configuration
   without the -b flag.

3. Removed database.yaml
   If you still have /etc/balboa/database.yaml from older installations,
   please note that it is no longer used. Backend configuration is now
   separate from the frontend and managed by the balboa-backend-* packages.

4. Changed feeder defaults
   The default feeders.yaml no longer includes socket-based inputs. If you
   need gopassivedns or suricata_dns socket inputs, add them manually:

     - name: Socket Input
       type: socket
       path: /var/run/balboa/balboa-gopassivedns.sock
       input_format: gopassivedns

5. Backend defaults file renamed
   The environment file for the RocksDB backend changed from
   /etc/default/balboa-rocksdb to /etc/default/balboa-backend-rocksdb.


Troubleshooting
===============

If balboa fails to start after an upgrade:

  1. Check that /etc/balboa/backend.yaml exists:
       ls -la /etc/balboa/backend.yaml

  2. Verify /etc/default/balboa contains the -b flag:
       grep -- '-b' /etc/default/balboa

  3. Check service status and logs:
       systemctl status balboa
       journalctl -u balboa

  4. Ensure the backend is running:
       systemctl status balboa-backend@rocksdb


 -- Sascha Steinbiss <satta@debian.org>  Wed, 09 Jul 2025 21:41:54 +0200