.. include:: global.rst.inc .. highlight:: bash .. _installation: Installation ============ There are different ways to install |project_name|: - :ref:`distribution-package` - easy and fast if a package is available from your distribution. - :ref:`pyinstaller-binary` - easy and fast, we provide a ready-to-use binary file that comes bundled with all dependencies. - :ref:`source-install`, either: - :ref:`pip-installation` - installing a source package with pip needs more installation steps and requires all dependencies with development headers and a compiler. - :ref:`git-installation` - for developers and power users who want to have the latest code or use revision control (each release is tagged). .. _distribution-package: Distribution Package -------------------- Some distributions might offer a ready-to-use ``borgbackup`` package which can be installed with the package manager. As |project_name| is still a young project, such a package might be not available for your system yet. ============ ============================================= ======= Distribution Source Command ============ ============================================= ======= Arch Linux `[community]`_ ``pacman -S borg`` Debian `stretch`_, `unstable/sid`_ ``apt install borgbackup`` NetBSD `pkgsrc`_ ``pkg_add py-borgbackup`` NixOS `.nix file`_ N/A OS X `Brew cask`_ ``brew cask install borgbackup`` Ubuntu `Xenial 16.04`_, `Wily 15.10 (backport PPA)`_ ``apt install borgbackup`` Ubuntu `Trusty 14.04 (backport PPA)`_ ``apt install borgbackup`` ============ ============================================= ======= .. _[community]: https://www.archlinux.org/packages/?name=borg .. _stretch: https://packages.debian.org/stretch/borgbackup .. _unstable/sid: https://packages.debian.org/sid/borgbackup .. _pkgsrc: http://pkgsrc.se/sysutils/py-borgbackup .. _Xenial 16.04: https://launchpad.net/ubuntu/xenial/+source/borgbackup .. _Wily 15.10 (backport PPA): https://launchpad.net/~costamagnagianfranco/+archive/ubuntu/borgbackup .. _Trusty 14.04 (backport PPA): https://launchpad.net/~costamagnagianfranco/+archive/ubuntu/borgbackup .. _.nix file: https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/backup/borg/default.nix .. _Brew cask: http://caskroom.io/ Please ask package maintainers to build a package or, if you can package / submit it yourself, please help us with that! See :issue:`105` on github to followup on packaging efforts. If a package is available, it might be interesting to check its version and compare that to our latest release and review the :doc:`changes`. .. _pyinstaller-binary: Standalone Binary ----------------- |project_name| binaries (generated with `pyinstaller`_) are available on the releases_ page for the following platforms: * **Linux**: glibc >= 2.13 (ok for most supported Linux releases). Maybe older glibc versions also work, if they are compatible to 2.13. * **Mac OS X**: 10.10 (does not work with older OS X releases) * **FreeBSD**: 10.2 (unknown whether it works for older releases) To install such a binary, just drop it into a directory in your ``PATH``, make borg readable and executable for its users and then you can run ``borg``:: sudo cp borg-linux64 /usr/local/bin/borg sudo chown root:root /usr/local/bin/borg sudo chmod 755 /usr/local/bin/borg Note that the binary uses /tmp to unpack |project_name| with all dependencies. It will fail if /tmp has not enough free space or is mounted with the ``noexec`` option. You can change the temporary directory by setting the ``TEMP`` environment variable before running |project_name|. If a new version is released, you will have to manually download it and replace the old version using the same steps as shown above. .. _pyinstaller: http://www.pyinstaller.org .. _releases: https://github.com/borgbackup/borg/releases .. _platforms: Features & platforms -------------------- Besides regular file and directory structures, |project_name| can preserve * Hardlinks (considering all files in the same archive) * Symlinks (stored as symlink, the symlink is not followed) * Special files: * Character and block device files (restored via mknod) * FIFOs ("named pipes") * Special file *contents* can be backed up in ``--read-special`` mode. By default the metadata to create them with mknod(2), mkfifo(2) etc. is stored. * Timestamps in nanosecond precision: mtime, atime, ctime * Permissions: * IDs of owning user and owning group * Names of owning user and owning group (if the IDs can be resolved) * Unix Mode/Permissions (u/g/o permissions, suid, sgid, sticky) On some platforms additional features are supported: .. Yes/No's are grouped by reason/mechanism/reference. +------------------+----------+-----------+------------+ | Platform | ACLs | xattr | Flags | | | [#acls]_ | [#xattr]_ | [#flags]_ | +==================+==========+===========+============+ | Linux x86 | Yes | Yes | No | +------------------+ | | | | Linux PowerPC | | | | +------------------+ | | | | Linux ARM | | | | +------------------+----------+-----------+------------+ | Mac OS X | Yes | Yes | Yes (all) | +------------------+----------+-----------+ | | FreeBSD | Yes | Yes | | +------------------+----------+-----------+ | | OpenBSD | n/a | n/a | | +------------------+----------+-----------+ | | NetBSD | n/a | No [2]_ | | +------------------+----------+-----------+------------+ | Solaris 11 | No [3]_ | n/a | +------------------+ | | | OpenIndiana | | | +------------------+----------+-----------+------------+ | Windows (cygwin) | No [4]_ | No | No | +------------------+----------+-----------+------------+ Some Distributions (e.g. Debian) run additional tests after each release, these are not reflected here. Other Unix-like operating systems may work as well, but have not been tested at all. Note that most of the platform-dependent features also depend on the file system. For example, ntfs-3g on Linux isn't able to convey NTFS ACLs. .. [2] Feature request :issue:`1332` .. [3] Feature request :issue:`1337` .. [4] Cygwin tries to map NTFS ACLs to permissions with varying degress of success. .. [#acls] The native access control list mechanism of the OS. This normally limits access to non-native ACLs. For example, NTFS ACLs aren't completely accessible on Linux with ntfs-3g. .. [#xattr] extended attributes; key-value pairs attached to a file, mainly used by the OS. This includes resource forks on Mac OS X. .. [#flags] aka *BSD flags*. .. _source-install: From Source ----------- Dependencies ~~~~~~~~~~~~ To install |project_name| from a source package (including pip), you have to install the following dependencies first: * `Python 3`_ >= 3.4.0, plus development headers. Even though Python 3 is not the default Python version on most systems, it is usually available as an optional install. * OpenSSL_ >= 1.0.0, plus development headers. * libacl_ (that pulls in libattr_ also), both plus development headers. * liblz4_, plus development headers. * some Python dependencies, pip will automatically install them for you * optionally, the llfuse_ Python package is required if you wish to mount an archive as a FUSE filesystem. See setup.py about the version requirements. If you have troubles finding the right package names, have a look at the distribution specific sections below and also at the Vagrantfile in our repo. In the following, the steps needed to install the dependencies are listed for a selection of platforms. If your distribution is not covered by these instructions, try to use your package manager to install the dependencies. On FreeBSD, you may need to get a recent enough OpenSSL version from FreeBSD ports. After you have installed the dependencies, you can proceed with steps outlined under :ref:`pip-installation`. Debian / Ubuntu +++++++++++++++ Install the dependencies with development headers:: sudo apt-get install python3 python3-dev python3-pip python-virtualenv \ libssl-dev openssl \ libacl1-dev libacl1 \ liblz4-dev liblz4-1 \ build-essential sudo apt-get install libfuse-dev fuse pkg-config # optional, for FUSE support In case you get complaints about permission denied on ``/etc/fuse.conf``: on Ubuntu this means your user is not in the ``fuse`` group. Add yourself to that group, log out and log in again. Fedora / Korora +++++++++++++++ Install the dependencies with development headers:: sudo dnf install python3 python3-devel python3-pip python3-virtualenv sudo dnf install openssl-devel openssl sudo dnf install libacl-devel libacl sudo dnf install lz4-devel sudo dnf install gcc gcc-c++ sudo dnf install fuse-devel fuse pkgconfig # optional, for FUSE support Mac OS X ++++++++ Assuming you have installed homebrew_, the following steps will install all the dependencies:: brew install python3 lz4 openssl brew install pkg-config # optional, for FUSE support pip3 install virtualenv For FUSE support to mount the backup archives, you need at least version 3.0 of FUSE for OS X, which is available as a pre-release_. .. _pre-release: https://github.com/osxfuse/osxfuse/releases FreeBSD ++++++++ Listed below are packages you will need to install |project_name|, its dependencies, and commands to make fuse work for using the mount command. :: pkg install -y python3 openssl liblz4 fusefs-libs pkgconf pkg install -y git python3.4 -m ensurepip # to install pip for Python3 To use the mount command: echo 'fuse_load="YES"' >> /boot/loader.conf echo 'vfs.usermount=1' >> /etc/sysctl.conf kldload fuse sysctl vfs.usermount=1 Cygwin ++++++ .. note:: Running under Cygwin is experimental and has only been tested with Cygwin (x86-64) v2.5.2. Use the Cygwin installer to install the dependencies:: python3 python3-setuptools binutils gcc-g++ libopenssl openssl-devel liblz4_1 liblz4-devel git make openssh You can then install ``pip`` and ``virtualenv``:: easy_install-3.4 pip pip install virtualenv .. _pip-installation: Using pip ~~~~~~~~~ Virtualenv_ can be used to build and install |project_name| without affecting the system Python or requiring root access. Using a virtual environment is optional, but recommended except for the most simple use cases. .. note:: If you install into a virtual environment, you need to **activate** it first (``source borg-env/bin/activate``), before running ``borg``. Alternatively, symlink ``borg-env/bin/borg`` into some directory that is in your ``PATH`` so you can just run ``borg``. This will use ``pip`` to install the latest release from PyPi:: virtualenv --python=python3 borg-env source borg-env/bin/activate # install Borg + Python dependencies into virtualenv pip install borgbackup # or alternatively (if you want FUSE support): pip install borgbackup[fuse] To upgrade |project_name| to a new version later, run the following after activating your virtual environment:: pip install -U borgbackup # or ... borgbackup[fuse] .. _git-installation: Using git ~~~~~~~~~ This uses latest, unreleased development code from git. While we try not to break master, there are no guarantees on anything. :: # get borg from github git clone https://github.com/borgbackup/borg.git virtualenv --python=python3 borg-env source borg-env/bin/activate # always before using! # install borg + dependencies into virtualenv pip install sphinx # optional, to build the docs cd borg pip install -r requirements.d/development.txt pip install -r requirements.d/fuse.txt # optional, for FUSE support pip install -e . # in-place editable mode # optional: run all the tests, on all supported Python versions # requires fakeroot, available through your package manager fakeroot -u tox .. note:: As a developer or power user, you always want to use a virtual environment.