proxmox-apt-mirror tool
=======================

This tool consists of two binaries, `proxmox-apt-mirror` (mirror tool to create
and manage mirrors and media containing repositories) and `proxmox-apt-repo`
(helper to use media on offline systems).

There are two basic entity types available for configuration:
- mirrors, consisting of upstream repository metadata and a local path where snapshots are stored
-- configured with `proxmox-apt-mirror config mirror ...`
-- used with `proxmox-apt-mirror mirror ...`
- media, consisting of local mirrors and a path where mirrors are synced to
-- configured with `proxmox-apt-mirror config medium ...`
-- used with `proxmox-apt-mirror medium ...`

and one internal one, a `pool` consisting of
- a pool directory containing checksum files (e.g., `sha256/3dc7bc5f82cdcc4ea0f69dd30d5f6bb19e0ccc36f4a79c865eed0e7a370cd5e4`)
- a base directory containing directories and hardlinks to checksum files inside the pool directory

Adding a file consists of first adding the checksum file(s), then linking them
under one or more paths. a garbage collect operation will iterate over all
files in the base directory and remove those which are not (or no longer) a
hardlink to any checksum files, and remove any checksum files which have no
hardlinks outside of the pool checksum file directories.

A default config path of `/etc/proxmox-apt-mirror.cfg` is used, but is
overridable on a per command basis (for example, to allow operation as non-root
user).

Setting up a mirror
===================

First either run the `setup` wizard (`proxmox-apt-mirror setup`), or the
`config mirror add` command. For example, to add a mirror entry for the Debian
Bullseye security repository, the following command can be used:

 proxmox-apt-mirror config mirror add \
  --id debian-bullseye-security \
  --architectures amd64 \
  --architectures all \
  --repository 'deb http://deb.debian.org/debian-security bullseye-security main contrib non-free' \
  --key-path /etc/apt/trusted.gpg.d/debian-archive-bullseye-security-automatic.gpg \
  --sync true \
  --verify true \
  --base-dir /path/to/mirror/dir/debian-bullseye-security \
  --pool-dir /path/to/mirror/dir/debian-bullseye-security/.pool

Syncing a mirror
================

To create the first (and subsequent) snapshots, the following command can be used:

 proxmox-apt-mirror mirror snapshot create --id debian-bullseye-security

Setting up a medium
===================

Either run the `setup` wizard again, or use the `config medium add` command.
For example, to define a new medium containing the
`proxmox-ve-bullseye-no-subscription` and `debian-bullseye` mirrors, run the
following command:

 proxmox-apt-mirror config medium add \
  --id pve-bullseye \
  --mirrors proxmox-ve-bullseye-no-subscription \
  --mirrors debian-bullseye \
  --sync true \
  --verify true \
  --mountpoint /path/where/medium/is/mounted

Syncing a medium
================

To sync the local mirrors to a medium, the following command can be used:

 proxmox-apt-mirror medium sync --id pve-bullseye

Using a medium
==============

After syncing a medium, unmount it and make it accessible on the (offline)
target system. You can now either manually point apt at the synced snapshots,
or run `proxmox-apt-repo setup` to generate a sources.list.d snippet referecing
selected mirrors and snapshots. Don't forget to remove the snippet again after
the upgrade is done.