add instructions

Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..7702ae4
--- /dev/null
+++ b/README
@@ -0,0 +1,85 @@
+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.