proxmox-offline-mirror/docs/introduction.rst

Introduction
============

What is Proxmox Offline Mirror?
-------------------------------

This tool consists of two binaries, `proxmox-offline-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-offline-mirror config mirror ...`
-- used with `proxmox-offline-mirror mirror ...`
- media, consisting of local mirrors and a path where mirrors are synced to
-- configured with `proxmox-offline-mirror config medium ...`
-- used with `proxmox-offline-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-offline-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-offline-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-offline-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-offline-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-offline-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-offline-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.


.. _get_help:

Getting Help
------------

.. _get_help_enterprise_support:

Enterprise Support
~~~~~~~~~~~~~~~~~~

Users with a `Proxmox Offline Mirror Basic, Standard or Premium Subscription Plan
<https://www.proxmox.com/en/proxmox-offline-mirror/pricing>`_ have access to the
`Proxmox Customer Portal <https://my.proxmox.com>`_. The customer portal
provides support with guaranteed response times from the Proxmox developers.
For more information or for volume discounts, please contact office@proxmox.com.

Community Support Forum
~~~~~~~~~~~~~~~~~~~~~~~

We always encourage our users to discuss and share their knowledge using the
`Proxmox Community Forum`_. The forum is moderated by the Proxmox support team.
The large user base is spread out all over the world. Needless to say that such
a large forum is a great place to get information.

Mailing Lists
~~~~~~~~~~~~~

Proxmox Offline Mirror is fully open-source and contributions are welcome! Here
is the primary communication channel for developers:

:Mailing list for developers: `PVE Development List`_

Bug Tracker
~~~~~~~~~~~

Proxmox runs a public bug tracker at `<https://bugzilla.proxmox.com>`_. If an
issue appears, file your report there. An issue can be a bug, as well as a
request for a new feature or enhancement. The bug tracker helps to keep track
of the issue and will send a notification once it has been solved.

License
-------

|pom-copyright|

This software is written by Proxmox Server Solutions GmbH <support@proxmox.com>

Proxmox Backup Server is free and open source software: you can use it,
redistribute it, and/or modify it under the terms of the GNU Affero General
Public License as published by the Free Software Foundation, either version 3
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but
``WITHOUT ANY WARRANTY``; without even the implied warranty of
``MERCHANTABILITY`` or ``FITNESS FOR A PARTICULAR PURPOSE``.  See the GNU
Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see AGPL3_.