1.. 2 Normally, there are no heading levels assigned to certain characters as the structure is 3 determined from the succession of headings. However, this convention is used in Python’s 4 Style Guide for documenting which you may follow: 5 6 # with overline, for parts 7 * for chapters 8 = for sections 9 - for subsections 10 ^ for subsubsections 11 " for paragraphs 12 13############ 14Installation 15############ 16 17Packages 18******** 19 20Note that if at any point the package you’re trying to use is outdated, you 21always have the option to use an official binary from the restic project. 22 23These are up to date binaries, built in a reproducible and verifiable way, that 24you can download and run without having to do additional installation work. 25 26Please see the :ref:`official_binaries` section below for various downloads. 27Official binaries can be updated in place by using the ``restic self-update`` 28command. 29 30Alpine Linux 31============ 32 33On `Alpine Linux <https://www.alpinelinux.org>`__ you can install the ``restic`` 34package from the official community repos, e.g. using ``apk``: 35 36.. code-block:: console 37 38 $ apk add restic 39 40Arch Linux 41========== 42 43On `Arch Linux <https://www.archlinux.org/>`__, there is a package called ``restic`` 44installed from the official community repos, e.g. with ``pacman -S``: 45 46.. code-block:: console 47 48 $ pacman -S restic 49 50Debian 51====== 52 53On Debian, there's a package called ``restic`` which can be 54installed from the official repos, e.g. with ``apt-get``: 55 56.. code-block:: console 57 58 $ apt-get install restic 59 60 61Fedora 62====== 63 64restic can be installed using ``dnf``: 65 66.. code-block:: console 67 68 $ dnf install restic 69 70If you used restic from copr previously, remove the copr repo as follows to 71avoid any conflicts: 72 73.. code-block:: console 74 75 $ dnf copr remove copart/restic 76 77macOS 78===== 79 80If you are using macOS, you can install restic using the 81`homebrew <https://brew.sh/>`__ package manager: 82 83.. code-block:: console 84 85 $ brew install restic 86 87You may also install it using `MacPorts <https://www.macports.org/>`__: 88 89.. code-block:: console 90 91 $ sudo port install restic 92 93Nix & NixOS 94=========== 95 96If you are using `Nix <https://nixos.org/nix/>`__ or `NixOS <https://nixos.org/>`__ 97there is a package available named ``restic``. 98It can be installed using ``nix-env``: 99 100.. code-block:: console 101 102 $ nix-env --install restic 103 104OpenBSD 105======= 106 107On OpenBSD 6.3 and greater, you can install restic using ``pkg_add``: 108 109.. code-block:: console 110 111 # pkg_add restic 112 113FreeBSD 114======= 115 116On FreeBSD (11 and probably later versions), you can install restic using ``pkg install``: 117 118.. code-block:: console 119 120 # pkg install restic 121 122openSUSE 123======== 124 125On openSUSE (leap 15.0 and greater, and tumbleweed), you can install restic using the ``zypper`` package manager: 126 127.. code-block:: console 128 129 # zypper install restic 130 131RHEL & CentOS 132============= 133 134restic can be installed via copr repository, for RHEL7/CentOS you can try the following: 135 136.. code-block:: console 137 138 $ yum install yum-plugin-copr 139 $ yum copr enable copart/restic 140 $ yum install restic 141 142If that doesn't work, you can try adding the repository directly, for CentOS6 use: 143 144.. code-block:: console 145 146 $ yum-config-manager --add-repo https://copr.fedorainfracloud.org/coprs/copart/restic/repo/epel-6/copart-restic-epel-6.repo 147 148For CentOS7 use: 149 150.. code-block:: console 151 152 $ yum-config-manager --add-repo https://copr.fedorainfracloud.org/coprs/copart/restic/repo/epel-7/copart-restic-epel-7.repo 153 154Solus 155===== 156 157restic can be installed from the official repo of Solus via the ``eopkg`` package manager: 158 159.. code-block:: console 160 161 $ eopkg install restic 162 163Windows 164======= 165 166restic can be installed using `Scoop <https://scoop.sh/>`__: 167 168.. code-block:: console 169 170 scoop install restic 171 172Using this installation method, ``restic.exe`` will automatically be available 173in the ``PATH``. It can be called from cmd.exe or PowerShell by typing ``restic``. 174 175 176.. _official_binaries: 177 178Official Binaries 179***************** 180 181Stable Releases 182=============== 183 184You can download the latest stable release versions of restic from the `restic 185release page <https://github.com/restic/restic/releases/latest>`__. These builds 186are considered stable and releases are made regularly in a controlled manner. 187 188There's both pre-compiled binaries for different platforms as well as the source 189code available for download. Just download and run the one matching your system. 190 191The official binaries can be updated in place using the ``restic self-update`` 192command (needs restic 0.9.3 or later): 193 194.. code-block:: console 195 196 $ restic version 197 restic 0.9.3 compiled with go1.11.2 on linux/amd64 198 199 $ restic self-update 200 find latest release of restic at GitHub 201 latest version is 0.9.4 202 download file SHA256SUMS 203 download SHA256SUMS 204 download file SHA256SUMS 205 download SHA256SUMS.asc 206 GPG signature verification succeeded 207 download restic_0.9.4_linux_amd64.bz2 208 downloaded restic_0.9.4_linux_amd64.bz2 209 saved 12115904 bytes in ./restic 210 successfully updated restic to version 0.9.4 211 212 $ restic version 213 restic 0.9.4 compiled with go1.12.1 on linux/amd64 214 215The ``self-update`` command uses the GPG signature on the files uploaded to 216GitHub to verify their authenticity. No external programs are necessary. 217 218.. note:: Please be aware that the user executing the ``restic self-update`` 219 command must have the permission to replace the restic binary. 220 If you want to save the downloaded restic binary into a different file, pass 221 the file name via the option ``--output``. 222 223Unstable Builds 224=============== 225 226Another option is to use the latest builds for the master branch, available on 227the `restic beta download site 228<https://beta.restic.net/?sort=time&order=desc>`__. These too are pre-compiled 229and ready to run, and a new version is built every time a push is made to the 230master branch. 231 232Windows 233======= 234 235On Windows, put the `restic.exe` binary into `%SystemRoot%\\System32` to use restic 236in scripts without the need for absolute paths to the binary. This requires 237administrator rights. 238 239Docker Container 240**************** 241 242We're maintaining a bare docker container with just a few files and the restic 243binary, you can get it with `docker pull` like this: 244 245.. code-block:: console 246 247 $ docker pull restic/restic 248 249.. note:: 250 | Another docker container which offers more configuration options is 251 | available as a contribution (Thank you!). You can find it at 252 | https://github.com/Lobaro/restic-backup-docker 253 254From Source 255*********** 256 257restic is written in the Go programming language and you need at least 258Go version 1.13. Building restic may also work with older versions of Go, 259but that's not supported. See the `Getting 260started <https://golang.org/doc/install>`__ guide of the Go project for 261instructions how to install Go. 262 263In order to build restic from source, execute the following steps: 264 265.. code-block:: console 266 267 $ git clone https://github.com/restic/restic 268 [...] 269 270 $ cd restic 271 272 $ go run build.go 273 274You can easily cross-compile restic for all supported platforms, just 275supply the target OS and platform via the command-line options like this 276(for Windows and FreeBSD respectively): 277 278.. code-block:: console 279 280 $ go run build.go --goos windows --goarch amd64 281 282 $ go run build.go --goos freebsd --goarch 386 283 284 $ go run build.go --goos linux --goarch arm --goarm 6 285 286The resulting binary is statically linked and does not require any 287libraries. 288 289At the moment, the only tested compiler for restic is the official Go 290compiler. Building restic with gccgo may work, but is not supported. 291 292Autocompletion 293************** 294 295Restic can write out man pages and bash/fish/zsh compatible autocompletion scripts: 296 297.. code-block:: console 298 299 $ ./restic generate --help 300 301 The "generate" command writes automatically generated files (like the man pages 302 and the auto-completion files for bash, fish and zsh). 303 304 Usage: 305 restic generate [flags] [command] 306 307 Flags: 308 --bash-completion file write bash completion file 309 --fish-completion file write fish completion file 310 -h, --help help for generate 311 --man directory write man pages to directory 312 --zsh-completion file write zsh completion file 313 314Example for using sudo to write a bash completion script directly to the system-wide location: 315 316.. code-block:: console 317 318 $ sudo ./restic generate --bash-completion /etc/bash_completion.d/restic 319 writing bash completion file to /etc/bash_completion.d/restic 320 321.. note:: The path for the ``--bash-completion`` option may vary depending on 322 the operating system used, e.g. ``/usr/share/bash-completion/completions/restic`` 323 in Debian and derivatives. Please look up the correct path in the appropriate 324 documentation. 325