]>
Commit | Line | Data |
---|---|---|
7ccbce03 | 1 | ``pxar`` is a command line utility for creating and manipulating archives in the |
cee53b34 CE |
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>`_, | |
4f3db187 AL |
5 | which caters to a similar use-case. |
6 | The ``.pxar`` format is adapted to fulfill the specific needs of the Proxmox | |
7ccbce03 DW |
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. | |
cee53b34 CE |
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 | ||
02f82148 | 18 | # pxar create archive.pxar /path/to/source |
cee53b34 | 19 | |
4f3db187 | 20 | This will create a new archive called ``archive.pxar`` with the contents of the |
cee53b34 CE |
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 | ||
7ccbce03 | 27 | By default, ``pxar`` will skip certain mount points and will not follow device |
cee53b34 | 28 | boundaries. This design decision is based on the primary use case of creating |
7ccbce03 DW |
29 | archives for backups. It makes sense to ignore the contents of certain |
30 | temporary or system specific files in a backup. | |
4f3db187 | 31 | To alter this behavior and follow device boundaries, use the |
cee53b34 CE |
32 | ``--all-file-systems`` flag. |
33 | ||
34 | It is possible to exclude certain files and/or folders from the archive by | |
02f82148 | 35 | passing the ``--exclude`` parameter with ``gitignore``\-style match patterns. |
cee53b34 CE |
36 | |
37 | For example, you can exclude all files ending in ``.txt`` from the archive | |
38 | by running: | |
39 | ||
40 | .. code-block:: console | |
41 | ||
02f82148 | 42 | # pxar create archive.pxar /path/to/source --exclude '**/*.txt' |
cee53b34 | 43 | |
7ccbce03 DW |
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. | |
04e24b14 | 46 | |
02f82148 DW |
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 | |
7ccbce03 | 49 | file inclusion/exclusion behavior. However, it is recommended to use |
cee53b34 CE |
50 | ``.pxarexclude`` files instead for such cases. |
51 | ||
7ccbce03 DW |
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. | |
cee53b34 CE |
56 | |
57 | .. code-block:: console | |
58 | ||
02f82148 | 59 | # pxar create archive.pxar /path/to/source --exclude '**/*.txt' --exclude '!/folder/file.txt' |
cee53b34 | 60 | |
7ccbce03 DW |
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. | |
cee53b34 CE |
63 | |
64 | ``pxar`` will store the list of glob match patterns passed as parameters via the | |
7ccbce03 | 65 | command line, in a file called ``.pxarexclude-cli``, at the root of the archive. |
cee53b34 | 66 | If a file with this name is already present in the source folder during archive |
7ccbce03 DW |
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. | |
cee53b34 CE |
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. | |
7ccbce03 DW |
74 | These files must contain one pattern per line, and later patterns override |
75 | earlier ones. | |
4f3db187 | 76 | The patterns control file exclusions of files present within the given directory |
cee53b34 | 77 | or further below it in the tree. |
a98e2287 | 78 | The behavior is the same as described in :ref:`client_creating_backups`. |
cee53b34 CE |
79 | |
80 | Extracting an Archive | |
81 | ^^^^^^^^^^^^^^^^^^^^^ | |
82 | ||
4cda7603 | 83 | An existing archive, ``archive.pxar``, is extracted to a ``target`` directory |
cee53b34 CE |
84 | with the following command: |
85 | ||
86 | .. code-block:: console | |
87 | ||
4cda7603 | 88 | # pxar extract archive.pxar /path/to/target |
cee53b34 | 89 | |
7ccbce03 | 90 | If no target is provided, the contents of the archive is extracted to the current |
cee53b34 CE |
91 | working directory. |
92 | ||
4cda7603 | 93 | In order to restore only parts of an archive, single files, and/or folders, |
cee53b34 | 94 | it is possible to pass the corresponding glob match patterns as additional |
4cda7603 | 95 | parameters or to use the patterns stored in a file: |
cee53b34 CE |
96 | |
97 | .. code-block:: console | |
98 | ||
4cda7603 | 99 | # pxar extract etc.pxar /restore/target/etc --pattern '**/*.conf' |
cee53b34 CE |
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 | ||
4f3db187 AL |
106 | List the Contents of an Archive |
107 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
cee53b34 CE |
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 | |
7ccbce03 | 117 | archive's root. |
cee53b34 CE |
118 | |
119 | Mounting an Archive | |
120 | ^^^^^^^^^^^^^^^^^^^ | |
121 | ||
122 | ``pxar`` allows you to mount and inspect the contents of an archive via _`FUSE`. | |
7ccbce03 | 123 | In order to mount an archive named ``archive.pxar`` to the mount point ``/mnt``, |
cee53b34 CE |
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 | |
7ccbce03 | 131 | mount point. |
cee53b34 CE |
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 | |
e4a5ab8d | 139 |