Container Installation

⚠️ Important Notice: Container Support Disclaimer

Container support is currently experimental, especially for minimal images, due to limitations in capabilities required to run services. We are actively investigating solutions to improve container support. Some features may not work as expected in containerized environments.

This guide covers installing and configuring the LinuxGuard agent in containerized environments. The agent can be installed in containers using the same package repositories as traditional installations.

Overview

The LinuxGuard agent can be installed in containers using standard package managers. The installation process is similar to traditional installations, but there are some container-specific considerations:

• Persistence: Agent configuration and state need to be persisted across container restarts

• Volumes: Mount volumes for configuration and logs

• Networking: Ensure the container has network access to api.linuxguard.io

• Base Images: Use base images that match supported distributions (Debian, RedHat, Alpine)

Installation Methods

Method 1: Install in Dockerfile

You can install the LinuxGuard agent directly in your Dockerfile. This approach is recommended for custom images where you want the agent pre-installed.

Debian/Ubuntu-based Containers

FROM debian:bookworm

# Install prerequisites
RUN apt-get update && apt-get install -y curl

# Add LinuxGuard repository
RUN curl -fsSL https://packages.linuxguard.io/apt/add-linuxguard-repo.sh | bash

# Install LinuxGuard agent
RUN apt-get update && apt-get install -y linuxguard-agent

# Create directories for agent state and logs
RUN mkdir -p /var/lib/linuxguard /var/log/linuxguard

# Your application setup continues here...

RedHat/CentOS-based Containers

FROM centos:8

# Install prerequisites
RUN yum install -y curl

# Add LinuxGuard repository
RUN curl -fsSL https://packages.linuxguard.io/dnf/add-linuxguard-yum-repo.sh | bash

# Install LinuxGuard agent
RUN yum install -y linuxguard-agent

# Create directories for agent state and logs
RUN mkdir -p /var/lib/linuxguard /var/log/linuxguard

# Your application setup continues here...

Alpine-based Containers

Note: Alpine and other minimal images have experimental support due to limited container capabilities. We are actively working on improving support for minimal container images.

FROM alpine:latest

# Install prerequisites
RUN apk add --no-cache curl

# Add LinuxGuard repository
RUN curl -fsSL https://packages.linuxguard.io/apk/add-linuxguard-apk-repo.sh | bash

# Install LinuxGuard agent
RUN apk add --no-cache linuxguard-agent

# Create directories for agent state and logs
RUN mkdir -p /var/lib/linuxguard /var/log/linuxguard

# Your application setup continues here...

Method 2: Install at Runtime

You can also install the agent when the container starts. This is useful for dynamic deployments or when you want to keep base images minimal.

Note: Minimal base images have experimental support due to limited container capabilities required to run services. We are actively working on improving support for these environments.

Using an Entrypoint Script

Create an entrypoint script that installs and configures the agent:

#!/bin/bash
set -e

# Add repository and install agent (Debian example)
if ! command -v linuxguard-agent &> /dev/null; then
    curl -fsSL https://packages.linuxguard.io/apt/add-linuxguard-repo.sh | bash
    apt-get update
    apt-get install -y linuxguard-agent
fi

# Enroll agent if not already enrolled
if [ ! -f /var/lib/linuxguard/enrolled ]; then
    linuxguard-agent enroll --api_key="${LINUXGUARD_API_KEY}" --tid="${LINUXGUARD_TENANT_ID}"
    touch /var/lib/linuxguard/enrolled
fi

# Start your application
exec "$@"

Container Configuration

Environment Variables

Use environment variables to pass credentials to the container:

LINUXGUARD_API_KEY=ak_1234567890abcdef
LINUXGUARD_TENANT_ID=tenant_abc123xyz

Persistent Volumes

Mount volumes to persist agent state and logs across container restarts:

# Docker Compose example
services:
  myapp:
    image: myapp:latest
    volumes:
      - linuxguard-data:/var/lib/linuxguard
      - linuxguard-logs:/var/log/linuxguard
    environment:
      - LINUXGUARD_API_KEY=${LINUXGUARD_API_KEY}
      - LINUXGUARD_TENANT_ID=${LINUXGUARD_TENANT_ID}

volumes:
  linuxguard-data:
  linuxguard-logs:

Or with Docker run:

docker run -d \
  -v linuxguard-data:/var/lib/linuxguard \
  -v linuxguard-logs:/var/log/linuxguard \
  -e LINUXGUARD_API_KEY=ak_1234567890abcdef \
  -e LINUXGUARD_TENANT_ID=tenant_abc123xyz \
  myapp:latest

Kubernetes Deployment

For Kubernetes deployments, use ConfigMaps and Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: linuxguard-credentials
type: Opaque
stringData:
  api-key: ak_1234567890abcdef
  tenant-id: tenant_abc123xyz
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: myapp
        image: myapp:latest
        env:
        - name: LINUXGUARD_API_KEY
          valueFrom:
            secretKeyRef:
              name: linuxguard-credentials
              key: api-key
        - name: LINUXGUARD_TENANT_ID
          valueFrom:
            secretKeyRef:
              name: linuxguard-credentials
              key: tenant-id
        volumeMounts:
        - name: linuxguard-data
          mountPath: /var/lib/linuxguard
        - name: linuxguard-logs
          mountPath: /var/log/linuxguard
      volumes:
      - name: linuxguard-data
        emptyDir: {}
      - name: linuxguard-logs
        emptyDir: {}

Enrollment in Containers

Automatic Enrollment

The agent can be enrolled automatically when the container starts using environment variables:

# In your entrypoint or startup script
linuxguard-agent enroll --api_key="${LINUXGUARD_API_KEY}" --tid="${LINUXGUARD_TENANT_ID}"

Manual Enrollment

You can also enroll manually by executing the command in a running container:

# Docker
docker exec -it <container-name> linuxguard-agent enroll --api_key=<API_KEY> --tid=<TENANT_ID>

# Kubernetes
kubectl exec -it <pod-name> -- linuxguard-agent enroll --api_key=<API_KEY> --tid=<TENANT_ID>

Enrollment Persistence

To avoid re-enrolling on every container restart, check if enrollment already exists:

#!/bin/bash
if [ ! -f /var/lib/linuxguard/enrolled ]; then
    linuxguard-agent enroll --api_key="${LINUXGUARD_API_KEY}" --tid="${LINUXGUARD_TENANT_ID}"
    if [ $? -eq 0 ]; then
        touch /var/lib/linuxguard/enrolled
    fi
fi

Container-Specific Considerations

Running as Non-Root

If your container runs as a non-root user, you may need to adjust permissions or use sudo:

# Allow non-root user to run agent commands
RUN chmod +s /usr/bin/linuxguard-agent

Or use sudo in your startup script:

sudo linuxguard-agent enroll --api_key="${LINUXGUARD_API_KEY}" --tid="${LINUXGUARD_TENANT_ID}"

Log Access

Access logs from outside the container:

# Docker
docker exec <container-name> tail -f /var/log/linuxguard/agent.log

# Kubernetes
kubectl exec <pod-name> -- tail -f /var/log/linuxguard/agent.log

Network Requirements

Ensure your container has outbound HTTPS access to:

• api.linuxguard.io (port 443)

• packages.linuxguard.io (port 443, for installation)

Resource Limits

The agent requires minimal resources:

• CPU: 0.1 cores recommended

• Memory: 50-100 MB

• Disk: 100-500 MB for logs and state

Verification

After installation and enrollment, verify the agent is working:

# Check agent status
docker exec <container-name> linuxguard-agent status

# Check logs
docker exec <container-name> tail -n 50 /var/log/linuxguard/agent.log

# Verify enrollment
docker exec <container-name> test -f /var/lib/linuxguard/enrolled && echo "Enrolled" || echo "Not enrolled"

Troubleshooting

Common container-specific issues:

1. Agent not persisting: Ensure volumes are mounted for /var/lib/linuxguard

2. Enrollment fails: Check network connectivity and environment variables

3. Permission errors: Verify user permissions or use sudo

4. Logs not accessible: Check volume mounts and file permissions

For more troubleshooting help, see the Troubleshooting Guide.

---

Related: Standard Installation | Configuration | Troubleshooting