Secure, compliant Linux infrastructure — managed and automated at scale.

Website • How It Works • Getting Started • Documentation • Roles Reference • Contributing

LinuxAid is a comprehensive platform for managing secure and reliable Linux operations at scale. Built on OpenVox (an open-source, Puppet-compatible configuration management system), LinuxAid provides infrastructure automation, monitoring, and compliance management for enterprise Linux environments — from a handful of servers to fleets of tens of thousands.

Everything is declarative and version-controlled: infrastructure is defined as code, changes are previewed before they touch production, and the full history lives in Git.

• Key Features
• How It Works
  • Add a Server in 3 Steps
  • Architecture
• Managed Responsibilities
• Configuration Options
• Proven at Enterprise Scale
• High Availability
• Supply Chain Security & Repository Management
• Getting Started
• Documentation
• Contributing
• License

Scale: LinuxAid is designed to manage from dozens to thousands of nodes, on architecture proven to support 20,000+ servers.

A lightweight LinuxAid-Agent runs on each of your servers. It applies the configuration and security policy you've chosen, then continuously reports health and metrics back to a central monitoring stack. You build your application; LinuxAid handles the rest.

Works on physical servers, virtual machines, cloud instances, and your own datacenter — on any supported Linux distribution.

The LinuxAid-Agent sits between your infrastructure and the monitoring stack. It receives policies and configuration from the control plane, runs exporters locally, and pushes metrics out over a secure channel — so nothing needs to reach into your servers.

What the agent does on each server

• Collects system, application, and service metrics
• Monitors processes and services, with health checks and status reporting
• Manages configuration and keeps the system in its desired state
• Receives policies and updates from the control plane
• Runs exporters — Node Exporter for system metrics, Security Exporter for CVE scanning
• Sends metrics to Prometheus over a secure, outbound-only channel

Beyond metrics, LinuxAid also manages

Because configuration is declarative, the agent re-checks the server on every run and corrects any drift. Changes are previewed before they reach production, and every change is version-controlled in Git.

graph TB
    git[Git Repository]
    hiera[Hiera Data]
    enc[External Node Classifier]
    openvox[OpenVox Server]

    common[common module]
    role[role module]
    profile[profile module]
    monitor[monitor module]

    linux_servers[Linux Servers]

    git -->|version control| hiera
    hiera -->|data lookup| openvox
    enc -->|certname + facts| openvox

    openvox -->|includes| common
    openvox -->|includes| role
    openvox -->|includes| profile
    openvox -->|includes| monitor

    common -->|configures| linux_servers
    role -->|orchestrates| linux_servers
    profile -->|implements| linux_servers
    monitor -->|observes| linux_servers

The detailed feature breakdown and managed-responsibilities checklist — deployment patterns, subscription tiers, operational modes, security/compliance coverage, and the full responsibilities matrix — live in docs/features-and-responsibilities.md.

LinuxAid provides true data ownership with no vendor lock-in:

• Your setup runs on your servers
• Infrastructure code remains on your systems
• Full control even after subscription ends
• Can be hosted on-premises or in any cloud

The Kubernetes setup is documented in KubeAid and can scale from single-host to multi-node clusters with component-level scaling.

Every module used by LinuxAid documents its parameters in a REFERENCE.md file, following the standard Puppet module documentation convention.

• Roles — the list of roles (software and configs currently supported). Some roles support mixing, but multiple roles cannot always be assigned to a server as they can conflict.
• Common Settings — configurations that can be rolled out to any server, regardless of its role.
• Monitoring Settings — settings for monitoring.

Options can be applied at different scopes:

• Tags — groups defined by the OpenVox ENC
• Facts — over 7,000 available facts (OS/distribution/software versions, location, hardware configuration, etc.). See Facts documentation for details.

LinuxAid leverages Hiera's hierarchical data lookup system to separate data from code:

• Same codebase across dev, staging, and production
• Override data at the appropriate specificity level (node, location, OS, etc.)
• Clear separation between code logic and environment-specific data
• Similar flexibility to Helm values in Kubernetes

See hiera.yaml for the full hierarchy configuration, starting at the hierarchy: section.

LinuxAid ships out-of-the-box, production-ready support for 60+ applications, including:

• Web servers — Nginx, Apache, HAProxy
• Databases — MySQL, PostgreSQL, MongoDB
• Monitoring — Prometheus, Grafana
• Mail servers — Mailcow
• VPN — WireGuard
• CI/CD — GitLab
• ...and many more, all pre-configured to follow best practices.

The Puppet/OpenVox architecture LinuxAid is built on has been proven at massive scale:

Why this architecture scales:

• Declarative configuration — define desired state, not steps
• Change calculation — preview all changes before execution
• Heterogeneous support — manage diverse systems with a single codebase
• Operational maturity — battle-tested at scale

What LinuxAid adds on top:

• 60+ pre-configured applications
• Built-in compliance frameworks (GDPR, CIS, NIS2)
• Enterprise-grade monitoring out of the box
• Years of Obmondo's operational expertise

At scale, change-preview capability becomes essential: it can reduce 30,000 servers to 5–7 distinct changeset patterns, preventing incidents from untested changes and enabling confident deployments with multiple contributors.

LinuxAid runs under a Kubernetes setup (documented in KubeAid), deployable on:

• A single-host Linux server
• A multi-node high-availability cluster
• Any cloud provider or on-premises

The OpenVox Server is written in Clojure with workload separation:

• Compiler — builds configurations (CPU-intensive work)
• API Layer — handles agent communications
• Independent scaling — scale components based on workload

LinuxAid includes built-in supply chain protection and package repository management:

• Air-Gapped Operation — package repository mirroring lets servers operate securely without direct internet connectivity
• Automated GPG Package Signing — the packagesign daemon pulls RPM/Deb packages built by CI/CD, GPG-signs them, and publishes them to trusted repositories
• GPG Git Verification — protects against compromised Git hosts by verifying GPG signatures on release branches before CI runners execute build pipelines
• Staged Snapshot Rollouts — hardlink-based repository snapshots let security updates be staged and rolled out to server groups incrementally

1. Set certname to hostname.customer_id format
2. Create node file in agents/<certname>.yaml in the customer's hiera-data repository
3. Assign role(s) via the classes: parameter
4. Run the Puppet agent: puppet agent -t to apply the initial configuration

Node classification is handled by the External Node Classifier (see puppet_enc.rb), which resolves the certname and facts into the classes and Hiera data for that node.

To connect your Git hosting platform to your Obmondo environment, see the Git Setup guide.

Contributions are welcome. Please read CONTRIBUTING.md for the development workflow, and CODE_OF_CONDUCT.md (DPGA-compliant) before opening issues or pull requests.

LinuxAid is licensed under the GNU Affero General Public License v3.0.