linuxaid-cli

Part of Linuxaid by Obmondo

A Linux system management toolkit that automates Puppet-based configuration management and system updates across Obmondo-managed infrastructure. The project provides two command-line applications for initial provisioning and ongoing system maintenance.

Installation

Quick Install (Recommended)

The easiest way to install linuxaid-install is using the installation script:

curl -sSL https://raw.githubusercontent.com/Obmondo/linuxaid-cli/main/install.sh | bash

This script will:

• Detect your system architecture (amd64, arm64, armv7)
• Download the latest release from GitHub
• Verify the checksum for security
• Install the linuxaid-install binary to /usr/local/bin
• Automatically run the installation tool

Build from Source

If you prefer to build from source:

make build

This produces two binaries: linuxaid-install and linuxaid-cli.

Applications

linuxaid-install

Initial system provisioning tool that installs and configures the Puppet agent (openvox-agent). Obmondo customers authenticate with the TOKEN environment variable; opensource users can run it without a token.

Usage:

# Obmondo customers
TOKEN='your-token' linuxaid-install --certname web01.example --puppet-server your.openvoxserver.com --environment master

# Opensource users (no token required)
linuxaid-install --certname web01.example --puppet-server your.openvoxserver.com --environment master

linuxaid-cli

System management CLI for Puppet-managed nodes with commands for automated maintenance operations.

Commands:

• system-update - Executes distribution-specific package updates with service window coordination
• run-openvox - Runs Puppet agent with connectivity checks and status reporting

Usage:

linuxaid-cli system-update --certname web01.example --no-reboot
linuxaid-cli run-openvox --certname web01.example

Features

• Automated Puppet Agent Management: Complete lifecycle management including installation, configuration, and execution
• Remote Logging: gRPC-based streaming of command execution output to Obmondo API
• Service Window Coordination: Integrates with Obmondo backend for maintenance window management
• Multi-Distribution Support: Ubuntu, Debian, RHEL, CentOS, SLES, OracleLinux, and TurrisOS

Configuration

Configuration uses a three-tier precedence system via Viper:

1. Command-line flags (highest priority)
2. Environment variables
3. Default values

Global Flags

These flags are available for both linuxaid-install and linuxaid-cli:

• --certname / CERTNAME - Certificate name (defaults to the machine's FQDN)
• --debug / DEBUG - Enable debug logging
• --puppet-server / PUPPET_SERVER - Puppet server hostname (for linuxaid-install, required when no TOKEN is set; for linuxaid-cli, overrides the customer settings)

linuxaid-install Specific Flags

• --environment / -E / OPENVOX_ENVIRONMENT - Openvox environment to install (Linuxaid release version, default master)

linuxaid-cli Command-Specific Flags

system-update

• --no-reboot / NO_REBOOT - Disable automatic reboot after updates
• --skip-openvox / SKIP_OPENVOX - Skip Puppet agent run
• --security-exporter-url / SECURITY_EXPORTER_URL - URL of the security exporter (default: http://127.254.254.254:63396)

The Openvox environment for the run is not a flag: an automatic service window pins the Linuxaid tag its update cycle runs with, and the update uses that tag so every server in the group updates to the same release. Adhoc windows pin no tag, so those runs use the environment set for the server in Obmondo, falling back to master when the API cannot be reached.

run-openvox

• --environment / -E - Openvox environment for this run only. Without it, the environment set for the server in Obmondo is used, falling back to master when the API cannot be reached. The value is never sent to Obmondo, so it applies to that single run
• --tag - Restrict this run to the given openvox tags (comma-separated), mapping to puppet agent --tags. Without it the agent applies the full catalog

Project Layout

cmd/linuxaid-cli/        cobra wiring for the agent binary: flags, and the Config built from them
cmd/linuxaid-install/    cobra wiring for the installer binary
internal/app/            the three workflows: system-update, run-openvox, install
internal/system/         the host itself: os-release, apt/yum/zypper, kernel and reboot, root check
internal/shell/          the one place commands are run; shelltest provides a Runner for tests
internal/puppet/         openvox agent lifecycle
internal/obmondo/        Obmondo API client
internal/certs/          certname and customer id resolution
internal/config/         the Config for a run, assembled from flags and environment
internal/{disk,httpx,logger,prettyfmt,progress,provisioner,security,webtee}/

Three rules keep this from silting up again:

• cmd/ only wires things together. Flags are parsed and a config.Config is built there; every workflow takes that Config as an argument. Nothing under internal/ reads flags, environment variables, or a global viper instance to find out what it was asked to do.
• Library code returns errors, it does not exit. Only main decides the process exit code. This matters beyond testability: system-update re-enables the puppet agent in a deferred cleanup, and an os.Exit further down would skip it and leave the agent disabled on the node.
• Commands go through shell.Runner. Anything that shells out takes a Runner, so tests substitute shelltest.Recorder instead of needing a machine with apt and puppet on it.

Release Management

Releases are managed via Cocogitto (cog) based on Conventional Commits history.

To cut a new release, simply run:

make release

This command will:

1. Verify you are on the main branch.
2. Fetch tags and pull the latest changes with rebase from both remotes (github and origin).
3. Automatically determine the version bump (--auto) based on conventional commits since the last tag (or specify a bump level, e.g. make release --patch, make release --minor, or make release --major).
4. Create the release commit and tag locally, and push the tag to both remotes (github and origin).
5. Pushing tags to the remotes automatically triggers GitHub Actions and Gitea workflows to build binaries and publish releases.

Dependencies

• Cobra for CLI framework
• Viper for configuration management
• gRPC for remote logging
• Bitfield/script for shell command execution