Documentation > Administration > Third-Party Repository Management

Third-Party Repository Management

Managing third-party package repositories on individual hosts through the SysManage web interface.

Overview

SysManage provides a graphical interface for managing third-party package repositories on individual hosts. This feature allows administrators to view, add, enable, disable, and remove repositories like Ubuntu PPAs, Fedora COPR repositories, openSUSE OBS repositories, macOS Homebrew taps, FreeBSD/NetBSD custom repositories, and Windows Chocolatey sources directly from the web UI.

Key Capabilities

  • View Current Repositories: See all third-party repositories currently configured on a host
  • Add Repositories: Add new repositories using OS-specific formats (PPA, COPR, OBS, Homebrew taps, etc.)
  • Enable/Disable: Toggle repositories on and off without removing them
  • Remove Repositories: Delete unwanted repositories from the host
  • Multi-Platform Support: Works across Debian/Ubuntu, RHEL/Fedora/CentOS, openSUSE/SLES, FreeBSD, NetBSD, macOS, and Windows
  • Real-Time Updates: Changes are sent to the host agent and applied immediately

⚠️ Important Notes

  • This feature requires the host to be in privileged mode (running as root/administrator)
  • You must have appropriate security role permissions (ADD_THIRD_PARTY_REPOSITORY, DELETE_THIRD_PARTY_REPOSITORY, etc.)
  • OpenBSD does not support third-party repositories and this feature is not available for OpenBSD hosts
  • Changes are applied per-host - this is not a centralized fleet-wide repository management tool

Accessing the Feature

The third-party repository management interface is accessed from the Host Detail page:

  1. Navigate to the Hosts page in the SysManage web UI
  2. Click on a host to open its detail page
  3. Scroll to the Third-Party Repositories section
  4. If the host is in privileged mode, you'll see the repository management interface

If you don't see the third-party repositories section, ensure:

  • The host agent is running in privileged mode (root/administrator)
  • You have the necessary security permissions
  • The host is not running OpenBSD

Supported Repository Formats by Operating System

Ubuntu / Debian - PPA (Personal Package Archives)

PPAs are the standard way to add third-party repositories on Ubuntu systems.

Adding a PPA

  • PPA Owner: The username of the PPA owner (e.g., "deadsnakes")
  • PPA Name: The name of the PPA (e.g., "ppa")
  • Result: ppa:deadsnakes/ppa

Example: To add the popular deadsnakes PPA for Python versions, enter:

  • PPA Owner: deadsnakes
  • PPA Name: ppa

Fedora / RHEL / CentOS - COPR

COPR (Cool Other Package Repo) is Fedora's community repository system.

Adding a COPR Repository

  • COPR Owner: The COPR project owner (e.g., "@dotnet-sig")
  • COPR Project: The project name (e.g., "dotnet")
  • Result: @dotnet-sig/dotnet

Example: To add the .NET COPR repository:

  • COPR Owner: @dotnet-sig
  • COPR Project: dotnet

openSUSE / SLES - OBS (Open Build Service)

OBS repositories provide additional packages for SUSE-based systems.

Adding an OBS Repository

  • Base URL: Usually https://download.opensuse.org/repositories/
  • Project Path: The OBS project path (e.g., "devel:/languages:/python")
  • Distribution Version: Your distribution version (e.g., "openSUSE_Leap_15.5")
  • Repository Name: A name for the repository (e.g., "python-devel")

Example: To add Python development packages from OBS:

  • Base URL: https://download.opensuse.org/repositories/
  • Project Path: devel:/languages:/python
  • Distribution Version: openSUSE_Leap_15.5
  • Repository Name: python-devel

macOS - Homebrew Taps

Taps are third-party Homebrew repositories hosted on GitHub or other Git servers.

Adding a Homebrew Tap

  • Tap User: The GitHub username (e.g., "homebrew")
  • Tap Repo: The tap repository name (e.g., "cask-versions")
  • Result: homebrew/cask-versions

Example: To add the Homebrew cask-versions tap:

  • Tap User: homebrew
  • Tap Repo: cask-versions

FreeBSD - pkg Repositories

Custom pkg repositories provide additional packages for FreeBSD.

Adding a pkg Repository

  • Repository Name: A name for your repository (e.g., "custom-repo")
  • Repository URL: The full URL to the repository

Example: To add a custom FreeBSD repository:

  • Repository Name: mycompany
  • Repository URL: https://pkg.mycompany.com/freebsd/${ABI}/latest

NetBSD - pkgsrc Repositories

Custom pkgsrc repositories for NetBSD binary packages.

Adding a pkgsrc Repository

  • Repository Name: A name for your repository
  • Repository URL: The full URL to the repository

Windows - Chocolatey Sources

Add custom Chocolatey package sources for Windows hosts.

Adding a Chocolatey Source

  • Source Type: Usually "chocolatey"
  • Source Name: A name for the source (e.g., "company-repo")
  • Source URL: The URL to your Chocolatey feed

Example: To add a private company Chocolatey repository:

  • Source Type: chocolatey
  • Source Name: company-internal
  • Source URL: https://chocolatey.company.com/repository

Using the Web Interface

Viewing Current Repositories

The repository list shows all currently configured third-party repositories on the host:

  • Name: The repository identifier
  • Type: The repository type (ppa, copr, obs, tap, etc.)
  • URL: The repository URL (if applicable)
  • Enabled: Whether the repository is currently enabled
  • File Path: The configuration file location on the host

The list auto-refreshes every 30 seconds to show current status.

Adding a New Repository

  1. Click the "Add Repository" button
  2. The dialog will show fields appropriate for your host's operating system
  3. Fill in the required fields (see supported formats above)
  4. The constructed repository string will be shown as you type
  5. Click "Add" to send the command to the host agent
  6. The repository list will refresh automatically after a few seconds

Enabling or Disabling Repositories

  1. Select one or more repositories from the list
  2. Click "Enable Selected" or "Disable Selected"
  3. Confirm the action in the dialog
  4. The changes will be applied to the host immediately

Note: Disabling a repository keeps it configured but prevents package managers from using it.

Removing Repositories

  1. Select one or more repositories from the list
  2. Click "Delete Selected"
  3. Confirm the deletion in the dialog
  4. The repositories will be permanently removed from the host

Warning: This permanently removes the repository configuration files from the host.

Refreshing the List

Click the "Refresh" button to manually update the repository list. The list also auto-refreshes every 30 seconds.

Required Permissions

To use third-party repository management features, users need specific security role permissions:

  • ADD_THIRD_PARTY_REPOSITORY: Required to add new repositories
  • DELETE_THIRD_PARTY_REPOSITORY: Required to remove repositories
  • ENABLE_THIRD_PARTY_REPOSITORY: Required to enable repositories
  • DISABLE_THIRD_PARTY_REPOSITORY: Required to disable repositories

Users without these permissions will see the repository list but won't be able to make changes.

Best Practices

Security Considerations

  • Verify Sources: Only add repositories from trusted sources you verify
  • Test First: Test new repositories on non-production hosts first
  • Document Purpose: Keep external documentation of why each repository was added
  • Regular Audits: Periodically review configured repositories and remove unused ones
  • Monitor Changes: Use SysManage's audit logging to track repository changes

Operational Best Practices

  • Limit Repositories: Only add repositories that are actually needed
  • Disable Rather Than Delete: Disable repositories temporarily instead of deleting if you might need them later
  • Check Compatibility: Ensure repositories match your exact OS version
  • Update After Adding: Run package updates after adding new repositories

Troubleshooting

Repository Section Not Visible

Symptoms: Third-party repositories section doesn't appear on Host Detail page

Solutions:

  • Verify the host agent is running in privileged mode (root/administrator)
  • Check that your user account has the required permissions
  • Confirm the host is not running OpenBSD (not supported)
  • Ensure the host is approved and connected

Repository Addition Fails

Symptoms: Error message when trying to add a repository

Solutions:

  • Verify the repository format is correct for the operating system
  • Check that the repository URL is accessible from the host
  • Ensure you have ADD_THIRD_PARTY_REPOSITORY permission
  • Review the error message for specific details
  • Check the host agent logs for more information

Changes Not Appearing

Symptoms: Repository added/removed but not shown in list

Solutions:

  • Wait a few seconds for the host agent to process the command
  • Click the Refresh button to manually update the list
  • Check the host's WebSocket connection status
  • Verify no network issues between server and agent

Permission Denied Errors

Symptoms: "Permission denied" errors when making changes

Solutions:

  • Verify you have the appropriate security role permissions
  • Contact your SysManage administrator to grant permissions
  • Ensure the host agent is running with sufficient privileges

Default Repositories

SysManage provides a centralized way to manage default third-party repositories that are automatically applied to all hosts of a specific operating system. This feature streamlines repository management across your entire fleet.

Overview

Default repositories are configured globally in the SysManage settings and are automatically:

  • Applied to New Hosts: When a host is approved during registration, all default repositories matching its OS are automatically added
  • Applied to Existing Hosts: When you create a new default repository, it is automatically added to all existing approved hosts with matching OS
  • Shown in Repository Lists: Default repositories appear in each host's repository list with a "Default" source badge

Accessing Default Repository Settings

  1. Navigate to Settings in the main navigation bar
  2. Click on Host Defaults
  3. Click the Repositories sub-tab

Adding a Default Repository

  1. In the Host Defaults > Repositories settings, click "Add Default Repository"
  2. Select the Operating System from the dropdown (Ubuntu, Fedora, CentOS Stream, openSUSE, etc.)
  3. Select the Package Manager (APT, DNF, YUM, Zypper, etc.)
  4. Fill in the OS-specific fields (same as adding a host-specific repository):
    • Ubuntu/Debian: PPA Owner and PPA Name
    • Fedora/RHEL/CentOS: COPR Owner and COPR Project
    • openSUSE/SLES: OBS URL, Project Path, Distribution Version, and Repository Name
    • macOS: Tap User and Tap Repository
    • FreeBSD: Repository Name and URL
    • NetBSD: Repository Name and URL
    • Windows: Repository Type, Name, and URL
  5. The repository identifier will be constructed automatically as you type
  6. Click "Add" to save the default repository

Automatic Application

When you add a default repository:

  1. The repository configuration is saved to the database
  2. SysManage finds all approved hosts matching the specified operating system
  3. Add repository commands are queued for each matching host
  4. The commands are sent to connected agents via WebSocket
  5. Each agent applies the repository to its host

Note: If an agent is not connected when the default repository is created, the system will automatically retry sending the command up to 3 times with exponential backoff (1 minute, 2 minutes, 4 minutes).

Viewing Default Repositories on Hosts

When viewing a host's Third-Party Repositories list, default repositories are shown with:

  • A "Default" source badge (blue chip)
  • The repository is not selectable for deletion or modification
  • If the same repository exists as both a default and host-specific entry, only the default is shown (deduplication)

Removing Default Repositories

To remove a default repository:

  1. Go to Settings > Host Defaults > Repositories
  2. Select the default repository you want to remove
  3. Click "Delete Selected"
  4. Confirm the deletion

When you delete a default repository:

  • The repository is removed from the default repository list
  • Delete commands are automatically queued for all hosts that have this repository
  • The repository is removed from all affected hosts
  • Future hosts will not receive this repository

Required Permissions

Managing default repositories requires:

  • VIEW_DEFAULT_REPOSITORIES: To view the default repositories list
  • ADD_DEFAULT_REPOSITORY: To create new default repositories
  • DELETE_DEFAULT_REPOSITORY: To remove default repositories

Best Practices for Default Repositories

  • Organization Standards: Use default repositories to enforce organizational standards across all hosts
  • Security Repositories: Add security-focused repositories as defaults to ensure all hosts receive security updates
  • Test Before Deploying: Test repositories on a few hosts before making them defaults
  • Document Purpose: Keep documentation of why each default repository exists
  • OS Version Matching: Be aware that repositories are matched by OS name only (e.g., "Ubuntu"), not by specific version
  • Monitor Application: Check that default repositories are successfully applied to hosts after creation

Difference Between Default and Host-Specific Repositories

Feature Default Repositories Host-Specific Repositories
Scope Applied to all hosts with matching OS Applied only to a single host
Configuration Location Settings > Host Defaults > Repositories Host Detail page > Third-Party Repositories
Automatic Application Yes, to new and existing hosts No, manual addition required
Can Be Deleted Per-Host No, must be removed from defaults Yes, deletable on individual hosts
Use Case Organization-wide standards Host-specific needs

Known Limitations

  • OpenBSD Not Supported: OpenBSD does not support third-party repositories by design
  • Privileged Mode Required: The host agent must be running as root/administrator
  • OS Name Matching Only: Default repositories match by OS name (e.g., "Ubuntu") not by specific version
  • No Version-Specific Defaults: You cannot create default repositories for specific OS versions (e.g., only Ubuntu 24.04)
  • Retry Limit: If a host is offline when a default repository is added, the system retries 3 times before giving up
  • Platform-Specific: Each OS has different repository formats and requirements

Related Documentation

Package Management → Host Management → Third-Party Repositories API →