Documentation > Getting Started > Agent Setup

Agent Setup and Approval

Learn how to install, configure, and approve SysManage agents on your hosts for comprehensive monitoring.

Agent Overview

SysManage agents are lightweight programs that run on your hosts to collect system information, manage packages, and execute administrative tasks. Agents communicate securely with the SysManage server using mTLS authentication.

Prerequisites: Ensure your SysManage server is running and accessible. Complete the First Deployment guide if needed.

Agent Features

  • System Monitoring: Hardware specs, uptime, resource usage
  • Package Management: Inventory, updates, installations
  • Security Updates: Automated detection and installation
  • Cross-Platform: Linux, BSD, macOS, Windows support
  • Secure Communication: mTLS encryption and authentication
  • Privileged Operations: Configurable sudo access

1. Agent Installation

Linux Installation

Ubuntu/Debian

# Download and install agent
wget https://github.com/bceverly/sysmanage-agent/releases/latest/download/sysmanage-agent-linux-amd64.deb
sudo dpkg -i sysmanage-agent-linux-amd64.deb

# Or install from source
git clone https://github.com/bceverly/sysmanage-agent.git
cd sysmanage-agent
sudo make install

RHEL/CentOS/Fedora

# Download and install agent
wget https://github.com/bceverly/sysmanage-agent/releases/latest/download/sysmanage-agent-linux-amd64.rpm
sudo rpm -i sysmanage-agent-linux-amd64.rpm

# Or install from source
git clone https://github.com/bceverly/sysmanage-agent.git
cd sysmanage-agent
sudo make install

Arch Linux

# Install from AUR
yay -S sysmanage-agent

# Or install from source
git clone https://github.com/bceverly/sysmanage-agent.git
cd sysmanage-agent
sudo make install

BSD Installation

FreeBSD

# Install from ports
cd /usr/ports/sysutils/sysmanage-agent
make install clean

# Or install package
pkg install sysmanage-agent

OpenBSD

# Install package
pkg_add sysmanage-agent

# Or install from source
git clone https://github.com/bceverly/sysmanage-agent.git
cd sysmanage-agent
doas make install

macOS Installation

Homebrew

# Install via Homebrew
brew tap bceverly/sysmanage
brew install sysmanage-agent

Manual Installation

# Download and install
curl -L https://github.com/bceverly/sysmanage-agent/releases/latest/download/sysmanage-agent-darwin-amd64.pkg -o sysmanage-agent.pkg
sudo installer -pkg sysmanage-agent.pkg -target /

Windows Installation

MSI Installer

# Download and install MSI package
Invoke-WebRequest -Uri "https://github.com/bceverly/sysmanage-agent/releases/latest/download/sysmanage-agent-windows-amd64.msi" -OutFile "sysmanage-agent.msi"
Start-Process msiexec.exe -ArgumentList "/i sysmanage-agent.msi /quiet" -Wait

Chocolatey

# Install via Chocolatey
choco install sysmanage-agent

2. Agent Configuration

Configuration File Location

The agent configuration file is located at:

  • Linux/BSD: /etc/sysmanage-agent/sysmanage-agent.yaml
  • macOS: /usr/local/etc/sysmanage-agent/sysmanage-agent.yaml
  • Windows: C:\Program Files\SysManage Agent\config\sysmanage-agent.yaml

Basic Configuration

Edit the configuration file with your server details:

# SysManage Agent Configuration
server:
  host: "sysmanage.yourdomain.com"
  port: 8444
  ssl_enabled: true
  ssl_verify: true

# Agent identification
agent:
  name: "web-server-01"
  tags:
    - "production"
    - "web"
    - "critical"
  location: "datacenter-1"

# Certificate paths (auto-generated on first run)
security:
  cert_file: "/etc/sysmanage-agent/certs/agent.crt"
  key_file: "/etc/sysmanage-agent/certs/agent.key"
  ca_file: "/etc/sysmanage-agent/certs/ca.crt"

# Package management
packages:
  enabled: true
  auto_update_security: false
  excluded_packages:
    - "kernel*"
    - "grub*"

# System monitoring
monitoring:
  enabled: true
  interval: 300  # 5 minutes
  collect_metrics: true
  collect_logs: false

# Privileged operations
privileged:
  enabled: false
  allowed_commands: []

logging:
  level: "INFO"
  file: "/var/log/sysmanage-agent/agent.log"

Advanced Configuration Options

Network Configuration

network:
  connection_timeout: 30
  retry_attempts: 3
  retry_delay: 5
  proxy:
    enabled: false
    url: "http://proxy.company.com:8080"
    username: ""
    password: ""

Security Configuration

security:
  # Certificate validation
  ssl_verify: true
  ssl_cert_file: "/path/to/server.crt"

  # Client certificate authentication
  cert_file: "/etc/sysmanage-agent/certs/agent.crt"
  key_file: "/etc/sysmanage-agent/certs/agent.key"

  # Auto-enrollment settings
  auto_enroll: true
  enrollment_token: "your-enrollment-token"

3. Certificate Setup

Automatic Certificate Generation

On first startup, the agent automatically generates a certificate signing request (CSR) and submits it to the server for approval:

# Start the agent service
sudo systemctl start sysmanage-agent

# Check agent logs for certificate generation
sudo journalctl -u sysmanage-agent -f

You should see log entries similar to:

INFO: Generating new certificate key pair
INFO: Creating certificate signing request
INFO: Submitting CSR to server for approval
INFO: Waiting for certificate approval...

Manual Certificate Setup

For environments requiring manual certificate management:

Generate Certificate Request

# Generate private key
openssl genrsa -out agent.key 2048

# Generate certificate signing request
openssl req -new -key agent.key -out agent.csr \
    -subj "/CN=web-server-01/O=YourOrganization"

# Submit CSR to SysManage server
curl -k -X POST https://sysmanage.yourdomain.com:8444/api/agent/csr \
    -H "Content-Type: application/json" \
    -d '{"csr": "'$(base64 -w 0 agent.csr)'", "hostname": "web-server-01"}'

Certificate Verification

Verify certificate setup is working:

# Test certificate
openssl x509 -in /etc/sysmanage-agent/certs/agent.crt -text -noout

# Test connection to server
sysmanage-agent --test-connection

4. Server-Side Agent Approval

Web Interface Approval

  1. Log into the SysManage web interface
  2. Navigate to Hosts → Pending Approval
  3. Review the pending agent certificate requests
  4. Verify the agent details (hostname, IP, fingerprint)
  5. Click Approve to approve the agent

CLI Approval

Approve agents using the command line interface:

# List pending approvals
sysmanage-cli agent list-pending

# Approve specific agent
sysmanage-cli agent approve --hostname web-server-01 --fingerprint SHA256:abc123...

# Approve all pending agents (use with caution)
sysmanage-cli agent approve-all

API Approval

Approve agents programmatically via API:

# Get pending approvals
curl -k -H "Authorization: Bearer $JWT_TOKEN" \
    https://sysmanage.yourdomain.com:8443/api/agents/pending

# Approve agent
curl -k -X POST -H "Authorization: Bearer $JWT_TOKEN" \
    -H "Content-Type: application/json" \
    https://sysmanage.yourdomain.com:8443/api/agents/approve \
    -d '{"agent_id": "agent-uuid", "approved": true}'

5. Service Management

Linux/BSD Service Management

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

# Check service status
sudo systemctl status sysmanage-agent

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

# Restart service
sudo systemctl restart sysmanage-agent

macOS Service Management

# Load launch daemon
sudo launchctl load /Library/LaunchDaemons/com.sysmanage.agent.plist

# Start service
sudo launchctl start com.sysmanage.agent

# Check status
sudo launchctl list | grep sysmanage

# Stop service
sudo launchctl stop com.sysmanage.agent

Windows Service Management

# Start service
Start-Service "SysManage Agent"

# Check service status
Get-Service "SysManage Agent"

# Set service to automatic startup
Set-Service "SysManage Agent" -StartupType Automatic

# View logs (Event Viewer or PowerShell)
Get-EventLog -LogName Application -Source "SysManage Agent" -Newest 10

6. Verification and Testing

Agent Status Verification

Verify the agent is communicating properly with the server:

Web Interface Checks

  • Agent appears in the Hosts list
  • Status shows as "Online" or "Connected"
  • System information is populated
  • Package inventory is available
  • Last contact time is recent

Command Line Checks

# Test agent connectivity
sysmanage-agent --status

# Test server communication
sysmanage-agent --ping-server

# View agent information
sysmanage-agent --info

Log File Checks

# Check for successful connection
grep "Successfully connected" /var/log/sysmanage-agent/agent.log

# Check for certificate issues
grep -i "certificate\|ssl\|tls" /var/log/sysmanage-agent/agent.log

# Check for communication errors
grep -i "error\|failed\|timeout" /var/log/sysmanage-agent/agent.log

7. Bulk Agent Deployment

Ansible Deployment

Example Ansible playbook for deploying agents:

---
- name: Deploy SysManage Agents
  hosts: all
  become: yes
  vars:
    sysmanage_server: "sysmanage.yourdomain.com"
    sysmanage_port: 8444

  tasks:
    - name: Download agent package
      get_url:
        url: "https://github.com/bceverly/sysmanage-agent/releases/latest/download/sysmanage-agent-linux-amd64.deb"
        dest: "/tmp/sysmanage-agent.deb"
      when: ansible_os_family == "Debian"

    - name: Install agent package
      apt:
        deb: "/tmp/sysmanage-agent.deb"
      when: ansible_os_family == "Debian"

    - name: Configure agent
      template:
        src: sysmanage-agent.yaml.j2
        dest: /etc/sysmanage-agent/sysmanage-agent.yaml
        mode: '0600'
      notify: restart sysmanage-agent

    - name: Start and enable agent service
      systemd:
        name: sysmanage-agent
        enabled: yes
        state: started

  handlers:
    - name: restart sysmanage-agent
      systemd:
        name: sysmanage-agent
        state: restarted

Configuration Template

Ansible template (sysmanage-agent.yaml.j2):

server:
  host: "{{ sysmanage_server }}"
  port: {{ sysmanage_port }}
  ssl_enabled: true

agent:
  name: "{{ inventory_hostname }}"
  tags:
    - "{{ group_names | join('", "') }}"
  location: "{{ datacenter | default('unknown') }}"

packages:
  enabled: true
  auto_update_security: {{ auto_security_updates | default(false) }}

monitoring:
  enabled: true
  interval: 300

8. Troubleshooting

Common Issues

Agent Not Connecting

  • Check network connectivity to server
  • Verify server hostname and port
  • Check firewall rules
  • Verify SSL certificate configuration

Certificate Issues

  • Check certificate file permissions
  • Verify certificate validity dates
  • Ensure CA certificate is correct
  • Check for certificate approval on server

Service Start Issues

  • Check configuration file syntax
  • Verify file permissions
  • Check system requirements
  • Review systemd logs

Performance Issues

  • Adjust monitoring interval
  • Check system resource usage
  • Review network latency
  • Optimize configuration settings

Diagnostic Commands

# Test network connectivity
telnet sysmanage.yourdomain.com 8444

# Test SSL connection
openssl s_client -connect sysmanage.yourdomain.com:8444

# Check certificate details
openssl x509 -in /etc/sysmanage-agent/certs/agent.crt -text -noout

# Test agent configuration
sysmanage-agent --config-test

# Enable debug logging
sysmanage-agent --log-level debug

9. Security Considerations

Certificate Security

  • Protect private keys with proper file permissions (600)
  • Regular certificate rotation (automated)
  • Monitor for certificate expiration
  • Use strong cryptographic algorithms

Network Security

  • Use firewall rules to restrict agent communication
  • Monitor network traffic for anomalies
  • Consider network segmentation
  • Use VPN for remote agents if needed

Privileged Operations

  • Enable privileged mode only when necessary
  • Restrict allowed commands using whitelists
  • Audit privileged operations
  • Use sudo with specific command restrictions

Next Steps

After successfully setting up your agents:

  1. Learn basic management: Master day-to-day operations
  2. Host management: Organize and manage your hosts
  3. Set up monitoring: Configure alerts and monitoring
  4. Privileged operations: Configure sudo access if needed

Navigation

← First Deployment Basic Management →