From cee53b34df80be4b5d0293df1c7303a51792dfd5 Mon Sep 17 00:00:00 2001 From: Christian Ebner Date: Thu, 20 Feb 2020 18:55:29 +0100 Subject: [PATCH] docs: add documentation for pxar Signed-off-by: Christian Ebner --- docs/administration-guide.rst | 1 + docs/pxar/description.rst | 145 +++++++++++++++++++++++++++++++++- 2 files changed, 144 insertions(+), 2 deletions(-) diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst index da5404ba..ab981460 100644 --- a/docs/administration-guide.rst +++ b/docs/administration-guide.rst @@ -215,6 +215,7 @@ Environment Variables certificate (only used if the system CA certificates cannot validate the certificate). +.. _creating-backups: Creating Backups ~~~~~~~~~~~~~~~~ diff --git a/docs/pxar/description.rst b/docs/pxar/description.rst index 34872663..6d03ffde 100644 --- a/docs/pxar/description.rst +++ b/docs/pxar/description.rst @@ -1,4 +1,145 @@ -This is just a test. +Description +^^^^^^^^^^^ -.. NOTE:: No further info. +``pxar`` is a command line utility used to create and manipulate archives in the +:ref:`pxar-format`. +It is inspired by `casync file archive format +`_, +which has a similar use-case. +The ``.pxar`` format is adapted to fulfill the specific needs of the proxmox +backup server, for example efficient storage of hardlinks. +The format is designed to reduce storage space needed on the server by achieving +high de-duplication. + +Creating an Archive +^^^^^^^^^^^^^^^^^^^ + +Run the following command to create an archive of a folder named ``source``: + +.. code-block:: console + + # pxar create archive.pxar source + +This will create a new archive called ``archive.pxar`` from the contents of the +``source`` folder. + +.. NOTE:: ``pxar`` will not overwrite any existing archives. If an archive with + the same name is already present in the target folder, the creation will + fail. + +By default, ``pxar`` will skip certain mountpoints and not follow device +boundaries. This design decision is based on the primary use case of creating +archives for backups, where it makes no sense to store the content of certain +temporary or system specific files. +In order to alter this behavior and follow device boundaries, use the +``--all-file-systems`` flag. + +It is possible to exclude certain files and/or folders from the archive by +passing glob match patterns as additional parameters. Whenever a file is matched +by one of the patterns, you will get a warning saying that this file is skipped +and therefore not included in the archive. + +For example, you can exclude all files ending in ``.txt`` from the archive +by running: + +.. code-block:: console + + # pxar create archive.pxar source '**/*.txt' + +Be aware that the shell itself will try to expand all of the glob patterns before +invoking ``pxar``. +In order to avoid this, all globs have to be quoted correctly. + +It is also possible to pass a list of match pattern to fulfill more complex +file exclusion/inclusion behavior, although it is recommended to use the +``.pxarexclude`` files instead for such cases. + +For example you might want to exclude all ``.txt`` files except for a specific +one from the archive. This is achieved via the negated match pattern, prefixed +by ``!``. +All the glob pattern are relative to the ``source`` directory. + +.. code-block:: console + + # pxar create archive.pxar source '**/*.txt' '!/folder/file.txt' + +.. NOTE:: The order of the glob match patterns matters as later ones win over + previous ones. Permutations of the same patterns lead to different results. + +``pxar`` will store the list of glob match patterns passed as parameters via the +command line in a file called ``.pxarexclude-cli`` and store it at the root of +the archive. +If a file with this name is already present in the source folder during archive +creation, this file is not included in the archive and the file containing the +new patterns is added to the archive instead, the original file is not altered. + +A more convenient and persistent way to exclude files from the archive is by +placing the glob match patterns in ``.pxarexclude`` files. +It is possible to create and place these files in any directory of the filesystem +tree. +These files must contain one pattern per line, again later patterns win over +previous ones. +The patterns control file exclusion of files present within the given directory +or further below it in the tree. +The behaviour is the same as described in :ref:`creating-backups`. + +Extracting an Archive +^^^^^^^^^^^^^^^^^^^^^ + +An existing archive ``archive.pxar`` is extracted to a ``target`` directory +with the following command: + +.. code-block:: console + + # pxar extract archive.pxar --target target + +If no target is provided, the content of the archive is extracted to the current +working directory. + +In order to restore only part of an archive or single files and/or folders, +it is possible to pass the corresponding glob match patterns as additional +parameters or use the patterns stored in a file: + +.. code-block:: console + + # pxar extract etc.pxar '**/*.conf' --target /restore/target/etc + +The above example restores all ``.conf`` files encountered in any of the +sub-folders in the archive ``etc.pxar`` to the target ``/restore/target/etc``. +A path to the file containing match patterns can be specified using the +``--files-from`` parameter. + +List the Content of an Archive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To display the files and directories contained in an archive ``archive.pxar``, +run the following command: + +.. code-block:: console + + # pxar list archive.pxar + +This displays the full path of each file or directory with respect to the +archives root. + +Mounting an Archive +^^^^^^^^^^^^^^^^^^^ + +``pxar`` allows you to mount and inspect the contents of an archive via _`FUSE`. +In order to mount an archive named ``archive.pxar`` to the mountpoint ``mnt``, +run the command: + +.. code-block:: console + + # pxar mount archive.pxar /mnt + +Once the archive is mounted, you can access its content under the given +mountpoint. + +.. code-block:: console + + # cd /mnt + # ls + bin dev home lib32 libx32 media opt root sbin sys usr + boot etc lib lib64 lost+found mnt proc run srv tmp var