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.
Table of Contents
- Key Features
- How It Works
- Managed Responsibilities
- Configuration Options
- Proven at Enterprise Scale
- High Availability
- Supply Chain Security & Repository Management
- Getting Started
- Documentation
- Contributing
- License
Key Features
| Configuration | Monitoring | Security & Compliance | Automation | Platforms |
|---|---|---|---|---|
| ✅ Hierarchical data model (Hiera) | ✅ 11+ Prometheus exporters | ✅ GDPR-ready configurations | ✅ GitOps change preview | ✅ Any Linux distro supported by OpenVox/Puppet |
| ✅ Role-based abstractions | ✅ Auto hardware detection | ✅ CIS benchmark configurations | ✅ Automated system updates with safety checks | ✅ Single-host or multi-node HA (Kubernetes) |
| ✅ 60+ pre-configured applications | ✅ SSL certificate monitoring | ✅ NIS2 compliance | ✅ Staged, hardlink-based repo rollouts | ✅ Cloud, on-prem, or air-gapped |
| ✅ Multi-customer, isolated configs | ✅ Pre-built Grafana dashboards | ✅ GPG-signed packages | ✅ Agents pull config on a configurable interval | ✅ Subscription-tiered feature management |
| ✅ Data ownership, no vendor lock-in | ✅ AlertManager, tier-based routing | ✅ GPG-verified Git releases | ✅ Auto-deployed exporters based on role/facts | ✅ Secure mesh VPN access (no exposed SSH) |
Scale: LinuxAid is designed to manage from dozens to thousands of nodes, on architecture proven to support 20,000+ servers.
How It Works
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.
Add a Server in 3 Steps
| Step | What happens | |
|---|---|---|
| 1 | Add server — give it a hostname | Obmondo creates a unique identity for your server |
| 2 | Choose configuration & subscription — pick the role it should run | Configuration and support tier are applied to your server |
| 3 | Run one command as root | LinuxAid-Agent installs, connects, and starts managing the server |
Works on physical servers, virtual machines, cloud instances, and your own datacenter — on any supported Linux distribution.
Architecture
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
| Service windows | Schedule and manage maintenance windows with zero downtime |
| Configuration management | Enforce desired state and track configuration changes |
| Security & compliance | Continuous security scans, CVE reports, and compliance monitoring |
| Logging | Centralized logs for better visibility and troubleshooting |
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.
Under the hood — OpenVox, Hiera, and the module layers
LinuxAid is built on OpenVox, a Puppet-compatible configuration management system. The agent is an openvox-agent; the control plane compiles a catalog for each node and the agent applies it.
Control plane
- OpenVox Server — compiles catalogs by combining module code with Hiera data
- Hiera — hierarchical data lookup, from node-specific overrides down to global defaults
- External Node Classifier — resolves a node's certname and facts into its classes and data
- Git — all configuration is version-controlled
Configuration module layers
- common — foundation layer: system baseline (users, SSH, packages, monitoring)
- profile — implementation layer: how to deploy a specific technology
- role — business logic layer: what services a node should run
- monitor — observability layer: service health checks and metrics
Managed infrastructure
- Agents pull configuration every 30 minutes (configurable)
- Services are deployed and managed declaratively
- Prometheus exporters are deployed automatically based on roles and system facts
Support systems
- Package repositories — serve openvox-agent and monitoring exporters
- Netbird VPN — secure node access without exposing SSH
- Automated system updates — applied with safety checks
Managed Responsibilities
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.
Data Ownership and Licensing
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
| Deployment Option | Description | Use Case |
|---|---|---|
| Single Host | OpenVox server on a single Linux server | Small deployments |
| HA Cluster | Multi-node Kubernetes cluster | Production environments |
| Cloud | AWS, Azure, GCP, or any provider | Cloud-native deployments |
| On-Premises | Self-hosted infrastructure | Security/compliance requirements |
The Kubernetes setup is documented in KubeAid and can scale from single-host to multi-node clusters with component-level scaling.
Configuration Options
Every module used by LinuxAid documents its parameters in a REFERENCE.md file, following the standard Puppet module documentation convention.
LinuxAid Modules
- 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.
Configuration Scopes
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.
Hierarchical Data Management with Hiera
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.
60+ Supported Applications
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.
Proven at Enterprise Scale
The Puppet/OpenVox architecture LinuxAid is built on has been proven at massive scale:
| Deployment | Scale | Evidence |
|---|---|---|
| Puppet Enterprise | 20,000+ nodes | Officially documented support |
| GitHub | Thousands of nodes | 500,000+ lines of Puppet code, 200+ contributors |
| Financial Institutions | 30,000+ servers | Major banks in highly regulated environments |
| Enterprise Deployments | 100,000+ servers | Organizations across various industries |
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.
High Availability
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
Supply Chain Security & Repository Management
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
packagesigndaemon 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
Getting Started
Adding a New Node
- Set certname to
hostname.customer_idformat - Create node file in
agents/<certname>.yamlin the customer's hiera-data repository - Assign role(s) via the
classes:parameter - Run the Puppet agent:
puppet agent -tto 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.
Documentation
Setup & Operations
| Guide | Description |
|---|---|
| Git Setup | Connect your Git hosting platform to your Obmondo environment |
| Netbird VPN | Secure node mesh VPN setup |
| Eyaml Secrets | Encrypted Hiera data management |
| Updates | Updating Puppet modules and the Puppetfile |
| Release Process | Tagging and publishing a LinuxAid release |
| Turris Install | Installing LinuxAid on Turris routers with Netbird |
Monitoring & Security
| Guide | Description |
|---|---|
| Monitoring | Kube Prometheus stack, Grafana, and alerting |
| Puppetboard | Web dashboard for OpenVox/Puppet |
| OpenVAS Setup | Greenbone vulnerability scanner deployment |
| ZFS Replication | Sanoid/Syncoid automated ZFS backup setup |
Reference
| Reference | Description |
|---|---|
| Roles | Pre-configured application roles |
| Facts | Fact-based configuration targeting |
| Features & Responsibilities | Feature matrix and operational scope |
| IaC Comparisons | Architectural comparison vs. Ansible, Terraform, Puppet |
| Generating Docs | Regenerating module REFERENCE.md with Puppet Strings |
Contributing
Contributions are welcome. Please read CONTRIBUTING.md for the development workflow, and CODE_OF_CONDUCT.md (DPGA-compliant) before opening issues or pull requests.
License
LinuxAid is licensed under the GNU Affero General Public License v3.0.