v0.2.0-rc5

Breaking Changes

As outlined in the 0.1.0 release, every minor version before 1.0.0 may contain breaking changes.
Please review the sections below carefully before upgrading to avoid service interruptions.

---

TL;DR (Key Changes)

• Parent/worker model removed – the SPOA now runs as a single process.
• workers, worker_user, worker_group options removed – replaced by listen_tcp / listen_unix.
• admin_socket removed – the setting is now ignored and can be deleted.
• Service now runs fully as crowdsec-spoa user – config/log file permissions must allow this.
• Docker image now runs as crowdsec-spoa.
• Default log directory moved to /var/log/crowdsec-spoa/ (config change required).

---

Inner Architecture

In short:
We removed the parent/worker architecture and now run a simpler, single-process model.

Background

Previously:

• Multiple workers handled incoming SPOE messages from HAProxy.

• Each worker communicated with a parent process over a Unix socket to fetch:

  • State
  • Decisions
  • Host configuration (e.g. ban / captcha)

This design existed to support multiple SPOA listeners from a single process.

In practice, we found that users almost never configured more than one SPOA listener.
The added complexity:

• Slowed down feature development,
• Increased code debt,
• Made onboarding new contributors harder.

As a result, we have simplified the architecture to a single process that directly handles SPOE messages.

Configuration Changes

We have removed the following YAML options:

• workers
• worker_user
• worker_group

These are replaced with:

listen_tcp: 127.0.0.1:9090
listen_unix: /path/to/unix.sock

Recommendation:
Add these keys to your configuration before upgrading to avoid startup failures.

---

Admin Socket

Because we no longer support multiple SPOA listeners, the admin socket no longer provides value.

• The following option has been removed and is now ignored:

admin_socket: /path/to/admin.sock

You can safely remove this key from your configuration.

We know users still need a way to reload the SPOA without dropping in-flight messages from HAProxy.
In a future release, we plan to add a proper systemctl reload hook to handle this cleanly.

---

Process Owner (systemd Unit)

With the removal of the parent/worker model and the admin socket, the systemd unit now runs entirely as the crowdsec-spoa user.

This improves separation between service accounts and root, but it also means:

• All files needed by the SPOA must be readable by the crowdsec-spoa group.

For example:

chown root:crowdsec-spoa /etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml
chmod 640 /etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml

If you have created .local variants of these configuration files, please run equivalent commands for those files as well.

Note:
The DEB/RPM packages are patched to adjust these permissions on upgrade.
If you encounter issues, manually validate permissions/ownership and open an issue on this repository if problems persist.

---

Dockerfile

The Docker image has also been updated to run as the crowdsec-spoa user.

If you are building the container locally and mounting configuration files, ensure that:

• The mounted configuration is readable by crowdsec-spoa.

---

Log Files

Since the systemd unit now runs as crowdsec-spoa, it can no longer write to the root-owned default /var/log directly.

The unit is configured to create a dedicated directory:

/var/log/crowdsec-spoa

Please update your YAML configuration accordingly:

log_dir: /var/log/crowdsec-spoa/

Note:
The DEB/RPM packages may not clean up old log files in previous locations.
After the upgrade, you may want to manually remove any obsolete log files or directories.