> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/rpm.md).

# RPM

RPM - host RPM packages in Harness Artifacts

Use an **RPM** registry to host private RPM packages, and install them using YUM or DNF.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Make sure YUM or DNF is installed on your local machine.
* Make sure you have a Harness API key to authenticate upload requests to the registry.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create an RPM Registry

To create an RPM registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **RPM** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch RPM packages from external sources when they are not available locally.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **RPM** as the **Registry type**.
7. Select **Custom** as the **Source**, then specify the **Remote registry URL**.
8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required. This works for public RPM repositories.
9. Click **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing RPM Artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Click **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If an RPM package is not found in your Harness registry, the upstream proxy fetches it from the remote registry and caches it.
{% endhint %}

## RPM client setup

In your RPM Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for YUM or DNF.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your RPM Artifact Registry, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. Use the token in place of `<IDENTITY_TOKEN>` in the following steps.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Select **YUM** or **DNF** for your client. In the code samples, replace the values in angle brackets with your own values.

{% hint style="info" %}
**YUM and DNF setup is identical**

Both tools read `.repo` files from the same `/etc/yum.repos.d/` directory, so the configuration steps are the same whether you use YUM or DNF.
{% endhint %}

{% tabs %}
{% tab title="YUM" %}
**1. Configure the repository**

Create or edit the `.repo` file:

```bash
sudo vi /etc/yum.repos.d/<REGISTRY_NAME>.repo
```

Add the following content:

```ini
[<REGISTRY_NAME>]
name=<REGISTRY_NAME>
baseurl=https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/rpm
enabled=1
gpgcheck=0
username=<USERNAME>
password=<IDENTITY_TOKEN>
```

**2. Publish the package**

Upload an RPM package to the registry:

```bash
curl --location --request PUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/rpm/' \
--form 'file=@"<FILE_PATH>"' \
--header 'x-api-key: <API_KEY>'
```

**3. Install the package**

Clear the YUM cache:

```bash
sudo yum clean all
```

Install the package:

```bash
sudo yum install <ARTIFACT_NAME>
```

{% endtab %}

{% tab title="DNF" %}
**1. Configure the repository**

Create or edit the `.repo` file:

```bash
sudo vi /etc/yum.repos.d/<REGISTRY_NAME>.repo
```

Add the following content:

```ini
[<REGISTRY_NAME>]
name=<REGISTRY_NAME>
baseurl=https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/rpm
enabled=1
gpgcheck=0
username=<USERNAME>
password=<IDENTITY_TOKEN>
```

**2. Publish the package**

Upload an RPM package to the registry:

```bash
curl --location --request PUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/rpm/' \
--form 'file=@"<FILE_PATH>"' \
--header 'x-api-key: <API_KEY>'
```

**3. Install the package**

Clear the DNF cache:

```bash
sudo dnf clean all
```

Install the package:

```bash
sudo dnf install <ARTIFACT_NAME>
```

{% endtab %}
{% endtabs %}

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

1. On a host with no cached YUM or DNF metadata for the registry, install the package you published.
2. Confirm that the package manager downloaded the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step shows the shape of a publish step. Store the API key as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        curl --location --request PUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/rpm/' \
        --form 'file=@"<PACKAGE_NAME>-'"$PACKAGE_VERSION"'.rpm"' \
        --header 'x-api-key: <API_KEY>'
```

## Troubleshooting

<details>

<summary>`yum install` or `dnf install` fails with `401` or `403`</summary>

Check that the `username` and `password` values in your `.repo` file match the identity token you generated in **Setup Client**. If the token expired or was revoked, generate a new one and update the `.repo` file.

</details>

<details>

<summary>An RPM upload returns `409 Conflict`</summary>

RPM package versions are immutable after upload. Build a new release version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`yum install` or `dnf install` reports `No package available`</summary>

Check that the package name and the `baseurl` in your `.repo` file match the registry name and account ID shown in **Setup Client**. Also check that the package upload completed successfully.

</details>

<details>

<summary>`Setup Client` does not show upload instructions for an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** omits upload instructions. Publish RPM packages to a virtual registry instead, or let the upstream proxy cache packages from the remote source on demand.

</details>

<details>

<summary>`yum install` or `dnf install` resolves an old version after a new upload</summary>

Clear the YUM or DNF cache with `sudo yum clean all` or `sudo dnf clean all`, then retry the install.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
