Ctrlk

Alpine Linux

Install the LinuxGuard agent on Alpine Linux via the APK repository — OpenRC service management and musl libc considerations.

This guide covers installing the LinuxGuard agent on Alpine Linux, commonly used in containers and lightweight environments.

Important: Alpine Linux uses OpenRC (not systemd) for service management and musl libc (not glibc). Commands in this guide differ from other distribution guides accordingly.

Note: Supported architectures — Alpine packages ship for amd64, arm64, and armv7 (with best-effort riscv64). ARMv7 deployments run in DegradedNoEBPFArch mode with no eBPF-derived telemetry. See Multi-Architecture Support for the per-architecture capability matrix.

Prerequisites

Before installing, ensure your system meets these requirements:

  • Kernel: Linux kernel 4.18 or later

  • Permissions: Root or sudo access

  • Network: Outbound HTTPS access to packages.linuxguard.io

  • curl: The curl package (not installed by default on Alpine minimal)

Note: For complete system requirements including architecture and detailed prerequisites, see the Prerequisites Guide.

To install curl if not already present:

sudo apk add curl

Repository Setup

The recommended installation method uses the APK package manager to install LinuxGuard from the official repository.

Step 1: Import GPG Key

Create the APK keys directory and import the LinuxGuard signing key:

Step 2: Add Repository

Add the LinuxGuard repository to your system:

Step 3: Install Agent

Update the package index and install the agent:

The installer will also install the sysstat dependency, which provides iostat and mpstat for system metrics collection.

Step 4: Enable and Start Service

Alpine uses OpenRC for service management. Enable the agent to start at boot and start the service:

Note: Alpine uses OpenRC for service management. Use rc-service and rc-update instead of systemctl.

Direct Download

If you prefer to download and install the package manually, you can download the APK package directly:

Note: Manual installation does not configure automatic updates. We recommend using the repository method for production systems.

ARM64 installation

The APK repository at packages.linuxguard.io/apk/alpine publishes packages for x86_64, aarch64 (arm64), and armv7 (with best-effort riscv64). The repository URL in Step 2 is architecture-neutral — apk update selects the matching package automatically based on the host's architecture.

To confirm your host is arm64 before installing:

The arm64 APK ships the same agent binary + compiled eBPF probe object as the amd64 APK — arm64 is a full-eBPF architecture per the capability matrix. No degradation, no missing telemetry.

If your host is ARMv7 (armv7l, armhf), the package is still available via the APK repository but the agent runs in Degraded mode — the eBPF probe is a zero-byte sentinel and no behavioral telemetry is produced. Alpine on ARMv7 is commonly used for SBC deployments (e.g., Raspberry Pi 3 / 4 running Alpine in 32-bit mode); treat these hosts as a documented gap in the evidence chain.

Note: Alpine on arm64 is widely used as a container base image (and in this case the agent typically runs in a container deployment shape rather than via the APK install — see Container deployment hub). The APK install path applies when the host is bare-metal or VM-based Alpine.

Note: For containerized arm64 deployments (Kubernetes DaemonSet on an arm64 node pool, Docker on an arm64 host), the OCI multi-arch manifest selects the arm64 image automatically when pulling packages.linuxguard.io/linuxguard-agent:vX.Y.Z. See OCI multi-arch manifest for the manifest inspection and --platform pull syntax.

Verification

After installation, verify the agent was installed correctly:

Check Agent Binary

Confirm the agent binary is installed:

Expected output:

Verify Agent User

Confirm the dedicated linuxguard user was created:

Expected output (UID/GID may vary):

Check Service Status

Verify the agent service is running (OpenRC command):

Expected output:

The agent is now installed and ready for enrollment.

Alpine-Specific Considerations

musl vs glibc

Alpine uses musl libc instead of glibc. The LinuxGuard agent package for Alpine is specifically compiled against musl. Do not install Debian/Ubuntu or RedHat/CentOS packages on Alpine — they are compiled against glibc and will not run.

Container Environments

Alpine is commonly used as a container base image due to its small size (3-10MB vs 100-300MB for Debian/Ubuntu). For container-specific installation instructions, see the Container Installation Guide.

Troubleshooting

Service Commands Not Working

Issue: systemctl: command not found or systemctl commands fail.

Solution: Alpine uses OpenRC, not systemd. Use rc-service linuxguard-agent <command> instead of systemctl <command> linuxguard-agent. Most common mistake when switching from other distributions.

Binary Compatibility Errors

Issue: Agent fails to start with library or symbol errors.

Solution: Verify you installed the Alpine-specific package. This error typically indicates a glibc vs musl mismatch. Reinstall using apk add linuxguard-agent from the Alpine repository.

Missing curl

Issue: Repository setup fails because curl is not installed.

Solution: Alpine minimal installations don't include curl by default. Install with:

Note: For additional troubleshooting guidance, see the Troubleshooting Guide.

Next Step: Configuration →

Related: Installation Overview | Prerequisites | Container Installation

PreviousSUSE / openSUSENextContainer Deployment

Last updated

Was this helpful?