Agent Installation Guide

System Requirements

🐍 Python

Required: 3.9, 3.11, or 3.12

Note: Python 3.13 is NOT yet supported due to package compatibility

💻 Operating System

Supported: Linux (Ubuntu, CentOS/RHEL, openSUSE, SLES), Windows, macOS, FreeBSD, OpenBSD, NetBSD

Cross-platform compatibility

🌐 Network Access

Required: Outbound HTTPS access to SysManage Server

No inbound ports required

🛡️ Privileges

Optional: Administrative rights for system management

Can run as regular user with limitations

Platform-Specific Prerequisites

Ubuntu 22.04 - 24.10

# Update package manager
sudo apt update

# Install Python (3.11 or 3.12 ONLY - not 3.13)
sudo apt install python3.11 python3.11-venv python3.11-dev python3-pip

# Install build tools for cryptography packages and SQLite
sudo apt install build-essential libffi-dev libssl-dev pkg-config sqlite3

# Install Rust (required for cryptography)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

Ubuntu 25.04+ (Python 3.12 from Source)

Note: Ubuntu 25.04+ only ships with Python 3.13. You must build Python 3.12 from source:

# Install build dependencies
sudo apt install build-essential libssl-dev zlib1g-dev libbz2-dev \
    libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev \
    libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev \
    python3-openssl git pkg-config

# Download and build Python 3.12
cd /tmp
wget https://www.python.org/ftp/python/3.12.7/Python-3.12.7.tgz
tar -xf Python-3.12.7.tgz
cd Python-3.12.7

# Configure and build (takes 10-15 minutes)
./configure --enable-optimizations --with-ensurepip=install
make -j$(nproc)
sudo make altinstall

# Verify installation
python3.12 --version

# Install Rust (required for cryptography)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

CentOS/RHEL/Fedora

# Install Python 3.9+
sudo dnf install python3 python3-devel python3-pip

# Install build tools and SQLite
sudo dnf groupinstall "Development Tools"
sudo dnf install libffi-devel openssl-devel pkg-config sqlite

# Install Rust (required for cryptography)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

macOS

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python 3.9+
brew install python3

# Install SQLite3
brew install sqlite3

# Install Rust (required for cryptography)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Build tools are included with Xcode Command Line Tools
xcode-select --install

Windows

Python 3.9-3.12: Download from python.org
- ⚠️ AVOID Python 3.13 - Package compatibility issues
- ✅ Check "Add Python to PATH" during installation
- ✅ SQLite3 is included with Python on Windows
Rust: Download from rustup.rs
- Run rustup-init.exe and follow prompts
Git for Windows: Download from git-scm.com
- Includes build tools needed for Python packages
Windows Build Tools (if needed): Download Visual Studio Build Tools

FreeBSD

# Update package manager
sudo pkg update

# Install Python 3.9+
sudo pkg install python3 py3-pip

# Install SQLite3
sudo pkg install sqlite3

# Install build tools and Rust
sudo pkg install rust gcc cmake make pkg-config

# Set up environment
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

OpenBSD

# Update package manager
doas pkg_add -u

# Install Python 3.9+
doas pkg_add python-3 py3-pip

# Install SQLite3
doas pkg_add sqlite3

# Install build tools and Rust (REQUIRED for cryptography)
doas pkg_add rust gcc cmake gmake pkgconf

# Set up environment
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.profile
. ~/.profile

⚠️ Important for OpenBSD

Rust is absolutely required for building cryptography packages. The agent uses certificate-based authentication which requires cryptography support for security.

NetBSD

# Update package manager
sudo pkgin update

# Install Python 3.12
sudo pkgin install python312 py312-pip

# Install SQLite3
sudo pkgin install sqlite3

# Install GCC 14 and build tools (REQUIRED for C++17 support)
sudo pkgin install gcc14 cmake gmake pkgconf

# Install Rust (REQUIRED for cryptography)
sudo pkgin install rust

# Set up environment (GCC 14 for C++17 support)
echo 'export PATH="/usr/pkg/gcc14/bin:$PATH"' >> ~/.profile
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.profile
echo 'export CXXFLAGS="-std=c++17"' >> ~/.profile
. ~/.profile

⚠️ Important for NetBSD

GCC 14 is required: NetBSD's base system GCC 10.5 doesn't properly support C++17 features needed by grpcio and other packages. Installing GCC 14 ensures proper C++17 support.

Rust is required: The agent uses certificate-based authentication which requires cryptography support for security.

Note: On BSD systems, use . ~/.profile instead of source ~/.profile to reload your shell environment.

openSUSE Leap/Tumbleweed

# Update package manager
sudo zypper refresh

# Install Python 3.9+ (usually pre-installed)
sudo zypper install python3 python3-pip python3-devel

# Install build tools and development libraries
sudo zypper install gcc gcc-c++ make cmake pkg-config
sudo zypper install libopenssl-devel libffi-devel sqlite3-devel

# Install Rust (required for cryptography)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Alternative: Install Rust via zypper (openSUSE Tumbleweed)
# sudo zypper install rust cargo

📦 Package Manager Notes

openSUSE Leap: Uses stable packages, may need manual Rust installation
openSUSE Tumbleweed: Rolling release, Rust available via zypper
Python versions: Leap ships with Python 3.9+, Tumbleweed with latest stable

SUSE Linux Enterprise Server (SLES)

# Update package manager
sudo zypper refresh

# Install Python 3.9+ and development tools
sudo zypper install python3 python3-pip python3-devel
sudo zypper install gcc gcc-c++ make cmake pkg-config

# Install development libraries
sudo zypper install libopenssl-devel libffi-devel sqlite3-devel

# Install Rust (required for cryptography)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# For SLES 15 SP4+, you may also need:
sudo zypper install glibc-devel kernel-devel

🏢 Enterprise Considerations

SLES 12: May require Software Collections (SCL) for newer Python
SLES 15: Python 3.6+ included, but 3.9+ recommended
Firewall: SuSEfirewall2 or firewalld may block agent ports
SELinux: May require policy adjustments if enabled
Subscription: Some packages require active SLES subscription

Installation Methods

📦 APT Repository (Ubuntu/Debian - Recommended)

Supported Platforms:

Ubuntu 22.04 LTS and newer
Debian 11 and newer

The package includes all Python dependencies in a self-contained virtualenv, so it works on any Ubuntu/Debian version with Python 3.10 or higher.

Quick Installation

# Add the SysManage APT repository
echo "deb [trusted=yes] https://bceverly.github.io/sysmanage-docs/repo/agent/deb stable main" | sudo tee /etc/apt/sources.list.d/sysmanage.list

# Update package lists
sudo apt update

# Install sysmanage-agent
sudo apt install sysmanage-agent

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Restart the service
sudo systemctl restart sysmanage-agent

# Check service status
sudo systemctl status sysmanage-agent

✨ Benefits of APT Installation

Automatic Updates: Get new versions via standard apt upgrade
Dependency Management: All Python dependencies included in package
Systemd Integration: Service automatically configured and enabled
User & Permissions: System user and sudoers automatically configured
Directory Structure: Config, logs, and data directories created automatically

📂 What Gets Installed

Component	Location
Application	`/opt/sysmanage-agent/`
Configuration Directory	`/etc/sysmanage-agent/`
Main Config File	`/etc/sysmanage-agent.yaml`
Database	`/var/lib/sysmanage-agent/agent.db`
Logs	`/var/log/sysmanage-agent/`
Systemd Service	`/lib/systemd/system/sysmanage-agent.service`
Sudoers File	`/etc/sudoers.d/sysmanage-agent`

🔄 Version Management

# List available versions
apt-cache policy sysmanage-agent

# Install specific version
sudo apt install sysmanage-agent=0.9.0-1

# Upgrade to latest version
sudo apt update
sudo apt upgrade sysmanage-agent

# Hold current version (prevent automatic upgrades)
sudo apt-mark hold sysmanage-agent

# Unhold to allow upgrades
sudo apt-mark unhold sysmanage-agent

🗑️ Uninstallation

# Remove package but keep configuration
sudo apt remove sysmanage-agent

# Remove package and all configuration files
sudo apt purge sysmanage-agent

# Remove repository configuration
sudo rm /etc/apt/sources.list.d/sysmanage.list
sudo apt update

🔒 Security Note

The repository currently uses [trusted=yes] because packages are not GPG-signed. For production environments, GPG signing will be added in a future release. The packages are served over HTTPS from GitHub Pages, providing transport-level security.

For Ubuntu users, we also provide official packages through Launchpad PPA with automatic builds for multiple Ubuntu versions:

🔷 Launchpad PPA (Alternative for Ubuntu)

Supported Ubuntu Versions:

Ubuntu 22.04 LTS (Jammy Jellyfish)
Ubuntu 24.04 LTS (Noble Numbat)
Ubuntu 24.10 (Oracular Oriole)
Ubuntu 25.04 (Plucky Puffin)
Ubuntu 25.10 (Questing Quetzal)

Quick Installation via PPA

# Add the PPA
sudo add-apt-repository ppa:bceverly/sysmanage-agent
sudo apt update

# Install sysmanage-agent
sudo apt install sysmanage-agent

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Restart the service
sudo systemctl restart sysmanage-agent

# Check service status
sudo systemctl status sysmanage-agent

✨ Benefits of Launchpad PPA

Official Ubuntu PPA: Native Ubuntu package building and distribution
Multi-Version Support: Automatic builds for multiple Ubuntu releases
Trusted Source: Packages built and hosted by Canonical's Launchpad

Note: The PPA builds are optimized for each specific Ubuntu release and may have slightly different dependencies than the generic APT repository.

📦 Snap Package - Strict Confinement (Read-Only Monitoring)

Note: Due to Snap Store policies, management snaps (those requiring system modification capabilities) are not approved for classic confinement. The strict confinement version provides read-only monitoring only.

⚠️ Important Limitation

This snap provides read-only monitoring capabilities only. It cannot:

Install or update system packages
Manage firewall rules
Execute administrative scripts
Install system certificates

For full system management capabilities, use the APT/DEB or source installation methods above.

Supported Platforms:

Ubuntu 22.04+ (core22 base)

Quick Installation

# Install from Snap Store
sudo snap install sysmanage-agent-strict --edge

# Configure the agent
sudo snap set sysmanage-agent-strict server-url="wss://your-server:8443"
sudo snap set sysmanage-agent-strict server-token="YOUR_TOKEN"

# View configuration
sudo snap get sysmanage-agent-strict

# Check service status
sudo snap services sysmanage-agent-strict

# View logs
sudo snap logs sysmanage-agent-strict -f

✨ Benefits of Snap Installation

Sandboxed and secure
Automatic updates
Simple installation
Read-only monitoring without system modifications

🗑️ Uninstallation

sudo snap remove sysmanage-agent-strict

View on Snap Store

For more information about Snap confinement, see: Snap Confinement Documentation

📦 Flatpak (Universal Linux Package)

Works on any Linux distribution that supports Flatpak:

Ubuntu / Debian
Fedora / RHEL / CentOS
openSUSE / SLES
Arch Linux
And many more...

Note: The Flatpak runs in a sandboxed environment with limited system access. For full system management capabilities, use native packages.

Method 1: Install from SysManage Repository (Recommended)

# Add the SysManage Flatpak repository
flatpak remote-add --if-not-exists sysmanage https://sysmanage.org/sysmanage.flatpakrepo

# Install the agent
flatpak install sysmanage org.sysmanage.Agent

# Run the service installation script
flatpak run --command=sysmanage-service-install org.sysmanage.Agent

# Configure the agent (edit the config in your home directory)
nano ~/.var/app/org.sysmanage.Agent/config/sysmanage/sysmanage-agent.yaml

# Start the agent
flatpak run org.sysmanage.Agent

Method 2: Install from Bundle File

# Download the latest Flatpak bundle
wget https://github.com/bceverly/sysmanage-agent/releases/latest/download/sysmanage-agent-VERSION.flatpak

# Install the bundle
flatpak install --user sysmanage-agent-VERSION.flatpak

# Run the service installation script
flatpak run --command=sysmanage-service-install org.sysmanage.Agent

# Start the agent
flatpak run org.sysmanage.Agent

✨ Benefits of Flatpak Installation

Universal: Works on any Linux distribution
Self-Contained: All dependencies bundled, including Python runtime
Automatic Updates: Update with standard flatpak update command
Sandboxed: Runs in isolated environment for additional security
No Conflicts: Isolated from system packages

⚠️ Limitations

Limited system access due to Flatpak sandboxing
Some system directories are read-only
Reduced privileged operation capabilities
For full system management, use native APT/RPM packages instead

🔄 Version Management

# Update to latest version
flatpak update org.sysmanage.Agent

# List installed version
flatpak list --app | grep sysmanage

# Uninstall
flatpak run --command=sysmanage-service-uninstall org.sysmanage.Agent
flatpak uninstall org.sysmanage.Agent

📂 Configuration & Data Locations

Component	Location
Configuration File	`~/.var/app/org.sysmanage.Agent/config/sysmanage/sysmanage-agent.yaml`
Database	`~/.var/app/org.sysmanage.Agent/data/sysmanage/agent.db`
Logs	`~/.var/app/org.sysmanage.Agent/data/sysmanage/logs/`

Note: Ubuntu 25.04+ requires building Python 3.12 from source first. See the Prerequisites tab for Ubuntu 25.04+, then use manual installation from source below.

Manual Installation from Source

# Clone the repository
git clone https://github.com/bceverly/sysmanage-agent.git
cd sysmanage-agent

# Create virtual environment with Python 3.12
python3.12 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

# Run the agent
python main.py

📦 YUM/DNF Repository (RHEL/CentOS/Fedora - Recommended)

Supported Platforms:

RHEL 9 / CentOS Stream 9 / Rocky 9 / AlmaLinux 9 - Python 3.9+ (2022+)
RHEL 8 / CentOS 8 / Rocky 8 / AlmaLinux 8 - Python 3.11 via AppStream (2019+)
Fedora 38+ - Python 3.11+ (2023+)

The package includes all Python dependencies in a self-contained virtualenv, so it works on any Red Hat-based distribution with Python 3.10 or higher.

Quick Installation - EL9 (RHEL 9, Rocky 9, AlmaLinux 9, CentOS Stream 9)

sudo tee /etc/yum.repos.d/sysmanage.repo << EOF
[sysmanage]
name=SysManage Agent Repository
baseurl=https://bceverly.github.io/sysmanage-docs/repo/agent/rpm/el9/x86_64
enabled=1
gpgcheck=0
metadata_expire=1h
EOF

sudo dnf install sysmanage-agent

Quick Installation - EL8 (RHEL 8, Rocky 8, AlmaLinux 8)

# Install Python 3.11 first
sudo dnf module install python311

sudo tee /etc/yum.repos.d/sysmanage.repo << EOF
[sysmanage]
name=SysManage Agent Repository
baseurl=https://bceverly.github.io/sysmanage-docs/repo/agent/rpm/el8/x86_64
enabled=1
gpgcheck=0
metadata_expire=1h
EOF

sudo dnf install sysmanage-agent

Quick Installation - Fedora 38+

sudo tee /etc/yum.repos.d/sysmanage.repo << EOF
[sysmanage]
name=SysManage Agent Repository
baseurl=https://bceverly.github.io/sysmanage-docs/repo/agent/rpm/fedora/39/x86_64
enabled=1
gpgcheck=0
metadata_expire=1h
EOF

sudo dnf install sysmanage-agent

✨ Benefits of RPM Installation

Automatic Updates: Get new versions via standard dnf upgrade / yum upgrade
Dependency Management: All Python dependencies included in package
Systemd Integration: Service automatically configured and enabled
User & Permissions: System user and sudoers automatically configured with permissions for DNF/YUM, firewalld, SELinux
Directory Structure: Config, logs, and data directories created automatically

📂 What Gets Installed

Component	Location
Application	`/opt/sysmanage-agent/`
Configuration Directory	`/etc/sysmanage-agent/`
Main Config File	`/etc/sysmanage-agent.yaml`
Database	`/var/lib/sysmanage-agent/agent.db`
Logs	`/var/log/sysmanage-agent/`
Systemd Service	`/usr/lib/systemd/system/sysmanage-agent.service`
Sudoers File	`/etc/sudoers.d/sysmanage-agent`

🔄 Version Management

# List available versions
dnf list --showduplicates sysmanage-agent

# Install specific version
sudo dnf install sysmanage-agent-0.9.0-1

# Upgrade to latest version
sudo dnf upgrade sysmanage-agent

# Lock to current version (prevent upgrades)
sudo dnf versionlock add sysmanage-agent

# Unlock to allow upgrades
sudo dnf versionlock delete sysmanage-agent

🗑️ Uninstallation

# Remove package (keeps configuration)
sudo dnf remove sysmanage-agent

# Remove repository configuration
sudo rm /etc/yum.repos.d/sysmanage.repo
sudo dnf clean all

🔒 Security Note

The repository currently uses gpgcheck=0 because packages are not GPG-signed. For production environments, GPG signing will be added in a future release. Packages are served via HTTPS from GitHub Pages, providing transport-level security.

For Fedora, RHEL, CentOS, and Amazon Linux users, we provide official packages through Fedora Copr with automatic builds for multiple distributions:

🔷 Fedora Copr (Alternative)

Supported Distributions:

Fedora 41 (Python 3.13)
Fedora 42 (Python 3.13)
Fedora 43 (Python 3.14)
EPEL 9 (RHEL 9, Rocky Linux 9, AlmaLinux 9, CentOS Stream 9 - Python 3.9)
EPEL 10 (RHEL 10, CentOS Stream 10 - Python 3.12)
Amazon Linux 2023 (Python 3.9)

Note: EPEL 8 is not supported as it uses Python 3.6, which is too old for our dependencies.

Quick Installation via Copr

# Enable the Copr repository
sudo dnf copr enable bceverly/sysmanage-agent

# Install sysmanage-agent
sudo dnf install sysmanage-agent

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Enable and start the service
sudo systemctl enable sysmanage-agent
sudo systemctl start sysmanage-agent

# Check service status
sudo systemctl status sysmanage-agent

✨ Benefits of Copr

Official Copr Repository: Native Fedora/RHEL package building infrastructure
Automatic Builds: Builds triggered automatically from tagged releases
Multi-Distribution: Single command works across Fedora, RHEL, CentOS, and Amazon Linux
Python Version Support: Optimized wheels for Python 3.9, 3.12, 3.13, and 3.14
Offline Installation: All Python dependencies bundled in package
Easy Updates: Standard dnf upgrade workflow

📋 Distribution-Specific Instructions

Fedora 41, 42, 43:

sudo dnf copr enable bceverly/sysmanage-agent
sudo dnf install sysmanage-agent

RHEL 9 / Rocky 9 / AlmaLinux 9 / CentOS Stream 9:

# Enable EPEL first
sudo dnf install epel-release

# Enable Copr repository
sudo dnf copr enable bceverly/sysmanage-agent
sudo dnf install sysmanage-agent

RHEL 10 / CentOS Stream 10:

# Enable EPEL first
sudo dnf install epel-release

# Enable Copr repository
sudo dnf copr enable bceverly/sysmanage-agent
sudo dnf install sysmanage-agent

Amazon Linux 2023:

sudo dnf copr enable bceverly/sysmanage-agent
sudo dnf install sysmanage-agent

🗑️ Uninstallation

# Remove package
sudo dnf remove sysmanage-agent

# Disable Copr repository
sudo dnf copr disable bceverly/sysmanage-agent

🔗 View Build Status

You can view the current build status and browse all available versions at:

https://copr.fedorainfracloud.org/coprs/bceverly/sysmanage-agent/

📦 Zypper Repository (openSUSE - Recommended)

Supported Platforms:

openSUSE Leap 15.x - Python 3.11 (2021+)
openSUSE Tumbleweed - Python 3.11+ (Rolling)

The package includes all Python dependencies in a self-contained virtualenv.

Quick Installation - openSUSE Leap 15.x

# Add the SysManage repository
sudo zypper addrepo https://bceverly.github.io/sysmanage-docs/repo/agent/rpm/opensuse-leap/15/x86_64 sysmanage
sudo zypper refresh

# Install sysmanage-agent
sudo zypper install sysmanage-agent

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Restart the service
sudo systemctl restart sysmanage-agent

# Check service status
sudo systemctl status sysmanage-agent

Quick Installation - openSUSE Tumbleweed

# Add the SysManage repository
sudo zypper addrepo https://bceverly.github.io/sysmanage-docs/repo/agent/rpm/opensuse-tumbleweed/x86_64 sysmanage
sudo zypper refresh

# Install sysmanage-agent
sudo zypper install sysmanage-agent

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Restart the service
sudo systemctl restart sysmanage-agent

# Check service status
sudo systemctl status sysmanage-agent

✨ Benefits of Zypper Installation

Automatic Updates: Get new versions via standard zypper update
Dependency Management: All Python dependencies included in package
Systemd Integration: Service automatically configured and enabled
Isolated Environment: Doesn't conflict with system Python packages

🔄 Version Management

# List available versions
zypper search -s sysmanage-agent

# Upgrade to latest version
sudo zypper update sysmanage-agent

# Lock to current version (prevent upgrades)
sudo zypper addlock sysmanage-agent

# Unlock to allow upgrades
sudo zypper removelock sysmanage-agent

🗑️ Uninstallation

# Remove package (keeps configuration)
sudo zypper remove sysmanage-agent

# Remove repository configuration
sudo zypper removerepo sysmanage
sudo zypper refresh

For openSUSE and SLES users, we provide official packages through the openSUSE Build Service (OBS) with automatic builds for multiple distributions:

🔷 openSUSE Build Service (Alternative)

Supported Distributions:

openSUSE Tumbleweed (rolling release)
openSUSE Leap 15.6
openSUSE Leap 15.5
SUSE Linux Enterprise 15 SP6
SUSE Linux Enterprise 15 SP5

Quick Installation via OBS - openSUSE Tumbleweed

# Add the OBS repository
sudo zypper addrepo https://download.opensuse.org/repositories/home:/bryaneverly/openSUSE_Tumbleweed/ sysmanage-agent-obs
sudo zypper refresh

# Install sysmanage-agent
sudo zypper install sysmanage-agent

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Restart the service
sudo systemctl restart sysmanage-agent

# Check service status
sudo systemctl status sysmanage-agent

Quick Installation via OBS - openSUSE Leap

# Add the OBS repository (replace 15.6 with your Leap version)
sudo zypper addrepo https://download.opensuse.org/repositories/home:/bryaneverly/openSUSE_Leap_15.6/ sysmanage-agent-obs
sudo zypper refresh

# Install sysmanage-agent
sudo zypper install sysmanage-agent

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Restart the service
sudo systemctl restart sysmanage-agent

# Check service status
sudo systemctl status sysmanage-agent

✨ Benefits of OBS

Official OBS Repository: Native openSUSE/SLES package building
Multi-Distribution Support: Automatic builds for Tumbleweed, Leap, and SLES
YaST Integration: Seamlessly integrates with openSUSE tools

Note: OBS builds are optimized for each specific distribution version. Packages are built from source on the openSUSE Build Service infrastructure.

View build status at: https://build.opensuse.org/package/show/home:bryaneverly/sysmanage-agent

📦 Zypper Repository (SLES - Recommended)

Supported Platforms:

SUSE Linux Enterprise Server 15 - Python 3.11 (2018+)

The package includes all Python dependencies in a self-contained virtualenv.

Quick Installation - SLES 15

# Add the SysManage repository
sudo zypper addrepo https://bceverly.github.io/sysmanage-docs/repo/agent/rpm/sles/15/x86_64 sysmanage
sudo zypper refresh

# Install sysmanage-agent
sudo zypper install sysmanage-agent

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Restart the service
sudo systemctl restart sysmanage-agent

# Check service status
sudo systemctl status sysmanage-agent

✨ Benefits of Zypper Installation

Automatic Updates: Get new versions via standard zypper update
Dependency Management: All Python dependencies included in package
Systemd Integration: Service automatically configured and enabled
Enterprise Support: Production-ready for SUSE enterprise environments

🔄 Version Management

# List available versions
zypper search -s sysmanage-agent

# Upgrade to latest version
sudo zypper update sysmanage-agent

# Lock to current version (prevent upgrades)
sudo zypper addlock sysmanage-agent

# Unlock to allow upgrades
sudo zypper removelock sysmanage-agent

🗑️ Uninstallation

# Remove package (keeps configuration)
sudo zypper remove sysmanage-agent

# Remove repository configuration
sudo zypper removerepo sysmanage
sudo zypper refresh

🏢 Enterprise Considerations

Subscription: SLES requires an active subscription for system updates
Firewall: Configure SuSEfirewall2 or firewalld for outbound HTTPS
AppArmor: May require profile adjustments if using AppArmor

For openSUSE and SLES users, we provide official packages through the openSUSE Build Service (OBS) with automatic builds for multiple distributions:

🔷 openSUSE Build Service (Alternative)

Supported Distributions:

SUSE Linux Enterprise 15 SP6
SUSE Linux Enterprise 15 SP5
openSUSE Tumbleweed (rolling release)
openSUSE Leap 15.6
openSUSE Leap 15.5

Quick Installation via OBS - SLES 15

# Add the OBS repository (for SLES 15 SP6)
sudo zypper addrepo https://download.opensuse.org/repositories/home:/bryaneverly/SLE_15_SP6/ sysmanage-agent-obs
sudo zypper refresh

# Install sysmanage-agent
sudo zypper install sysmanage-agent

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Restart the service
sudo systemctl restart sysmanage-agent

# Check service status
sudo systemctl status sysmanage-agent

✨ Benefits of OBS

Official OBS Repository: Native openSUSE/SLES package building
Multi-Distribution Support: Automatic builds for Tumbleweed, Leap, and SLES
YaST Integration: Seamlessly integrates with openSUSE tools

Note: OBS builds are optimized for each specific distribution version. Packages are built from source on the openSUSE Build Service infrastructure.

View build status at: https://build.opensuse.org/package/show/home:bryaneverly/sysmanage-agent

📦 Package Installer (macOS - Recommended)

Supported Platforms:

macOS 11.0 (Big Sur) and newer
Apple Silicon (ARM64) native
Intel (x86_64) compatible

The package uses system Python (3.9+) and automatically detects your architecture to install native binaries.

Quick Installation

# Download the latest package
VERSION=$(curl -s https://bceverly.github.io/sysmanage-docs/repo/mac/latest.txt)
curl -O https://bceverly.github.io/sysmanage-docs/repo/mac/packages/$VERSION/sysmanage-agent-$VERSION-macos.pkg

# Install the package
sudo installer -pkg sysmanage-agent-$VERSION-macos.pkg -target /

# Configure the agent
sudo nano /etc/sysmanage-agent.yaml

# Start the service
sudo launchctl start com.sysmanage.agent

# Check service status
sudo launchctl print system/com.sysmanage.agent

✨ Benefits of Package Installation

Native Architecture: ARM64 native binaries on Apple Silicon
Dependency Management: All Python dependencies included in package
LaunchDaemon Integration: Service automatically configured and starts on boot
Directory Structure: Config, logs, and data directories created automatically
Uses System Python: No need to install Python separately

📂 What Gets Installed

Component	Location
Application	`/opt/sysmanage-agent/`
Main Config File	`/etc/sysmanage-agent.yaml`
Example Config	`/etc/sysmanage-agent.yaml.example`
Database	`/var/lib/sysmanage-agent/agent.db`
Logs	`/var/log/sysmanage-agent.log /var/log/sysmanage-agent-error.log`
LaunchDaemon	`/Library/LaunchDaemons/com.sysmanage.agent.plist`

🔄 Service Management

# Start service
sudo launchctl start com.sysmanage.agent

# Stop service
sudo launchctl stop com.sysmanage.agent

# Check service status
sudo launchctl print system/com.sysmanage.agent

# View logs
tail -f /var/log/sysmanage-agent.log
tail -f /var/log/sysmanage-agent-error.log

🔒 Verify Package Integrity

# Download package and checksum
VERSION=$(curl -s https://bceverly.github.io/sysmanage-docs/repo/mac/latest.txt)
curl -O https://bceverly.github.io/sysmanage-docs/repo/mac/packages/$VERSION/sysmanage-agent-$VERSION-macos.pkg
curl -O https://bceverly.github.io/sysmanage-docs/repo/mac/packages/$VERSION/sysmanage-agent-$VERSION-macos.pkg.sha256

# Verify checksum
shasum -a 256 -c sysmanage-agent-$VERSION-macos.pkg.sha256

🗑️ Uninstallation

# Stop and unload service
sudo launchctl unload /Library/LaunchDaemons/com.sysmanage.agent.plist

# Remove application files
sudo rm -rf /opt/sysmanage-agent
sudo rm /Library/LaunchDaemons/com.sysmanage.agent.plist
sudo rm /etc/sysmanage-agent.yaml
sudo rm /etc/sysmanage-agent.yaml.example

# Remove data and logs (optional)
sudo rm -rf /var/lib/sysmanage-agent
sudo rm -rf /var/log/sysmanage-agent*.log

💡 Architecture Detection

The installer automatically detects whether you're running on Apple Silicon or Intel and installs the appropriate native binaries. On Apple Silicon Macs, all Python packages are compiled for ARM64, providing optimal performance.

📦 MSI Installer (Windows - Recommended)

Supported Platforms:

Windows 10 (1809) or later
Windows 11
Windows Server 2019 or later
Architectures: x64 and ARM64

The MSI installer includes all dependencies (Python 3.12, VC++ Redistributable) and automatically installs the agent as a Windows service using NSSM.

Quick Installation

# Download the latest package (x64)
$VERSION = (Invoke-WebRequest -Uri "https://bceverly.github.io/sysmanage-docs/repo/windows/latest.txt").Content.Trim()
$ARCH = "x64"  # or "arm64" for ARM64 Windows
Invoke-WebRequest -Uri "https://bceverly.github.io/sysmanage-docs/repo/windows/packages/$VERSION/sysmanage-agent-$VERSION-windows-$ARCH.msi" -OutFile "sysmanage-agent-$VERSION-windows-$ARCH.msi"

# Install the package (requires Administrator)
Start-Process msiexec.exe -ArgumentList "/i sysmanage-agent-$VERSION-windows-$ARCH.msi /qn" -Wait -Verb RunAs

# Configure the agent
notepad C:\ProgramData\SysManage\sysmanage-agent.yaml

# Start the service
Start-Service SysManageAgent

✨ Benefits of MSI Installer

Fully Automated Installation: Python, VC++ Redistributable, and all dependencies installed automatically
Windows Service Integration: Service automatically configured using NSSM, starts on boot
Dependency Management: All Python dependencies included in isolated virtualenv
Seamless Upgrade: Installers upgrade automatically without manual uninstallation
Architecture Detection: Separate packages for x64 and ARM64 Windows
Directory Structure: Config, logs, and data directories created automatically

📂 What Gets Installed

Component	Location
Application	`C:\Program Files\SysManage Agent`
Configuration File	`C:\ProgramData\SysManage\sysmanage-agent.yaml`
Example Configuration	`C:\ProgramData\SysManage\sysmanage-agent.yaml.example`
Database	`C:\ProgramData\SysManage\db\agent.db`
Logs	`C:\ProgramData\SysManage\logs\`
Windows Service	Configured with NSSM (Non-Sucking Service Manager)

🔄 Service Management

# Check service status
Get-Service SysManageAgent

# Start/Stop service
Start-Service SysManageAgent
Stop-Service SysManageAgent
Restart-Service SysManageAgent

# View logs
Get-Content C:\ProgramData\SysManage\logs\agent.log -Tail 50
Get-Content C:\ProgramData\SysManage\logs\service-stdout.log -Tail 50
Get-Content C:\ProgramData\SysManage\logs\service-stderr.log -Tail 50

🔒 Verify Package Integrity

# Download package and checksum
$VERSION = "0.9.7.2"  # Replace with desired version
$ARCH = "x64"  # or "arm64"
Invoke-WebRequest -Uri "https://bceverly.github.io/sysmanage-docs/repo/windows/packages/$VERSION/sysmanage-agent-$VERSION-windows-$ARCH.msi" -OutFile "sysmanage-agent-$VERSION-windows-$ARCH.msi"
Invoke-WebRequest -Uri "https://bceverly.github.io/sysmanage-docs/repo/windows/packages/$VERSION/sysmanage-agent-$VERSION-windows-$ARCH.msi.sha256" -OutFile "sysmanage-agent-$VERSION-windows-$ARCH.msi.sha256"

# Verify checksum
$expectedHash = (Get-Content "sysmanage-agent-$VERSION-windows-$ARCH.msi.sha256").Split()[0]
$actualHash = (Get-FileHash "sysmanage-agent-$VERSION-windows-$ARCH.msi" -Algorithm SHA256).Hash.ToLower()
if ($expectedHash -eq $actualHash) { Write-Host "Checksum verified!" } else { Write-Host "Checksum mismatch!" }

🗑️ Uninstallation

Using Control Panel

1. Open **Settings** > **Apps** > **Apps & features**
2. Search for "SysManage Agent"
3. Click **Uninstall**

Using PowerShell

# Get the product code
$productCode = (Get-WmiObject -Class Win32_Product | Where-Object { $_.Name -eq "SysManage Agent" }).IdentifyingNumber

# Uninstall
Start-Process msiexec.exe -ArgumentList "/x $productCode /qn" -Wait -Verb RunAs

💡 Architecture Note

Make sure to download the correct installer for your architecture:
- **x64**: For Intel/AMD 64-bit systems
- **ARM64**: For ARM64 Windows devices (Surface Pro X, etc.)

Installation from Source

For FreeBSD, OpenBSD, NetBSD, and other platforms, install manually from source:

# Clone the repository
git clone https://github.com/bceverly/sysmanage-agent.git
cd sysmanage-agent

# Create virtual environment
python3 -m venv .venv  # Linux/macOS/BSD
# python -m venv .venv   # Windows

# Activate virtual environment
source .venv/bin/activate  # Linux/macOS (On OpenBSD: . .venv/bin/activate)
# OR
.venv\Scripts\activate     # Windows

# Upgrade pip to latest version
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

# Run the agent
python main.py

Alternative: Direct Installation

# Install directly from GitHub
pip install git+https://github.com/bceverly/sysmanage-agent.git

OpenBSD-Specific Installation Notes

OpenBSD users require special attention to Rust installation:

# Install all required packages including Rust
doas pkg_add python-3.9 py3-pip rust gcc cmake gmake pkgconf

# Set up Rust environment
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.profile
. ~/.profile

# Install Python dependencies
pip install -r requirements.txt

# Or run the agent using the run script which detects Rust availability
./run.sh

🔐 Security Note

The agent requires cryptography support for secure certificate-based authentication. Rust is mandatory for building these security packages. The run script automatically detects if Rust is available and uses appropriate installation methods.

Configuration

Auto-Discovery (Recommended)

SysManage Agent includes automatic server discovery that eliminates manual configuration:

🔍 How Auto-Discovery Works

No Configuration Required: If no configuration file exists, the agent automatically attempts to discover servers
Network Scanning: Sends UDP broadcast discovery requests and listens for server announcements
Server Evaluation: Uses scoring system (SSL preference, local network preference)
Automatic Configuration: Writes complete configuration file and starts normal operation

🌐 Required Network Ports

Agent Ports (Outbound):

UDP 31337 - Send discovery requests to servers
UDP 31338 - Listen for server announcements
TCP 6443 (or server port) - HTTPS connections to discovered server

Manual Configuration (Alternative)

💡 Configuration Generator Available

Use the interactive Configuration Builder Tool to generate customized agent configuration files for your environment.

Or create configuration file manually at:

Linux/macOS/BSD: /etc/sysmanage-agent.yaml
Windows: C:\ProgramData\SysManage\sysmanage-agent.yaml

# SysManage Server connection details
server:
  hostname: "sysmanage.example.com"  # SysManage Server hostname
  port: 6443                         # Server WebSocket port
  protocol: "wss"                    # Use "ws" for non-SSL, "wss" for SSL

# Agent identification
agent:
  name: "my-server-01"               # Optional: Custom agent name
  tags:                              # Optional: Custom tags for grouping
    - "production"
    - "web-server"
    - "datacenter-1"

# Security settings
security:
  verify_ssl: true                   # Set to false for self-signed certificates
  api_key: "your-api-key-here"       # Optional: API key for authentication

# Monitoring settings
monitoring:
  heartbeat_interval: 30             # Seconds between heartbeat messages
  metrics_interval: 60               # Seconds between metric collection
  command_timeout: 300               # Maximum command execution time (seconds)

# Logging
logging:
  level: "INFO"                      # DEBUG, INFO, WARNING, ERROR, CRITICAL
  file: "/var/log/sysmanage-agent.log"  # Log file path

# Internationalization
i18n:
  language: "en"                     # Agent language (en, es, fr, de, it, pt, nl, ja, zh_CN, zh_TW, ko, ru, ar, hi)

Required Directories and Permissions

Certificate Storage

Linux/macOS/BSD: /etc/sysmanage-agent/

Windows: C:\ProgramData\SysManage\

# Create with proper permissions (Linux/macOS)
sudo mkdir -p /etc/sysmanage-agent
sudo chown sysmanage-agent:sysmanage-agent /etc/sysmanage-agent
sudo chmod 0700 /etc/sysmanage-agent

Configuration File

# Create configuration file with proper permissions
sudo touch /etc/sysmanage-agent.yaml
sudo chown sysmanage-agent:sysmanage-agent /etc/sysmanage-agent.yaml
sudo chmod 0600 /etc/sysmanage-agent.yaml

Log Directory

# Create log directory
sudo mkdir -p /var/log/sysmanage-agent
sudo chown sysmanage-agent:sysmanage-agent /var/log/sysmanage-agent
sudo chmod 0755 /var/log/sysmanage-agent

Service User Account

# Create dedicated service user (Linux)
sudo useradd -r -s /bin/false -d /opt/sysmanage-agent -c "SysManage Agent" sysmanage-agent

📝 Development Note

During development and testing, the application automatically detects test environments and uses temporary directories to avoid permission issues.

Running the Agent

Development Mode

# Run with debug output
python main.py --debug

# Run with custom config file
python main.py --config /path/to/config.yaml

# Run with specific server
python main.py --server sysmanage.example.com --port 6443

Command Line Options

python main.py [OPTIONS]

Options:
  --config PATH              Configuration file path
  --server TEXT              SysManage server hostname
  --port INTEGER             Server WebSocket port (default: 6443)
  --protocol [ws|wss]        Connection protocol (default: wss)
  --debug                    Enable debug logging
  --no-verify-ssl           Disable SSL certificate verification
  --daemon                   Run as daemon (Unix only)
  --help                     Show help message

Service Installation

Create systemd service file

Create /etc/systemd/system/sysmanage-agent.service:

[Unit]
Description=SysManage Agent
After=network.target
Wants=network.target

[Service]
Type=simple
ExecStart=/opt/sysmanage-agent/.venv/bin/python /opt/sysmanage-agent/main.py
Restart=always
RestartSec=10
User=sysmanage-agent
Group=sysmanage-agent
WorkingDirectory=/opt/sysmanage-agent

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/log
ProtectHome=true

[Install]
WantedBy=multi-user.target

Enable and start service

# Enable and start the service
sudo systemctl enable sysmanage-agent
sudo systemctl start sysmanage-agent

# Check status
sudo systemctl status sysmanage-agent

# View logs
sudo journalctl -u sysmanage-agent -f

openSUSE/SLES systemd service

Create /etc/systemd/system/sysmanage-agent.service:

[Unit]
Description=SysManage Agent
After=network.target
Wants=network.target

[Service]
Type=simple
ExecStart=/opt/sysmanage-agent/.venv/bin/python /opt/sysmanage-agent/main.py
Restart=always
RestartSec=10
User=sysmanage-agent
Group=sysmanage-agent
WorkingDirectory=/opt/sysmanage-agent

# SUSE-specific security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/log
ProtectHome=true
CapabilityBoundingSet=

[Install]
WantedBy=multi-user.target

Service management commands

# Enable and start the service
sudo systemctl enable sysmanage-agent
sudo systemctl start sysmanage-agent

# Check status
sudo systemctl status sysmanage-agent

# View logs
sudo journalctl -u sysmanage-agent -f

# openSUSE/SLES specific commands
sudo zypper install systemd-presets  # If not installed
sudo systemctl daemon-reload         # Reload systemd

🏢 SUSE Enterprise Notes

Firewall: Open required ports via YaST or firewall-cmd
SELinux: May require setsebool or custom policies
AppArmor: SUSE uses AppArmor instead of SELinux by default
Logging: Logs available via journalctl or /var/log/messages

Windows Service Installation

# Install as Windows service using NSSM or similar
# Or run as scheduled task at startup

# Example using Task Scheduler:
# 1. Open Task Scheduler
# 2. Create Basic Task
# 3. Set trigger to "At startup"
# 4. Set action to start program: python.exe
# 5. Set arguments: C:\path\to\sysmanage-agent\main.py
# 6. Set working directory to agent directory

Create launchd service

Create /Library/LaunchDaemons/com.sysmanage.agent.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.sysmanage.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/sysmanage-agent/.venv/bin/python</string>
        <string>/opt/sysmanage-agent/main.py</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Load the service

# Load and start the service
sudo launchctl load /Library/LaunchDaemons/com.sysmanage.agent.plist
sudo launchctl start com.sysmanage.agent

Troubleshooting

Connection Issues

Server connectivity: telnet sysmanage.example.com 6443
DNS resolution: nslookup sysmanage.example.com
SSL certificate: openssl s_client -connect sysmanage.example.com:6443

Permission Issues

Check agent user permissions: sudo -u sysmanage-agent python main.py --debug
Verify file permissions: ls -la /etc/sysmanage-agent.yaml
Check log file access: ls -la /var/log/sysmanage-agent.log

Python Package Issues

Cryptography build errors: Ensure Rust is installed and in PATH
Missing dependencies: Install build tools and development libraries
Python 3.13 compatibility: Use Python 3.11 or 3.12 instead

Auto-Discovery Issues

Ensure UDP ports 31337 and 31338 are accessible
Check firewall rules on both agent and server
Verify server discovery service is enabled