docs/pxar/description.rst

   1 ``pxar`` is a command line utility for creating and manipulating archives in the
   2 :ref:`pxar-format`.
   3 It is inspired by `casync file archive format
   4 <http://0pointer.net/blog/casync-a-tool-for-distributing-file-system-images.html>`_,
   5 which caters to a similar use-case.
   6 The ``.pxar`` format is adapted to fulfill the specific needs of the Proxmox
   7 Backup Server, for example, efficient storage of hard links.
   8 The format is designed to reduce the required storage on the server by
   9 achieving a high level of deduplication.
  10
  11 Creating an Archive
  12 ^^^^^^^^^^^^^^^^^^^
  13
  14 Run the following command to create an archive of a folder named ``source``:
  15
  16 .. code-block:: console
  17
  18     # pxar create archive.pxar /path/to/source
  19
  20 This will create a new archive called ``archive.pxar`` with the contents of the
  21 ``source`` folder.
  22
  23 .. NOTE:: ``pxar`` will not overwrite any existing archives. If an archive with
  24     the same name is already present in the target folder, the creation will
  25     fail.
  26
  27 By default, ``pxar`` will skip certain mount points and will not follow device
  28 boundaries. This design decision is based on the primary use case of creating
  29 archives for backups. It makes sense to ignore the contents of certain
  30 temporary or system specific files in a backup.
  31 To alter this behavior and follow device boundaries, use the
  32 ``--all-file-systems`` flag.
  33
  34 It is possible to exclude certain files and/or folders from the archive by
  35 passing the ``--exclude`` parameter with ``gitignore``\-style match patterns.
  36
  37 For example, you can exclude all files ending in ``.txt`` from the archive
  38 by running:
  39
  40 .. code-block:: console
  41
  42     # pxar create archive.pxar /path/to/source --exclude '**/*.txt'
  43
  44 Be aware that the shell itself will try to expand glob patterns before invoking
  45 ``pxar``. In order to avoid this, all globs have to be quoted correctly.
  46
  47 It is possible to pass the ``--exclude`` parameter multiple times, in order to
  48 match more than one pattern. This allows you to use more complex
  49 file inclusion/exclusion behavior. However, it is recommended to use
  50 ``.pxarexclude`` files instead for such cases.
  51
  52 For example you might want to exclude all ``.txt`` files except a specific
  53 one from the archive. This would be achieved via the negated match pattern,
  54 prefixed by ``!``.  All the glob patterns are relative to the ``source``
  55 directory.
  56
  57 .. code-block:: console
  58
  59     # pxar create archive.pxar /path/to/source --exclude '**/*.txt' --exclude '!/folder/file.txt'
  60
  61 .. NOTE:: The order of the glob match patterns matters, as later ones override
  62    earlier ones. Permutations of the same patterns lead to different results.
  63
  64 ``pxar`` will store the list of glob match patterns passed as parameters via the
  65 command line, in a file called ``.pxarexclude-cli``, at the root of the archive.
  66 If a file with this name is already present in the source folder during archive
  67 creation, this file is not included in the archive, and the file containing the
  68 new patterns is added to the archive instead. The original file is not altered.
  69
  70 A more convenient and persistent way to exclude files from the archive is by
  71 placing the glob match patterns in ``.pxarexclude`` files.
  72 It is possible to create and place these files in any directory of the filesystem
  73 tree.
  74 These files must contain one pattern per line, and later patterns override
  75 earlier ones.
  76 The patterns control file exclusions of files present within the given directory
  77 or further below it in the tree.
  78 The behavior is the same as described in :ref:`client_creating_backups`.
  79
  80 Extracting an Archive
  81 ^^^^^^^^^^^^^^^^^^^^^
  82
  83 An existing archive, ``archive.pxar``, is extracted to a ``target`` directory
  84 with the following command:
  85
  86 .. code-block:: console
  87
  88     # pxar extract archive.pxar /path/to/target
  89
  90 If no target is provided, the contents of the archive is extracted to the current
  91 working directory.
  92
  93 In order to restore only parts of an archive, single files, and/or folders,
  94 it is possible to pass the corresponding glob match patterns as additional
  95 parameters or to use the patterns stored in a file:
  96
  97 .. code-block:: console
  98
  99     # pxar extract etc.pxar /restore/target/etc --pattern '**/*.conf'
 100
 101 The above example restores all ``.conf`` files encountered in any of the
 102 sub-folders in the archive ``etc.pxar`` to the target ``/restore/target/etc``.
 103 A path to the file containing match patterns can be specified using the
 104 ``--files-from`` parameter.
 105
 106 List the Contents of an Archive
 107 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 108
 109 To display the files and directories contained in an archive ``archive.pxar``,
 110 run the following command:
 111
 112 .. code-block:: console
 113
 114     # pxar list archive.pxar
 115
 116 This displays the full path of each file or directory with respect to the
 117 archive's root.
 118
 119 Mounting an Archive
 120 ^^^^^^^^^^^^^^^^^^^
 121
 122 ``pxar`` allows you to mount and inspect the contents of an archive via _`FUSE`.
 123 In order to mount an archive named ``archive.pxar`` to the mount point ``/mnt``,
 124 run the command:
 125
 126 .. code-block:: console
 127
 128     # pxar mount archive.pxar /mnt
 129
 130 Once the archive is mounted, you can access its content under the given
 131 mount point.
 132
 133 .. code-block:: console
 134
 135     # cd /mnt
 136     # ls
 137     bin   dev  home  lib32  libx32      media  opt   root  sbin  sys  usr
 138     boot  etc  lib   lib64  lost+found  mnt    proc  run   srv   tmp  var
 139