docs/introduction.rst

   1 Introduction
   2 ============
   3
   4 What is Proxmox Offline Mirror?
   5 -------------------------------
   6
   7 With the Proxmox Offline Mirror tool, you can manage a local apt mirror for all package updates for
   8 Proxmox and Debian projects. From this local apt mirror you can create an external medium, for
   9 example a USB flash drive or a local network share, to update systems which cannot access the
  10 package repositories directly via the internet.  Such systems might be restricted by policies to
  11 access the public internet or are completely air-gapped.  Finally, you can also manage subscriptions
  12 for such restricted hosts.
  13
  14 This tool consists of two binaries:
  15
  16 ``proxmox-offline-mirror``
  17   The mirror tool to create and manage mirrors and media containing repositories
  18
  19 ``proxmox-apt-repo``
  20   The helper to use the external medium on offline Proxmox VE, Proxmox Mail Gateway or Proxmox
  21   Backup Server systems as well as managing subscriptions on these systems.
  22
  23 Terminology
  24 -----------
  25
  26 There are three basic entity types available for configuration:
  27
  28 *keys*
  29   Subscription keys are either for the mirroring system itself, or for the offline systems.
  30
  31   They are configured with ``proxmox-offline-mirror key ...``
  32
  33 *mirrors*
  34   A mirror consists of the metadata of an upstream repository and a local path where **snapshots**
  35   of the upstream repository are stored.
  36
  37   - configured with ``proxmox-offline-mirror config mirror ...``
  38
  39   - used with ``proxmox-offline-mirror mirror ...``
  40
  41 *media*
  42   A medium consisting of local mirrors and a path where the mirrors are synced to
  43
  44   - configured with ``proxmox-offline-mirror config medium ...``
  45
  46   - used with ``proxmox-offline-mirror medium ...``
  47
  48
  49 Technical Overview
  50 ------------------
  51
  52 Behind the scenes, one or more `pools` consisting of
  53
  54 - a pool directory containing checksum files (e.g., `sha256/3dc7bc5f82cdcc4ea0f69dd30d5f6bb19e0ccc36f4a79c865eed0e7a370cd5e4`)
  55 - a link directory containing directories and hardlinks to the checksum files inside the pool
  56   directory
  57
  58 are used to store the repository contents ("snapshots") of repository mirrors in a space-efficient way.
  59
  60 When adding a file, the following steps are done: first the ckecksum file(s) are added, then they
  61 are linked under one or more paths. A garbage collect operation will iterate over all files in the
  62 link directory and remove those, which are not (or no longer) a hardlink to any checksum files. It
  63 will also remove any checksum files which have no hardlinks outside of the pool's checksum file
  64 directories.
  65
  66 A pool directory can be shared by multiple mirrors in order to deduplicate stored files across the
  67 mirror boundary. For example, it is recommended to have a single pool directory (mirror base directory)
  68 for all mirrors of Proxmox repositories.
  69
  70 The default config path is ``/etc/proxmox-offline-mirror.cfg``, but it can be overriden on a per
  71 command basis (for example, to allow operation as a non-root user). Use the ``--config`` CLI option or
  72 the ``PROXMOX_OFFLINE_MIRROR_CONFIG`` environment variable.
  73
  74
  75 .. _get_help:
  76
  77 Getting Help
  78 ------------
  79
  80 .. _get_help_enterprise_support:
  81
  82 Enterprise Support
  83 ^^^^^^^^^^^^^^^^^^
  84
  85 Users with a `Proxmox Offline Mirror` subscription have access to the `Proxmox Customer Portal
  86 <https://my.proxmox.com>`_ for offline mirroring/key handling related issues, provided the
  87 corresponding offline system has a valid subscription level higher than `Community`. The customer
  88 portal provides support with guaranteed response times from the Proxmox developers.
  89
  90 For more information or for volume discounts, please contact sales@proxmox.com.
  91
  92 Community Support Forum
  93 ^^^^^^^^^^^^^^^^^^^^^^^
  94
  95 We always encourage our users to discuss and share their knowledge using the
  96 `Proxmox Community Forum`_. The forum is moderated by the Proxmox support team.
  97 The large user base is spread out all over the world. Needless to say that such
  98 a large forum is a great place to get information.
  99
 100 Mailing Lists
 101 ^^^^^^^^^^^^^
 102
 103 Proxmox Offline Mirror is fully open-source and contributions are welcome! The Proxmox VE
 104 development mailing list acts as the primary communication channel for offline mirror developers:
 105
 106 :Mailing list for developers: `PVE Development List`_
 107
 108 Bug Tracker
 109 ^^^^^^^^^^^
 110
 111 Proxmox runs a public bug tracker at `<https://bugzilla.proxmox.com>`_. If an
 112 issue appears, file your report there. An issue can be a bug, as well as a
 113 request for a new feature or enhancement. The bug tracker helps to keep track
 114 of the issue and will send a notification once it has been solved.
 115
 116 License
 117 -------
 118
 119 |pom-copyright|
 120
 121 This software is written by Proxmox Server Solutions GmbH <support@proxmox.com>
 122
 123 Proxmox Offline Mirror is free and open source software: you can use it,
 124 redistribute it, and/or modify it under the terms of the GNU Affero General
 125 Public License as published by the Free Software Foundation, either version 3
 126 of the License, or (at your option) any later version.
 127
 128 This program is distributed in the hope that it will be useful, but
 129 ``WITHOUT ANY WARRANTY``; without even the implied warranty of
 130 ``MERCHANTABILITY`` or ``FITNESS FOR A PARTICULAR PURPOSE``.  See the GNU
 131 Affero General Public License for more details.
 132
 133 You should have received a copy of the GNU Affero General Public License
 134 along with this program.  If not, see AGPL3_.