Documentation > Administration > Package Management

Package Management

Comprehensive guide to managing software packages across your infrastructure including installation, uninstallation, and operation tracking.

Overview

SysManage provides a unified interface for managing software packages across multiple operating systems and package managers. The platform supports both installation and uninstallation operations with comprehensive tracking, logging, and status monitoring.

Key Features

  • Cross-Platform Support: Works with apt, yum/dnf, pkg (FreeBSD), pkg_add (OpenBSD), and Homebrew
  • Batch Operations: Install or uninstall multiple packages in a single operation
  • Real-time Tracking: Monitor operation status and progress in real-time
  • Comprehensive Logging: Detailed logs for all package operations
  • User Attribution: Track which user initiated each operation
  • Safety Features: Confirmation dialogs and rollback capabilities

Package Installation

Installation Process

Package installation in SysManage follows a structured workflow:

  1. User initiates installation from the web interface
  2. Request is validated and queued on the server
  3. Installation request is sent to the target agent via message queue
  4. Agent downloads and installs the package using the appropriate package manager
  5. Installation results are reported back and logged
  6. User receives real-time status updates

Using the Web Interface

Installing Individual Packages

  1. Navigate to the host detail page
  2. Go to the "Software Inventory" tab
  3. Use the search functionality to find available packages
  4. Click the "Install" button next to the desired package
  5. Confirm the installation in the dialog
  6. Monitor progress in the "Software Changes" tab

Bulk Package Installation

SysManage supports installing multiple packages in a single operation through the API. This is efficient for system setup and bulk deployments.

Installation Tracking

Every installation operation is tracked with the following information:

  • Request ID: Unique UUID for the installation request
  • Package Details: Name, version, and package manager
  • User Attribution: Who requested the installation
  • Timestamps: Request time, start time, and completion time
  • Status: pending, queued, installing, completed, failed, cancelled
  • Results: Success/failure status and installation logs

Package Uninstallation

Uninstallation Process

Package uninstallation follows a similar but more safety-focused workflow:

  1. User initiates uninstallation from the software inventory
  2. System displays confirmation dialog with package details
  3. Request is validated and queued with operation type "uninstall"
  4. Uninstallation request is sent to the target agent
  5. Agent removes the package using the appropriate package manager
  6. Uninstallation results are reported back and logged
  7. Software inventory is updated to reflect changes

Using the Web Interface for Uninstallation

Uninstalling Individual Packages

  1. Navigate to the host detail page
  2. Go to the "Software Inventory" tab
  3. Find the installed package you want to remove
  4. Click the "Uninstall" button next to the package
  5. Important: Carefully review the confirmation dialog
  6. Confirm the uninstallation by clicking "Uninstall"
  7. Monitor progress in the "Software Changes" tab

⚠️ Important Safety Considerations

  • Package uninstallation is irreversible through the UI
  • Removing system packages may cause system instability
  • Dependencies may be automatically removed by the package manager
  • Always test uninstallations in non-production environments first
  • Create system backups before removing critical packages

Bulk Package Uninstallation

Multiple packages can be uninstalled in a single operation via the API. This is useful for:

  • System cleanup and maintenance
  • Removing obsolete software suites
  • Standardizing system configurations
  • Security-driven package removal

Uninstallation Tracking

Uninstallation operations are tracked with the same detail as installations:

  • Operation Type: Clearly marked as "uninstall" in logs
  • Package Information: Name, version, and dependencies removed
  • Audit Trail: Complete record of who removed what and when
  • Command Output: Full package manager output for troubleshooting
  • Status Tracking: Real-time status updates during removal

Operation Monitoring and Tracking

Software Changes Tab

The "Software Changes" tab (previously "Software Installs") provides a comprehensive view of all package operations:

Key Information Displayed

  • Operation Type: Install or Uninstall label with appropriate styling
  • Package Name: Name of the package that was modified
  • Version: Package version involved in the operation
  • Status: Current status of the operation
  • Requested By: User who initiated the operation
  • Timestamps: When the operation was requested and completed
  • Results: Success/failure status and error details if applicable

Status Values

  • pending: Operation queued but not yet started
  • in_progress: Agent is currently processing the operation
  • completed: Operation finished successfully
  • failed: Operation encountered an error
  • cancelled: Operation was cancelled before completion

Real-time Status Updates

SysManage provides real-time updates through WebSocket connections:

  • Status changes are immediately reflected in the web interface
  • Success/failure notifications appear as snackbar messages
  • Progress indicators show operation advancement
  • Error messages provide immediate feedback for failed operations

Logging and Auditing

All package operations are comprehensively logged for auditing and troubleshooting:

Database Logging

  • Operation Records: Stored in software_installation_log table
  • Request Tracking: UUID-based tracking for grouped operations
  • User Attribution: Every operation linked to the requesting user
  • Detailed Metadata: Package manager, versions, timestamps

Agent Logging

  • Command Execution: Full package manager command output
  • Error Details: Detailed error messages and stack traces
  • Environment Info: System state during operation execution
  • Dependency Information: Details about packages installed/removed as dependencies

Supported Package Managers

APT (Debian/Ubuntu)

  • Installation: apt-get install -y package-name
  • Uninstallation: apt-get remove -y package-name
  • Features: Automatic dependency resolution, security updates
  • Notes: Uses DEBIAN_FRONTEND=noninteractive for automation

YUM/DNF (RHEL/CentOS/Fedora)

  • Installation: yum install -y package-name or dnf install -y package-name
  • Uninstallation: yum remove -y package-name or dnf remove -y package-name
  • Features: Repository management, group installations
  • Notes: Automatic detection between yum and dnf

PKG (FreeBSD)

  • Installation: pkg install -y package-name
  • Uninstallation: pkg delete -y package-name
  • Features: Binary package management, ports collection integration
  • Notes: Supports both binary packages and ports

PKG_ADD (OpenBSD)

  • Installation: pkg_add package-name
  • Uninstallation: pkg_delete package-name
  • Features: Simple, secure package management
  • Notes: Uses release-specific package repositories

Homebrew (macOS)

  • Installation: brew install package-name
  • Uninstallation: brew uninstall package-name
  • Features: Source and binary packages, cask support
  • Notes: Requires user-space installation

Automatic Package Manager Detection

SysManage agents automatically detect the appropriate package manager based on:

  • Operating system type and version
  • Available package manager binaries
  • System configuration and package database presence
  • User-specified preferences in configuration

Database Schema

Software Installation Log Table

The software_installation_log table tracks all package operations:

CREATE TABLE software_installation_log (
    id SERIAL PRIMARY KEY,
    host_id INTEGER REFERENCES host(id) ON DELETE CASCADE,

    -- Package details
    package_name VARCHAR(255) NOT NULL,
    package_manager VARCHAR(50) NOT NULL,
    requested_version VARCHAR(100),
    requested_by VARCHAR(100) NOT NULL,

    -- Request tracking
    installation_id VARCHAR(36) NOT NULL UNIQUE,  -- UUID
    status VARCHAR(20) DEFAULT 'pending',
    operation_type VARCHAR(20) DEFAULT 'install',  -- NEW: install/uninstall

    -- Timestamps
    requested_at TIMESTAMP WITH TIME ZONE NOT NULL,
    queued_at TIMESTAMP WITH TIME ZONE,
    started_at TIMESTAMP WITH TIME ZONE,
    completed_at TIMESTAMP WITH TIME ZONE,

    -- Results
    installed_version VARCHAR(100),
    success BOOLEAN,
    error_message TEXT,
    installation_log TEXT,

    -- Metadata
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

Key Schema Changes for Uninstall Support

  • operation_type column: Distinguishes between 'install' and 'uninstall' operations
  • Enhanced indexing: Optimized queries for operation type filtering
  • Backward compatibility: Existing records default to 'install' operation

UUID-based Request Tracking

Package operations use UUID-based tracking for grouped operations:

CREATE TABLE installation_requests (
    id VARCHAR(36) PRIMARY KEY,  -- UUID
    host_id INTEGER REFERENCES host(id) ON DELETE CASCADE,
    requested_by VARCHAR(100) NOT NULL,
    requested_at TIMESTAMP WITH TIME ZONE NOT NULL,
    completed_at TIMESTAMP WITH TIME ZONE,
    status VARCHAR(20) DEFAULT 'pending',
    result_log TEXT,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL
);

CREATE TABLE installation_packages (
    id SERIAL PRIMARY KEY,
    installation_request_id VARCHAR(36) REFERENCES installation_requests(id) ON DELETE CASCADE,
    package_name VARCHAR(255) NOT NULL,
    package_manager VARCHAR(50) NOT NULL
);

Benefits of UUID Tracking

  • Groups multiple packages into a single operation
  • Enables atomic success/failure for batch operations
  • Simplifies progress tracking and reporting
  • Provides clear audit trail for complex operations

Best Practices

Operational Best Practices

  • Test First: Always test package operations in development/staging environments
  • Backup Systems: Create system snapshots before major package changes
  • Read Dependencies: Review package dependencies before uninstallation
  • Monitor Resources: Ensure adequate disk space and memory before operations
  • Schedule Wisely: Perform major package operations during maintenance windows
  • Document Changes: Maintain records of package modifications for compliance

Security Best Practices

  • Role-based Access: Restrict package management to authorized users
  • Audit Logging: Review package operation logs regularly
  • Source Verification: Use trusted package repositories only
  • Vulnerability Management: Keep security-critical packages updated
  • Change Control: Implement approval workflows for critical systems
  • Incident Response: Have rollback procedures for failed operations

Performance Best Practices

  • Batch Operations: Group related packages into single operations
  • Repository Caching: Maintain local package mirrors for large deployments
  • Network Optimization: Schedule operations during low-traffic periods
  • Resource Planning: Consider system load when planning operations
  • Parallel Execution: Use agent concurrency for multiple hosts
  • Progress Monitoring: Monitor operation progress to identify bottlenecks

Related Documentation

Package Management API → Monitoring & Alerts → Basic Management Guide →