fb-agent: Single-Binary Fluent Bit Manager for Linux in Go

Managing Fluent Bit across dozens of Linux servers is tedious work — repository setup, config generation, systemd unit hardening, certificate rotation, and health monitoring all need to happen consistently on every host. I built fb-agent, a single-binary Fluent Bit agent for Go on Linux, to reduce this entire lifecycle to one static executable with zero runtime dependencies. You compile it once, copy it anywhere, and run a handful of commands to get a fully operational, monitored, mTLS-secured log pipeline. The source code is publicly available on GitHub.

Why I Needed a Single-Binary Fluent Bit Agent

In my infrastructure work I manage heterogeneous Linux environments — bare-metal, LXC containers, Docker hosts, cloud VMs. Each needs Fluent Bit installed, configured with the right inputs for whatever services are running (Nginx, PostgreSQL, Redis, Fail2Ban, Docker, and more), connected to a central VictoriaLogs endpoint with optional Cloudflare Access auth, and kept alive. Deploying Ansible playbooks or maintaining per-host config repositories gets expensive fast.

The alternative I wanted: a single go build artifact that self-installs, self-registers, and self-heals. No Python, no Ruby, no local package manager quirks. Just one binary that knows everything it needs to know.

What fb-agent Does: Five Core Commands

The Fluent Bit agent Go Linux workflow is built around five subcommands, each handling a distinct phase of the lifecycle:

• install — detects the OS, adds the official Fluent Bit repository (with automatic fallback from Debian trixie → bookworm if needed), installs the package, auto-detects running services (SSH, Nginx, PostgreSQL, Redis, Rocket.Chat, Fail2Ban, Docker, HAProxy, and 15+ others), generates fluent-bit.conf with the right input plugins, deploys enrich.lua, optionally configures mTLS, writes a hardened systemd unit, and starts the service.
• register — collects a host fingerprint (public and private IPs, open ports, hardware info, detected services) and ships it to VictoriaLogs so every host is discoverable from the central observability stack.
• watchdog — performs a one-shot health check against the Fluent Bit health endpoint and retries failed outputs, useful as a manual diagnostic or a lightweight cron step.
• daemon — runs as a long-lived process that replaces four separate systemd timers: watchdog every 5 minutes, register every 24 hours, certificate renewal every 7 days, and an alert if the host goes offline for more than 6 hours.
• mTLS — generates and signs client/server certificates using pure Go crypto (no openssl dependency), enabling mutual TLS between fb-agent and the VictoriaLogs endpoint.

Zero-Dependency Build: CGO_ENABLED=0

The key design constraint is static compilation. Building fb-agent is a single command:

CGO_ENABLED=0 go build -o fb-agent .

The result is a fully static ELF binary — no glibc dependencies, no shared libraries, no interpreter — that runs identically on amd64 and arm64 targets. Deploy it to a fresh Debian 12 minimal install, an Alpine-based Docker container, or an LXC container without a full init system, and it just works. This matters especially for air-gapped environments or CI/CD pipelines where you want a self-contained artifact rather than a managed runtime.

For infrastructure that spans multiple architectures, this single-binary approach replaces configuration management tools or per-distro package repos. I use it alongside my broader IT consulting work for clients who need reliable log pipelines without operational overhead.

Configuration via Environment Variables

fb-agent is configured entirely through environment variables — no config files to manage, no YAML to template:

• VL_HOST / VL_PORT — VictoriaLogs endpoint
• FB_HOSTNAME — override the hostname used in log labels
• FB_JOB — workload type: lxc, remote, docker, or vm
• FB_LOG_PATHS — comma-separated list of additional log paths to tail
• FB_GZIP — enable gzip compression on the output stream
• CF_CLIENT_ID / CF_SECRET — Cloudflare Access service token for protected endpoints

This ENV-first approach integrates naturally with container orchestrators (Kubernetes, Nomad), systemd EnvironmentFile directives, or simple shell scripts. No config templating layer required. For large-scale deployments, this is the difference between a 10-minute rollout and a multi-day configuration management project — something I’ve seen firsthand in my infrastructure automation engagements.

Auto-Detection of Services: 15+ Inputs

One of the more useful features is the service auto-detection that runs during install. Rather than requiring you to manually enumerate which services are running on each host, fb-agent probes systemd units, checks common socket paths, and scans process lists to determine which Fluent Bit input plugins to enable. Supported services include:

• System: SSH, systemd journal, kernel log, auth.log
• Web: Nginx, Apache, HAProxy
• Databases: PostgreSQL, MySQL/MariaDB, Redis, MongoDB
• Containers: Docker (container logs + daemon log)
• Security: Fail2Ban, UFW/iptables
• Apps: Rocket.Chat, custom paths via FB_LOG_PATHS

The generated fluent-bit.conf contains only the inputs that are actually present, avoiding empty input sections that would cause warnings. The accompanying enrich.lua script adds host metadata (hostname, job type, environment) as structured fields on every log record — making host-level filtering in VictoriaLogs trivial.

Daemon Mode: Replacing Four systemd Timers

Most monitoring setups that use Fluent Bit end up with a cluster of systemd timers: one for health checks, one for host registration, one for cert renewal, one for alerting. Managing four timer units per host adds up quickly. The daemon command consolidates all of this into a single long-running process with built-in scheduling:

• Every 5 minutes: watchdog health check + output retry
• Every 24 hours: re-register host fingerprint with VictoriaLogs
• Every 7 days: mTLS certificate renewal (pure Go, no openssl)
• Alert threshold: if Fluent Bit has been offline for more than 6 hours, trigger an alert

Run daemon mode under its own hardened systemd unit (generated by install) and you get a self-managing log agent with no cron dependency. This is exactly the kind of operational simplicity I aim for in the risk-managed infrastructure I build for clients.

52 Automated Verifications

The repository includes verify.py — a test harness with 52 automated checks that validate everything from binary size and static linking to config correctness, cert validity, and daemon scheduling logic. Running the full suite takes under a minute and catches regressions before they reach production hosts. This kind of automated verification is standard practice in the infrastructure tooling I ship — it’s the difference between “it works on my machine” and a tool you can confidently deploy at scale.

The project is actively maintained and open source. Contributions, issues, and forks are welcome at github.com/razqqm/fb-agent.

FAQ

Does fb-agent work on ARM (Raspberry Pi, ARM servers)?

Yes. Because the binary is built with CGO_ENABLED=0, it compiles to a fully static binary for both amd64 and arm64 targets. You can cross-compile on any Go-capable machine and copy the result to an ARM host with no additional setup.

Can I use fb-agent without VictoriaLogs?

The install and watchdog commands work without a VictoriaLogs endpoint — they configure and monitor Fluent Bit locally. The register and daemon commands require VL_HOST and VL_PORT to be set. If you’re using a different log backend, you can modify the output plugin configuration in the generated fluent-bit.conf.

How does mTLS certificate renewal work?

fb-agent implements certificate generation and signing entirely in Go’s standard crypto/tls and crypto/x509 packages — no openssl, no cfssl, no external CA tool required. In daemon mode, cert renewal runs automatically every 7 days. For manual renewal, run fb-agent mTLS directly.

What Linux distributions are supported?

The install command targets Debian/Ubuntu-based distributions and uses the official Fluent Bit APT repository. The binary itself runs on any Linux system where you can execute a static ELF binary. The fallback logic (trixie → bookworm) handles edge cases where the latest Fluent Bit repo doesn’t yet support the newest Debian release.

If you’re managing Linux infrastructure and want to discuss log pipeline architecture, observability strategy, or related security tooling, I’m happy to connect. Reach out here.