How to set up repository mirroring end-to-end (26.04 and later)

Note

This document applies to Landscape Server 26.04 LTS and later. See the 26.04 LTS release notes for details on our changes to repository management in 26.04.

This guide demonstrates how to mirror part of the Ubuntu archive, publish it to object storage, and configure a client machine to install packages from the published repository. By the end of this guide, you’ll have a repository mirror set up and a package on your client machine.

It uses an opinionated setup with Amazon S3 as the publication target, but the steps generally apply to other object stores and configurations. For a broader set of repository management tasks, see How to manage and mirror repositories from the web portal (26.04 and later).

The workflow uses these repository management components:

  • A mirror: your copy of an upstream repository.

  • A publication target: where the copy is stored.

  • A publication: the configuration that connects a mirror to a target.

  • A repository profile: the configuration that tells your clients to use the published repository.

Background: repository signing

Client machines verify the repositories they install from using a signing key (a GPG key). When you publish a repository with Landscape, you can either preserve the upstream signing key or re-sign the repository with your own key.

This guide uses a re-signed publication, so you provide your own signing key. Landscape uses the private key to sign your published repository, and your client uses the matching public key to verify packages.

Prerequisites

Before you start, make sure you have:

  • A Landscape Server 26.04 LTS (or later) deployment with repository management set up. See Landscape installation and set-up for installation, and How to set up Deb Archive with Landscape to set up repository management. If you’re on a version earlier than 26.04, upgrade first by following How to upgrade to Landscape Server 26.04 LTS.

  • At least one registered client machine running Ubuntu.

  • An S3-compatible object store that you can write to, along with its region and a pair of access keys. This guide uses Amazon S3 as the example.

  • The object store must allow your client machine to read objects. In this guide, the client fetches packages directly from the storage URL without credentials, so public object read must be enabled.

Disk space requirements

This guide uses the main component and amd64 architecture in noble-backports to keep the example mirror small. Larger distributions with more components and architectures require more storage.

For disk space estimates, see Disk space requirements.

Step 1: Create a publication target

A publication target is the storage location where your mirrored repository is stored. Create it first so it’s available when you publish.

  1. From the sidebar, navigate to Repositories > Publication targets.

  2. Click Add publication target.

  3. Enter the name of the publication target. For example, s3-target.

  4. In the Type dropdown menu, select S3.

  5. Complete the S3 details for your bucket:

    • Region: the bucket’s region. For example, us-east-1.

    • Bucket: the bucket’s name.

    • AWS access key ID: your access key ID.

    • AWS secret access key: your secret access key.

  6. Click Add publication target.

A publication target is defined independently of any repository, so you can reuse it for other publications.

Step 2: Create and sync a mirror

A mirror is Landscape’s copy of an upstream Ubuntu repository. After you create it, sync it to download the packages from upstream.

  1. From the sidebar, navigate to Repositories > Mirrors.

  2. Click Add mirror.

  3. Enter the name of the mirror. For example, noble-backports-mirror.

  4. In the Source type dropdown menu, select Ubuntu archive.

  5. Use the default Source URL, which points at the Ubuntu archive.

  6. Leave the Preserve upstream signing key checkbox cleared. Landscape re-signs the mirror with your own key when you publish it.

  7. Under Mirror contents, select what to mirror. For example:

    • Distribution: noble-backports

    • Components: main

    • Architectures: amd64

  8. Click Add mirror.

To sync the mirror:

  1. From the Mirrors list, select the mirror you created.

  2. Click Update from the actions dropdown menu.

The sync downloads the upstream packages into Landscape so they’re ready to publish. The time this takes depends on the size of the repository, from a few minutes for a small mirror to several hours for a large one. A single-component, single-architecture mirror such as noble-backports main for amd64 is relatively small.

Step 3: Create a GPG key pair

Create a GPG key pair to sign the published repository:

gpg --full-generate-key

When prompted, do not set a passphrase on the key. Landscape needs direct access to the private key material for signing during publication.

Use this key pair in the next steps: paste the private key in the publication and the public key in the repository profile.

Step 4: Publish the mirror

A publication connects your mirror to your publication target and writes the repository into your object store.

To create the publication:

  1. From the sidebar, navigate to Repositories > Publications.

  2. Click Add publication.

  3. Enter the name of the publication. For example, noble-backports-publication.

  4. In the Source type dropdown menu, select Mirror.

  5. In the Source dropdown menu, select the mirror you created.

  6. In the Publication target dropdown menu, select the publication target you created.

  7. In the Architectures dropdown menu, select amd64.

  8. In the Signing GPG key field, paste your private GPG signing key.

  9. Click Add publication.

To publish the mirror:

  1. From the Mirrors list, select the mirror you created.

  2. Click Publish from the actions dropdown menu.

  3. Select Existing publication.

  4. In the Publication dropdown menu, select the publication you created.

  5. Click Publish Mirror.

Landscape copies the packages and writes a complete APT repository into your object store, signed with your key. When the publish finishes, the repository is available for clients.

Step 5: Create a repository profile and associate client machines

A repository profile applies an APT source to the client machines you associate with it. The configuration is applied one time when a machine is associated with the profile.

  1. From the sidebar, navigate to Repositories > Repository profiles.

  2. Click Add repository profile.

  3. In the Profile name field, enter a name for this profile. For example, noble-backports-profile.

  4. Click Add source to specify the Debian repository for this profile.

    1. In the Source name field, enter a name for the source.

    2. Add the deb line for your published repository, substituting your own bucket and region. For example:

      deb https://my-bucket.s3.us-east-1.amazonaws.com/ noble-backports main

    3. In the GPG key field, paste your public GPG signing key. Your client uses this key to verify packages, since Landscape re-signed the repository with your key.

  5. Use the Access group dropdown menu and Association section to associate this profile with an access group or tags.

  6. Optionally fill out the Description field.

  7. Save the profile.

Landscape creates activities to apply the new APT source to the associated client machines.

Step 6: Install a package from your mirror to the client machine

On a client machine associated with the repository profile, refresh the package lists:

sudo apt update

If apt update completes without any signature warnings, the client has verified your published repository against your signing key.

To confirm your mirror is a source for a package it contains, check its policy, replacing <PACKAGE> with a package that exists in your mirror:

apt-cache policy <PACKAGE>

Your object store’s address is listed among the sources for the package. Install it to confirm:

sudo apt install <PACKAGE>

See also