PXAR(1)

NAME
pxar - Proxmox File Archive CLI Tool

SYNOPSIS

pxar create <archive> <source> [OPTIONS]

Create a new .pxar archive.

<archive> (<string>)
    Archive name.

<source> (<string>)
    Source directory.

    Optional parameters:

--all-file-systems <boolean> (default=false)
    Include mounted sudirs.

--entries-max <integer> (0 - 9223372036854775807) (default=1048576)
    Max number of entries loaded at once into memory

--exclude <string>
    List of paths or pattern matching files to exclude. Can be specified more than once.

--no-acls <boolean> (default=false)
    Ignore access control list entries.

--no-device-nodes <boolean> (default=false)
    Ignore device nodes.

--no-fcaps <boolean> (default=false)
    Ignore file capabilities.

--no-fifos <boolean> (default=false)
    Ignore fifos.

--no-sockets <boolean> (default=false)
    Ignore sockets.

--no-xattrs <boolean> (default=false)
    Ignore extended file attributes.

--payload-output <string>
    'ppxar' payload output data file to create split archive.

    ----

    pxar extract <archive> [<target>] [OPTIONS]

    Extract an archive.

<archive> (<string>)
    Archive name.

<target> (<string>)
    Target directory

    Optional parameters:

--allow-existing-dirs <boolean> (default=false)
    Allows directories to already exist on restore.

--files-from <string>
    File containing match pattern for files to restore.

--no-acls <boolean> (default=false)
    Ignore access control list entries.

--no-device-nodes <boolean> (default=false)
    Ignore device nodes.

--no-fcaps <boolean> (default=false)
    Ignore file capabilities.

--no-fifos <boolean> (default=false)
    Ignore fifos.

--no-sockets <boolean> (default=false)
    Ignore sockets.

--no-xattrs <boolean> (default=false)
    Ignore extended file attributes.

--overwrite <boolean> (default=false)
    overwrite already existing files, symlinks and hardlinks

--overwrite-files <boolean> (default=false)
    overwrite already existing files

--overwrite-hardlinks <boolean> (default=false)
    overwrite already existing entries by archives hardlink

--overwrite-symlinks <boolean> (default=false)
    overwrite already existing entries by archives symlink

--pattern <string>
    Path or match pattern to limit files that get restored. Can be specified more than once.

--payload-input <string>
    'ppxar' payload input data file to restore split archive.

--prelude-target <string>
    Path to restore pxar archive prelude to.

--strict <boolean> (default=false)
    Stop on errors. Otherwise most errors will simply warn.

    ----

    pxar help [{<command>}] [OPTIONS]

    Get help about specified command (or sub-command).

<command> (<string>)
    Command. This may be a list in order to specify nested sub-commands. Can be specified more than once.

    Optional parameters:

--verbose <boolean>
    Verbose help.

    ----

    pxar list <archive> [OPTIONS]

    List the contents of an archive.

<archive> (<string>)
    Archive name.

    Optional parameters:

--payload-input <string>
    'ppxar' payload input data file for split archive.

    ----

    pxar mount <archive> <mountpoint> [OPTIONS]

    Mount the archive to the provided mountpoint via FUSE.

<archive> (<string>)
    Archive name.

<mountpoint> (<string>)
    Mountpoint for the file system.

    Optional parameters:

--payload-input <string>
    'ppxar' payload input data file to restore split archive.

--verbose <boolean> (default=false)
    Verbose output, running in the foreground (for debugging).

DESCRIPTION

pxar is a command-line utility for creating and manipulating archives in the Proxmox File Archive Format (.pxar). It is inspired by casync file archive format, which caters to a similar use-case. The .pxar format is adapted to fulfill the specific needs of the Proxmox Backup Server, for example, efficient storage of hard links. The format is designed to reduce the required storage on the server by achieving a high level of deduplication.

  Creating an Archive

Run the following command to create an archive of a folder named source:

    # pxar create archive.pxar /path/to/source

This will create a new archive called archive.pxar with 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 mount points and will not follow device boundaries. This design decision is based on the primary use case of creating archives for backups. It makes sense to ignore the contents of certain temporary or system specific files in a backup. 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 the --exclude parameter with gitignore-style match patterns.

For example, you can exclude all files ending in .txt from the archive by running:

    # pxar create archive.pxar /path/to/source --exclude '**/*.txt'

Be aware that the shell itself will try to expand glob patterns before invoking pxar. In order to avoid this, all globs have to be quoted correctly.

It is possible to pass the --exclude parameter multiple times, in order to match more than one pattern. This allows you to use more complex file inclusion/exclusion behavior. However, it is recommended to use .pxarexclude files instead for such cases.

For example you might want to exclude all .txt files except a specific one from the archive. This would be achieved via the negated match pattern, prefixed by !. All the glob patterns are relative to the source directory.

    # pxar create archive.pxar /path/to/source --exclude '**/*.txt' --exclude '!/folder/file.txt'

NOTE: The order of the glob match patterns matters, as later ones override earlier 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, 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, and later patterns override earlier ones. The patterns control file exclusions of files present within the given directory or further below it in the tree. The behavior is the same as described in Creating Backups.

  Extracting an Archive

An existing archive, archive.pxar, is extracted to a target directory with the following command:

    # pxar extract archive.pxar /path/to/target

If no target is provided, the contents of the archive is extracted to the current working directory.

In order to restore only parts of an archive, single files, and/or folders, it is possible to pass the corresponding glob match patterns as additional parameters or to use the patterns stored in a file:

    # pxar extract etc.pxar /restore/target/etc --pattern '**/*.conf'

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 Contents of an Archive

To display the files and directories contained in an archive archive.pxar, run the following command:

    # pxar list archive.pxar

This displays the full path of each file or directory with respect to the archive's root.

  Mounting an Archive

pxar allows you to mount and inspect the contents of an archive via . In order to mount an archive named archive.pxar to the mount point /mnt, run the command:

    # pxar mount archive.pxar /mnt

Once the archive is mounted, you can access its content under the given mount point.

    # 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

COPYRIGHT AND DISCLAIMER

Copyright (C) 2019-2025, Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/

AUTHOR
Proxmox Support Team

COPYRIGHT
2019-2025, Proxmox Server Solutions GmbH