Linux Installation

This guide covers installing the Tamandua EDR agent on Linux systems using native packages (DEB/RPM) or manual installation.

Prerequisites

System Requirements

Supported Distributions

Administrative Requirements

• Root or sudo access required for installation
• Network access to the Tamandua server
• Enrollment token from the Tamandua admin console

Firewall Configuration

Ensure outbound connections are allowed:

# For firewalld (RHEL/CentOS/Fedora)
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload

# For ufw (Ubuntu/Debian)
sudo ufw allow out 8443/tcp
sudo ufw allow out 443/tcp

Package Installation

Debian/Ubuntu (DEB)

Add Repository

# Import GPG key
curl -fsSL https://repo.tamandua.treantlab.org/gpg | sudo gpg --dearmor -o /usr/share/keyrings/tamandua-archive-keyring.gpg

# Add repository
echo "deb [signed-by=/usr/share/keyrings/tamandua-archive-keyring.gpg] https://repo.tamandua.treantlab.org/apt stable main" | \
    sudo tee /etc/apt/sources.list.d/tamandua.list

# Update package list
sudo apt update

Install Package

# Install agent
sudo apt install tamandua-agent

# Enroll agent
sudo tamandua-agent install

# Start service
sudo systemctl start tamandua-agent
sudo systemctl enable tamandua-agent

Direct DEB Installation

# Download package
wget https://tamandua.treantlab.org/downloads/agent/linux/amd64/tamandua-agent.deb

# Verify checksum
sha256sum tamandua-agent.deb
# Compare with published checksum

# Install package
sudo dpkg -i tamandua-agent.deb

# Install dependencies if needed
sudo apt-get install -f

# Enroll agent
sudo tamandua-agent install

RHEL/CentOS/Fedora (RPM)

Add Repository

# Add repository
sudo cat > /etc/yum.repos.d/tamandua.repo << 'EOF'
[tamandua]
name=Tamandua EDR Repository
baseurl=https://repo.tamandua.treantlab.org/rpm/stable/$basearch
enabled=1
gpgcheck=1
gpgkey=https://repo.tamandua.treantlab.org/gpg
EOF

# Import GPG key
sudo rpm --import https://repo.tamandua.treantlab.org/gpg

Install Package

# Install agent (RHEL 8+/Fedora)
sudo dnf install tamandua-agent

# Or for older systems (CentOS 7)
sudo yum install tamandua-agent

# Enroll agent
sudo tamandua-agent install

# Start service
sudo systemctl start tamandua-agent
sudo systemctl enable tamandua-agent

Direct RPM Installation

# Download package
curl -O https://tamandua.treantlab.org/downloads/agent/linux/amd64/tamandua-agent.rpm

# Verify checksum
sha256sum tamandua-agent.rpm

# Install package
sudo rpm -ivh tamandua-agent.rpm

# Or with dnf (handles dependencies)
sudo dnf install ./tamandua-agent.rpm

# Enroll agent
sudo tamandua-agent install

Amazon Linux 2023

# Install from RPM
sudo dnf install https://tamandua.treantlab.org/downloads/agent/linux/amd64/tamandua-agent.rpm

# Enroll agent
sudo tamandua-agent install

# Enable and start
sudo systemctl enable --now tamandua-agent

Manual Installation

For systems without package manager support or air-gapped environments.

Download Binary

# Create installation directory
sudo mkdir -p /opt/tamandua

# Download agent binary
sudo curl -L -o /opt/tamandua/tamandua-agent \
    "https://tamandua.treantlab.org/downloads/agent/linux/amd64/tamandua-agent"

# Make executable
sudo chmod +x /opt/tamandua/tamandua-agent

# Verify binary
/opt/tamandua/tamandua-agent --version

Create Data Directories

# Create data directory
sudo mkdir -p /var/lib/tamandua/{config,logs,models,rules,quarantine,journal}

# Set permissions
sudo chmod 700 /var/lib/tamandua
sudo chown -R root:root /var/lib/tamandua

Install and Enroll

# Run installation
sudo /opt/tamandua/tamandua-agent install \
    --server "wss://agents.tamandua.treantlab.org:8443/socket/agent"

Create Systemd Service

The installer typically creates this automatically, but for manual setup:

sudo cat > /etc/systemd/system/tamandua-agent.service << 'EOF'
[Unit]
Description=Tamandua EDR Agent
Documentation=https://docs.tamandua.io
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/opt/tamandua/tamandua-agent service
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

# Security hardening
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=read-only
PrivateTmp=yes
ReadWritePaths=/var/lib/tamandua

# Resource limits
MemoryMax=512M
CPUQuota=25%

[Install]
WantedBy=multi-user.target
EOF

# Reload systemd
sudo systemctl daemon-reload

# Enable and start
sudo systemctl enable tamandua-agent
sudo systemctl start tamandua-agent

eBPF Support

The agent uses eBPF for high-performance kernel telemetry on Linux 5.4+.

Check eBPF Support

# Check kernel version
uname -r
# Should be 5.4 or higher for full eBPF support

# Check BPF filesystem
mount | grep bpf
# Should show: bpf on /sys/fs/bpf type bpf

# Check BTF support (required for CO-RE)
ls /sys/kernel/btf/vmlinux
# File should exist for BTF support

Enable eBPF on Older Kernels

For kernels 4.18-5.3, limited eBPF functionality is available:

# Install kernel headers (required for older kernels)
# Ubuntu/Debian
sudo apt install linux-headers-$(uname -r)

# RHEL/CentOS
sudo dnf install kernel-headers kernel-devel

eBPF Permissions

The agent requires CAPBPF and CAPPERFMON capabilities:

# Verify capabilities (after installation)
getcap /opt/tamandua/tamandua-agent
# Should show: cap_bpf,cap_perfmon+ep

SELinux Configuration

For RHEL/CentOS/Fedora with SELinux enabled:

Check SELinux Status

getenforce
# Returns: Enforcing, Permissive, or Disabled

Install SELinux Policy Module

# The package includes SELinux policy
sudo semodule -i /opt/tamandua/selinux/tamandua.pp

# Verify policy is loaded
sudo semodule -l | grep tamandua

Manual SELinux Context

If needed, set file contexts manually:

# Set contexts for agent binary
sudo semanage fcontext -a -t bin_t "/opt/tamandua/tamandua-agent"
sudo restorecon -v /opt/tamandua/tamandua-agent

# Set contexts for data directory
sudo semanage fcontext -a -t var_lib_t "/var/lib/tamandua(/.*)?"
sudo restorecon -Rv /var/lib/tamandua

Troubleshoot SELinux Denials

# Check for denials
sudo ausearch -m avc -ts recent

# Generate policy module from denials
sudo audit2allow -a -M tamandua_local
sudo semodule -i tamandua_local.pp

AppArmor Configuration

For Ubuntu/Debian with AppArmor enabled:

Check AppArmor Status

sudo aa-status

AppArmor Profile

The package includes an AppArmor profile at /etc/apparmor.d/opt.tamandua.tamandua-agent:

# Reload profile
sudo apparmor_parser -r /etc/apparmor.d/opt.tamandua.tamandua-agent

# Verify profile is loaded
sudo aa-status | grep tamandua

Set to Complain Mode (Troubleshooting)

# Switch to complain mode
sudo aa-complain /opt/tamandua/tamandua-agent

# Check logs for denied operations
sudo dmesg | grep DENIED

# Once resolved, switch back to enforce
sudo aa-enforce /opt/tamandua/tamandua-agent

Verify Installation

Check Service Status

# Check service status
sudo systemctl status tamandua-agent

# Expected output:
# ● tamandua-agent.service - Tamandua EDR Agent
#      Loaded: loaded (/etc/systemd/system/tamandua-agent.service; enabled)
#      Active: active (running) since ...

Check Agent Logs

# View recent logs
sudo journalctl -u tamandua-agent -n 50

# Follow logs in real-time
sudo journalctl -u tamandua-agent -f

# Or check log file
sudo tail -f /var/lib/tamandua/logs/agent.log

Verify Connectivity

# Check if agent is connected
sudo journalctl -u tamandua-agent | grep -i "connected"

# Test network connectivity
curl -v https://tamandua.treantlab.org/health

Verify in Admin Console

1. Log in to the Tamandua admin console
2. Navigate to Agents > All Agents
3. Confirm the new agent appears with status Online

Directory Structure

/opt/tamandua/
    tamandua-agent              # Agent binary
    selinux/
        tamandua.pp             # SELinux policy module

/var/lib/tamandua/
    config/
        agent.toml              # Agent configuration
        cert.pem                # Agent certificate
        key.pem                 # Agent private key (protected)
        ca-bundle.pem           # CA certificate bundle
    logs/
        agent.log               # Agent logs (rotated)
    models/
        malware_smell.onnx      # ML model (if enabled)
    rules/
        yara/                   # YARA rules
        sigma/                  # Sigma rules
    quarantine/                 # Quarantined files
    journal/                    # File modification journal

/etc/systemd/system/
    tamandua-agent.service      # Systemd service unit

/etc/apparmor.d/
    opt.tamandua.tamandua-agent # AppArmor profile (Debian/Ubuntu)

Troubleshooting

Service Fails to Start

Cause: Missing dependencies or permission issues. Solution:

# Check detailed status
sudo systemctl status tamandua-agent -l

# Check journal for errors
sudo journalctl -u tamandua-agent --no-pager

# Verify binary permissions
ls -la /opt/tamandua/tamandua-agent
# Should be: -rwxr-xr-x 1 root root

Enrollment Fails

Cause: Network issues or invalid token. Solution:

# Test connectivity
curl -v https://tamandua.treantlab.org/api/v1/agent/health

# Check DNS resolution
dig agents.tamandua.treantlab.org

# Verify token (first few characters)
echo "Token starts with: ${TOKEN:0:8}..."

# Re-run enrollment with verbose output
sudo RUST_LOG=debug /opt/tamandua/tamandua-agent install

eBPF Programs Fail to Load

Cause: Kernel version too old or missing BTF. Solution:

# Check kernel version
uname -r

# For kernels < 5.4, install headers
sudo apt install linux-headers-$(uname -r)  # Debian/Ubuntu
sudo dnf install kernel-headers              # RHEL/Fedora

# Verify BTF
ls -la /sys/kernel/btf/vmlinux

# Agent falls back to non-eBPF collectors if eBPF fails
# Check logs for fallback messages
sudo journalctl -u tamandua-agent | grep -i "ebpf\|fallback"

SELinux Blocking Agent

Cause: Missing or incorrect SELinux policy. Solution:

# Check for denials
sudo ausearch -m avc -ts recent | grep tamandua

# Temporarily set permissive (testing only)
sudo setenforce 0

# Generate and apply policy
sudo audit2allow -a -M tamandua_fix
sudo semodule -i tamandua_fix.pp

# Re-enable enforcing
sudo setenforce 1

High CPU Usage

Cause: Aggressive profile or eBPF overhead on older kernels. Solution:

# Check current profile
grep performance_profile /var/lib/tamandua/config/agent.toml

# Edit to use balanced or lightweight profile
sudo sed -i 's/performance_profile = "aggressive"/performance_profile = "balanced"/' \
    /var/lib/tamandua/config/agent.toml

# Restart agent
sudo systemctl restart tamandua-agent

Container Not Detected

Cause: Container collector needs Docker socket access. Solution:

# Verify Docker socket permissions
ls -la /var/run/docker.sock

# Add tamandua to docker group (if running as non-root user)
sudo usermod -aG docker tamandua

# For containerd
ls -la /run/containerd/containerd.sock

Uninstall

Package Uninstall

# Debian/Ubuntu
sudo apt remove tamandua-agent
sudo apt purge tamandua-agent  # Also removes config

# RHEL/CentOS/Fedora
sudo dnf remove tamandua-agent

# Remove data directory (optional)
sudo rm -rf /var/lib/tamandua

Manual Uninstall

# Stop and disable service
sudo systemctl stop tamandua-agent
sudo systemctl disable tamandua-agent

# Run uninstall; token is prompted without echo
sudo /opt/tamandua/tamandua-agent uninstall

# Or manual cleanup
sudo rm -rf /opt/tamandua
sudo rm -rf /var/lib/tamandua
sudo rm -f /etc/systemd/system/tamandua-agent.service
sudo systemctl daemon-reload

Next Steps

• Configure the Agent - Customize agent settings
• Enrollment Guide - Manage agent enrollment
• Windows Installation - Install on Windows systems
• macOS Installation - Install on macOS systems