Documentation > API Reference > Third-Party Repositories

Third-Party Repositories API

Centralized management of third-party package repositories across multiple operating systems and platforms.

Overview

The Third-Party Repositories API provides centralized management of package repositories across Debian, Ubuntu, RHEL-based, SUSE-based, FreeBSD, NetBSD, Windows, and macOS systems. Repositories are automatically distributed to matching hosts based on OS name and version.

Key Features

  • Automatic OS Detection: Repositories are automatically sent to all hosts matching the specified OS and version
  • GPG Key Management: Automatic GPG key import and verification for Linux systems
  • Cross-Platform Support: Support for all major package management systems
  • User Attribution: Track which administrator added each repository

Repository Management

POST /api/third-party-repositories

Add a new third-party repository configuration. The repository will be automatically distributed to all hosts matching the specified OS name and version.

🔒 Authentication Required (Admin)

Request Body

{
  "os_name": "Ubuntu",
  "os_version": "24.04",
  "repository_config": "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable",
  "gpg_key_url": "https://download.docker.com/linux/ubuntu/gpg",
  "gpg_key_content": null
}

Parameters

Parameter Type Required Description
os_name string Yes Target operating system name (e.g., "Ubuntu", "CentOS", "FreeBSD")
os_version string Yes Specific OS version (e.g., "24.04", "9", "14.1")
repository_config string Yes Complete repository configuration in OS-specific format
gpg_key_url string No URL to GPG signing key for verification (Linux systems)
gpg_key_content string No GPG key content directly (alternative to URL)

Response (201 Created)

{
  "id": 1,
  "os_name": "Ubuntu",
  "os_version": "24.04",
  "repository_config": "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable",
  "gpg_key_url": "https://download.docker.com/linux/ubuntu/gpg",
  "added_by": "admin@example.com",
  "created_at": "2024-10-08T10:00:00Z",
  "hosts_notified": 12
}

Error Responses

400 Bad Request - Invalid repository configuration format
401 Unauthorized - Authentication required
403 Forbidden - Admin privileges required
500 Internal Server Error - Server error occurred
GET /api/third-party-repositories

List all configured third-party repositories.

🔒 Authentication Required

Response (200 OK)

[
  {
    "id": 1,
    "os_name": "Ubuntu",
    "os_version": "24.04",
    "repository_config": "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable",
    "gpg_key_url": "https://download.docker.com/linux/ubuntu/gpg",
    "added_by": "admin@example.com",
    "created_at": "2024-10-08T10:00:00Z",
    "host_count": 12
  },
  {
    "id": 2,
    "os_name": "CentOS",
    "os_version": "9",
    "repository_config": "[docker]\nname=Docker Repository\nbaseurl=https://download.docker.com/linux/centos/9/x86_64/stable\nenabled=1\ngpgcheck=1",
    "gpg_key_url": "https://download.docker.com/linux/centos/gpg",
    "added_by": "admin@example.com",
    "created_at": "2024-10-08T11:00:00Z",
    "host_count": 8
  }
]
GET /api/third-party-repositories/{id}

Get details of a specific repository configuration.

🔒 Authentication Required

Response (200 OK)

{
  "id": 1,
  "os_name": "Ubuntu",
  "os_version": "24.04",
  "repository_config": "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable",
  "gpg_key_url": "https://download.docker.com/linux/ubuntu/gpg",
  "gpg_key_content": null,
  "added_by": "admin@example.com",
  "created_at": "2024-10-08T10:00:00Z",
  "affected_hosts": [
    {
      "hostname": "web-server-01",
      "status": "applied",
      "applied_at": "2024-10-08T10:01:23Z"
    },
    {
      "hostname": "web-server-02",
      "status": "applied",
      "applied_at": "2024-10-08T10:01:45Z"
    }
  ]
}
DELETE /api/third-party-repositories/{id}

Remove a repository configuration. This will remove the repository from all affected hosts and update their package cache.

🔒 Authentication Required (Admin)

Response (200 OK)

{
  "message": "Repository removed successfully",
  "hosts_notified": 12,
  "repository_id": 1
}

Error Responses

401 Unauthorized - Authentication required
403 Forbidden - Admin privileges required
404 Not Found - Repository not found
500 Internal Server Error - Server error occurred

Usage Examples

Add Docker Repository to Ubuntu Hosts

curl -X POST https://sysmanage.example.com/api/third-party-repositories \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "os_name": "Ubuntu",
    "os_version": "24.04",
    "repository_config": "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable",
    "gpg_key_url": "https://download.docker.com/linux/ubuntu/gpg"
  }'

Add EPEL Repository to RHEL Hosts

curl -X POST https://sysmanage.example.com/api/third-party-repositories \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "os_name": "RHEL",
    "os_version": "9",
    "repository_config": "[epel]\nname=Extra Packages for Enterprise Linux 9 - $basearch\nbaseurl=https://download.fedoraproject.org/pub/epel/9/Everything/$basearch/\nenabled=1\ngpgcheck=1",
    "gpg_key_url": "https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-9"
  }'

List All Repositories

curl -X GET https://sysmanage.example.com/api/third-party-repositories \
  -H "Authorization: Bearer $API_TOKEN"

Remove a Repository

curl -X DELETE https://sysmanage.example.com/api/third-party-repositories/1 \
  -H "Authorization: Bearer $API_TOKEN"

Repository Configuration Formats by Platform

Debian/Ubuntu

deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable

RHEL/CentOS/Fedora

[docker-ce]
name=Docker CE Stable - $basearch
baseurl=https://download.docker.com/linux/centos/9/$basearch/stable
enabled=1
gpgcheck=1

openSUSE/SLES

https://download.opensuse.org/repositories/Virtualization:/containers/15.4/

FreeBSD

https://pkg.example.com/freebsd/${ABI}/latest

macOS (Homebrew)

user/tap-name
https://github.com/user/homebrew-tap-name

Windows (Chocolatey)

https://chocolatey.example.com/repository

API Best Practices

Security Considerations

  • HTTPS Only: Always use HTTPS repository URLs to prevent man-in-the-middle attacks
  • GPG Keys: Provide GPG keys for all Linux repositories to ensure package verification
  • Verify Sources: Only add repositories from trusted, verified sources
  • Admin Only: Repository management requires administrative privileges

Operational Best Practices

  • Test First: Test repository configurations on non-production systems before adding
  • Document Purpose: Maintain external documentation of why each repository was added
  • Monitor Application: Check affected_hosts in API responses to verify successful distribution
  • Version Control: Track API calls in version control or configuration management systems

Related Documentation

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