docs/pxar/description.rst

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