File manager

File manager - Edit - /usr/share/doc/restic/html/040_backup.html

Back
<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Backing up — restic 0.12.1 documentation</title> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/css/restic.css" type="text/css" /> <link rel="shortcut icon" href="_static/favicon.ico"/> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/doctools.js"></script> <script src="_static/js/theme.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Working with repositories" href="045_working_with_repos.html" /> <link rel="prev" title="Preparing a new repository" href="030_preparing_a_new_repo.html" /> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html" class="icon icon-home"> restic <img src="_static/logo.png" class="logo" alt="Logo"/> </a> <div class="version"> 0.12.1 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="010_introduction.html">Introduction</a></li> <li class="toctree-l1"><a class="reference internal" href="020_installation.html">Installation</a></li> <li class="toctree-l1"><a class="reference internal" href="030_preparing_a_new_repo.html">Preparing a new repository</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Backing up</a><ul> <li class="toctree-l2"><a class="reference internal" href="#file-change-detection">File change detection</a></li> <li class="toctree-l2"><a class="reference internal" href="#excluding-files">Excluding Files</a></li> <li class="toctree-l2"><a class="reference internal" href="#including-files">Including Files</a></li> <li class="toctree-l2"><a class="reference internal" href="#comparing-snapshots">Comparing Snapshots</a></li> <li class="toctree-l2"><a class="reference internal" href="#backing-up-special-items-and-metadata">Backing up special items and metadata</a></li> <li class="toctree-l2"><a class="reference internal" href="#reading-data-from-stdin">Reading data from stdin</a></li> <li class="toctree-l2"><a class="reference internal" href="#tags-for-backup">Tags for backup</a></li> <li class="toctree-l2"><a class="reference internal" href="#space-requirements">Space requirements</a></li> <li class="toctree-l2"><a class="reference internal" href="#environment-variables">Environment Variables</a></li> <li class="toctree-l2"><a class="reference internal" href="#exit-status-codes">Exit status codes</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="045_working_with_repos.html">Working with repositories</a></li> <li class="toctree-l1"><a class="reference internal" href="050_restore.html">Restoring from backup</a></li> <li class="toctree-l1"><a class="reference internal" href="060_forget.html">Removing backup snapshots</a></li> <li class="toctree-l1"><a class="reference internal" href="070_encryption.html">Encryption</a></li> <li class="toctree-l1"><a class="reference internal" href="075_scripting.html">Scripting</a></li> <li class="toctree-l1"><a class="reference internal" href="080_examples.html">Examples</a></li> <li class="toctree-l1"><a class="reference internal" href="090_participating.html">Participating</a></li> <li class="toctree-l1"><a class="reference internal" href="100_references.html">References</a></li> <li class="toctree-l1"><a class="reference internal" href="110_talks.html">Talks</a></li> <li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li> <li class="toctree-l1"><a class="reference internal" href="manual_rest.html">Manual</a></li> <li class="toctree-l1"><a class="reference internal" href="developer_information.html">Developer Information</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">restic</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home"></a> »</li> <li>Backing up</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/040_backup.rst.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="backing-up"> <h1>Backing up<a class="headerlink" href="#backing-up" title="Permalink to this headline">¶</a></h1> <p>Now we’re ready to backup some data. The contents of a directory at a specific point in time is called a “snapshot” in restic. Run the following command and enter the repository password you chose above again:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo --verbose backup ~/work <span class="go">open repository</span> <span class="go">enter password for repository:</span> <span class="go">password is correct</span> <span class="go">lock repository</span> <span class="go">load index files</span> <span class="go">start scan</span> <span class="go">start backup</span> <span class="go">scan finished in 1.837s</span> <span class="go">processed 1.720 GiB in 0:12</span> <span class="go">Files: 5307 new, 0 changed, 0 unmodified</span> <span class="go">Dirs: 1867 new, 0 changed, 0 unmodified</span> <span class="go">Added: 1.200 GiB</span> <span class="go">snapshot 40dc1520 saved</span> </pre></div> </div> <p>As you can see, restic created a backup of the directory and was pretty fast! The specific snapshot just created is identified by a sequence of hexadecimal characters, <code class="docutils literal notranslate"><span class="pre">40dc1520</span></code> in this case.</p> <p>You can see that restic tells us it processed 1.720 GiB of data, this is the size of the files and directories in <code class="docutils literal notranslate"><span class="pre">~/work</span></code> on the local file system. It also tells us that only 1.200 GiB was added to the repository. This means that some of the data was duplicate and restic was able to efficiently reduce it.</p> <p>If you don’t pass the <code class="docutils literal notranslate"><span class="pre">--verbose</span></code> option, restic will print less data. You’ll still get a nice live status display. Be aware that the live status shows the processed files and not the transferred data. Transferred volume might be lower (due to de-duplication) or higher.</p> <p>On Windows, the <code class="docutils literal notranslate"><span class="pre">--use-fs-snapshot</span></code> option will use Windows’ Volume Shadow Copy Service (VSS) when creating backups. Restic will transparently create a VSS snapshot for each volume that contains files to backup. Files are read from the VSS snapshot instead of the regular filesystem. This allows to backup files that are exclusively locked by another process during the backup.</p> <p>By default VSS ignores Outlook OST files. This is not a restriction of restic but the default Windows VSS configuration. The files not to snapshot are configured in the Windows registry under the following key:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\BackupRestore\FilesNotToSnapshot</span> </pre></div> </div> <p>For more details refer the official Windows documentation e.g. the article <code class="docutils literal notranslate"><span class="pre">Registry</span> <span class="pre">Keys</span> <span class="pre">and</span> <span class="pre">Values</span> <span class="pre">for</span> <span class="pre">Backup</span> <span class="pre">and</span> <span class="pre">Restore</span></code>.</p> <p>If you run the backup command again, restic will create another snapshot of your data, but this time it’s even faster and no new data was added to the repository (since all data is already there). This is de-duplication at work!</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo --verbose backup ~/work <span class="go">open repository</span> <span class="go">enter password for repository:</span> <span class="go">password is correct</span> <span class="go">lock repository</span> <span class="go">load index files</span> <span class="go">using parent snapshot d875ae93</span> <span class="go">start scan</span> <span class="go">start backup</span> <span class="go">scan finished in 1.881s</span> <span class="go">processed 1.720 GiB in 0:03</span> <span class="go">Files: 0 new, 0 changed, 5307 unmodified</span> <span class="go">Dirs: 0 new, 0 changed, 1867 unmodified</span> <span class="go">Added: 0 B</span> <span class="go">snapshot 79766175 saved</span> </pre></div> </div> <p>You can even backup individual files in the same repository (not passing <code class="docutils literal notranslate"><span class="pre">--verbose</span></code> means less output):</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo backup ~/work.txt <span class="go">enter password for repository:</span> <span class="go">password is correct</span> <span class="go">snapshot 249d0210 saved</span> </pre></div> </div> <p>If you’re interested in what restic does, pass <code class="docutils literal notranslate"><span class="pre">--verbose</span></code> twice (or <code class="docutils literal notranslate"><span class="pre">--verbose=2</span></code>) to display detailed information about each file and directory restic encounters:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">echo</span> <span class="s1">'more data foo bar'</span> >> ~/work.txt <span class="gp">$ </span>restic -r /srv/restic-repo --verbose --verbose backup ~/work.txt <span class="go">open repository</span> <span class="go">enter password for repository:</span> <span class="go">password is correct</span> <span class="go">lock repository</span> <span class="go">load index files</span> <span class="go">using parent snapshot f3f8d56b</span> <span class="go">start scan</span> <span class="go">start backup</span> <span class="go">scan finished in 2.115s</span> <span class="go">modified /home/user/work.txt, saved in 0.007s (22 B added)</span> <span class="go">modified /home/user/, saved in 0.008s (0 B added, 378 B metadata)</span> <span class="go">modified /home/, saved in 0.009s (0 B added, 375 B metadata)</span> <span class="go">processed 22 B in 0:02</span> <span class="go">Files: 0 new, 1 changed, 0 unmodified</span> <span class="go">Dirs: 0 new, 2 changed, 0 unmodified</span> <span class="go">Data Blobs: 1 new</span> <span class="go">Tree Blobs: 3 new</span> <span class="go">Added: 1.116 KiB</span> <span class="go">snapshot 8dc503fc saved</span> </pre></div> </div> <p>In fact several hosts may use the same repository to backup directories and files leading to a greater de-duplication.</p> <p>Now is a good time to run <code class="docutils literal notranslate"><span class="pre">restic</span> <span class="pre">check</span></code> to verify that all data is properly stored in the repository. You should run this command regularly to make sure the internal structure of the repository is free of errors.</p> <section id="file-change-detection"> <h2>File change detection<a class="headerlink" href="#file-change-detection" title="Permalink to this headline">¶</a></h2> <p>When restic encounters a file that has already been backed up, whether in the current backup or a previous one, it makes sure the file’s contents are only stored once in the repository. To do so, it normally has to scan the entire contents of every file. Because this can be very expensive, restic also uses a change detection rule based on file metadata to determine whether a file is likely unchanged since a previous backup. If it is, the file is not scanned again.</p> <p>Change detection is only performed for regular files (not special files, symlinks or directories) that have the exact same path as they did in a previous backup of the same location. If a file or one of its containing directories was renamed, it is considered a different file and its entire contents will be scanned again.</p> <p>Metadata changes (permissions, ownership, etc.) are always included in the backup, even if file contents are considered unchanged.</p> <p>On <strong>Unix</strong> (including Linux and Mac), given that a file lives at the same location as a file in a previous backup, the following file metadata attributes have to match for its contents to be presumed unchanged:</p> <blockquote> <div><ul class="simple"> <li><p>Modification timestamp (mtime).</p></li> <li><p>Metadata change timestamp (ctime).</p></li> <li><p>File size.</p></li> <li><p>Inode number (internal number used to reference a file in a filesystem).</p></li> </ul> </div></blockquote> <p>The reason for requiring both mtime and ctime to match is that Unix programs can freely change mtime (and some do). In such cases, a ctime change may be the only hint that a file did change.</p> <p>The following <code class="docutils literal notranslate"><span class="pre">restic</span> <span class="pre">backup</span></code> command line flags modify the change detection rules:</p> <blockquote> <div><ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">--force</span></code>: turn off change detection and rescan all files.</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--ignore-ctime</span></code>: require mtime to match, but allow ctime to differ.</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--ignore-inode</span></code>: require mtime to match, but allow inode number and ctime to differ.</p></li> </ul> </div></blockquote> <p>The option <code class="docutils literal notranslate"><span class="pre">--ignore-inode</span></code> exists to support FUSE-based filesystems and pCloud, which do not assign stable inodes to files.</p> <p>Note that the device id of the containing mount point is never taken into account. Device numbers are not stable for removable devices and ZFS snapshots. If you want to force a re-scan in such a case, you can change the mountpoint.</p> <p>On <strong>Windows</strong>, a file is considered unchanged when its path, size and modification time match, and only <code class="docutils literal notranslate"><span class="pre">--force</span></code> has any effect. The other options are recognized but ignored.</p> </section> <section id="excluding-files"> <h2>Excluding Files<a class="headerlink" href="#excluding-files" title="Permalink to this headline">¶</a></h2> <p>You can exclude folders and files by specifying exclude patterns, currently the exclude options are:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">--exclude</span></code> Specified one or more times to exclude one or more items</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--iexclude</span></code> Same as <code class="docutils literal notranslate"><span class="pre">--exclude</span></code> but ignores the case of paths</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--exclude-caches</span></code> Specified once to exclude folders containing a special file</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--exclude-file</span></code> Specified one or more times to exclude items listed in a given file</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--iexclude-file</span></code> Same as <code class="docutils literal notranslate"><span class="pre">exclude-file</span></code> but ignores cases like in <code class="docutils literal notranslate"><span class="pre">--iexclude</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--exclude-if-present</span> <span class="pre">foo</span></code> Specified one or more times to exclude a folder’s content if it contains a file called <code class="docutils literal notranslate"><span class="pre">foo</span></code> (optionally having a given header, no wildcards for the file name supported)</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--exclude-larger-than</span> <span class="pre">size</span></code> Specified once to excludes files larger than the given size</p></li> </ul> <p>Please see <code class="docutils literal notranslate"><span class="pre">restic</span> <span class="pre">help</span> <span class="pre">backup</span></code> for more specific information about each exclude option.</p> <p>Let’s say we have a file called <code class="docutils literal notranslate"><span class="pre">excludes.txt</span></code> with the following content:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># exclude go-files</span> <span class="o">.</span><span class="n">go</span> <span class="c1"># exclude foo/x/y/z/bar foo/x/bar foo/bar</span> <span class="n">foo</span><span class="o">//</span><span class="n">bar</span> </pre></div> </div> <p>It can be used like this:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo backup ~/work --exclude<span class="o">=</span><span class="s2">".c"</span> --exclude-file<span class="o">=</span>excludes.txt </pre></div> </div> <p>This instructs restic to exclude files matching the following criteria:</p> <blockquote> <div><ul class="simple"> <li><p>All files matching <code class="docutils literal notranslate"><span class="pre">.c</span></code> (parameter <code class="docutils literal notranslate"><span class="pre">--exclude</span></code>)</p></li> <li><p>All files matching <code class="docutils literal notranslate"><span class="pre">.go</span></code> (second line in <code class="docutils literal notranslate"><span class="pre">excludes.txt</span></code>)</p></li> <li><p>All files and sub-directories named <code class="docutils literal notranslate"><span class="pre">bar</span></code> which reside somewhere below a directory called <code class="docutils literal notranslate"><span class="pre">foo</span></code> (fourth line in <code class="docutils literal notranslate"><span class="pre">excludes.txt</span></code>)</p></li> </ul> </div></blockquote> <p>Patterns use <a class="reference external" href="https://golang.org/pkg/path/filepath/#Glob">filepath.Glob</a> internally, see <a class="reference external" href="https://golang.org/pkg/path/filepath/#Match">filepath.Match</a> for syntax. Patterns are tested against the full path of a file/dir to be saved, even if restic is passed a relative path to save. Empty lines and lines starting with a <code class="docutils literal notranslate"><span class="pre">#</span></code> are ignored.</p> <p>Environment variables in exclude files are expanded with <a class="reference external" href="https://golang.org/pkg/os/#ExpandEnv">os.ExpandEnv</a>, so <code class="docutils literal notranslate"><span class="pre">/home/$USER/foo</span></code> will be expanded to <code class="docutils literal notranslate"><span class="pre">/home/bob/foo</span></code> for the user <code class="docutils literal notranslate"><span class="pre">bob</span></code>. To get a literal dollar sign, write <code class="docutils literal notranslate"><span class="pre">$$</span></code> to the file - this has to be done even when there’s no matching environment variable for the word following a single <code class="docutils literal notranslate"><span class="pre">$</span></code>. Note that tilde (<code class="docutils literal notranslate"><span class="pre">~</span></code>) is not expanded, instead use the <code class="docutils literal notranslate"><span class="pre">$HOME</span></code> or equivalent environment variable (depending on your operating system).</p> <p>Patterns need to match on complete path components. For example, the pattern <code class="docutils literal notranslate"><span class="pre">foo</span></code>:</p> <blockquote> <div><ul class="simple"> <li><p>matches <code class="docutils literal notranslate"><span class="pre">/dir1/foo/dir2/file</span></code> and <code class="docutils literal notranslate"><span class="pre">/dir/foo</span></code></p></li> <li><p>does not match <code class="docutils literal notranslate"><span class="pre">/dir/foobar</span></code> or <code class="docutils literal notranslate"><span class="pre">barfoo</span></code></p></li> </ul> </div></blockquote> <p>A trailing <code class="docutils literal notranslate"><span class="pre">/</span></code> is ignored, a leading <code class="docutils literal notranslate"><span class="pre">/</span></code> anchors the pattern at the root directory. This means, <code class="docutils literal notranslate"><span class="pre">/bin</span></code> matches <code class="docutils literal notranslate"><span class="pre">/bin/bash</span></code> but does not match <code class="docutils literal notranslate"><span class="pre">/usr/bin/restic</span></code>.</p> <p>Regular wildcards cannot be used to match over the directory separator <code class="docutils literal notranslate"><span class="pre">/</span></code>, e.g. <code class="docutils literal notranslate"><span class="pre">bash</span></code> matches <code class="docutils literal notranslate"><span class="pre">/bin/bash</span></code> but does not match <code class="docutils literal notranslate"><span class="pre">/bin/ash</span></code>. For this, the special wildcard <code class="docutils literal notranslate"><span class="pre"></span></code> can be used to match arbitrary sub-directories: The pattern <code class="docutils literal notranslate"><span class="pre">foo//bar</span></code> matches:</p> <blockquote> <div><ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">/dir1/foo/dir2/bar/file</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">/foo/bar/file</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">/tmp/foo/bar</span></code></p></li> </ul> </div></blockquote> <p>Spaces in patterns listed in an exclude file can be specified verbatim. That is, in order to exclude a file named <code class="docutils literal notranslate"><span class="pre">foo</span> <span class="pre">bar</span> <span class="pre">star.txt</span></code>, put that just as it reads on one line in the exclude file. Please note that beginning and trailing spaces are trimmed - in order to match these, use e.g. a <code class="docutils literal notranslate"><span class="pre"></span></code> at the beginning or end of the filename.</p> <p>Spaces in patterns listed in the other exclude options (e.g. <code class="docutils literal notranslate"><span class="pre">--exclude</span></code> on the command line) are specified in different ways depending on the operating system and/or shell. Restic itself does not need any escaping, but your shell may need some escaping in order to pass the name/pattern as a single argument to restic.</p> <p>On most Unixy shells, you can either quote or use backslashes. For example:</p> <blockquote> <div><ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">--exclude='foo</span> <span class="pre">bar</span> <span class="pre">star/foo.txt'</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--exclude="foo</span> <span class="pre">bar</span> <span class="pre">star/foo.txt"</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">--exclude=foo\</span> <span class="pre">bar\</span> <span class="pre">star/foo.txt</span></code></p></li> </ul> </div></blockquote> <p>By specifying the option <code class="docutils literal notranslate"><span class="pre">--one-file-system</span></code> you can instruct restic to only backup files from the file systems the initially specified files or directories reside on. In other words, it will prevent restic from crossing filesystem boundaries and subvolumes when performing a backup.</p> <p>For example, if you backup <code class="docutils literal notranslate"><span class="pre">/</span></code> with this option and you have external media mounted under <code class="docutils literal notranslate"><span class="pre">/media/usb</span></code> then restic will not back up <code class="docutils literal notranslate"><span class="pre">/media/usb</span></code> at all because this is a different filesystem than <code class="docutils literal notranslate"><span class="pre">/</span></code>. Virtual filesystems such as <code class="docutils literal notranslate"><span class="pre">/proc</span></code> are also considered different and thereby excluded when using <code class="docutils literal notranslate"><span class="pre">--one-file-system</span></code>:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo backup --one-file-system / </pre></div> </div> <p>Please note that this does not prevent you from specifying multiple filesystems on the command line, e.g:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo backup --one-file-system / /media/usb </pre></div> </div> <p>will back up both the <code class="docutils literal notranslate"><span class="pre">/</span></code> and <code class="docutils literal notranslate"><span class="pre">/media/usb</span></code> filesystems, but will not include other filesystems like <code class="docutils literal notranslate"><span class="pre">/sys</span></code> and <code class="docutils literal notranslate"><span class="pre">/proc</span></code>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p><code class="docutils literal notranslate"><span class="pre">--one-file-system</span></code> is currently unsupported on Windows, and will cause the backup to immediately fail with an error.</p> </div> <p>Files larger than a given size can be excluded using the <cite>–exclude-larger-than</cite> option:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo backup ~/work --exclude-larger-than 1M </pre></div> </div> <p>This excludes files in <code class="docutils literal notranslate"><span class="pre">~/work</span></code> which are larger than 1 MB from the backup.</p> <p>The default unit for the size value is bytes, so e.g. <code class="docutils literal notranslate"><span class="pre">--exclude-larger-than</span> <span class="pre">2048</span></code> would exclude files larger than 2048 bytes (2 kilobytes). To specify other units, suffix the size value with one of <code class="docutils literal notranslate"><span class="pre">k</span></code>/<code class="docutils literal notranslate"><span class="pre">K</span></code> for kilobytes, <code class="docutils literal notranslate"><span class="pre">m</span></code>/<code class="docutils literal notranslate"><span class="pre">M</span></code> for megabytes, <code class="docutils literal notranslate"><span class="pre">g</span></code>/<code class="docutils literal notranslate"><span class="pre">G</span></code> for gigabytes and <code class="docutils literal notranslate"><span class="pre">t</span></code>/<code class="docutils literal notranslate"><span class="pre">T</span></code> for terabytes (e.g. <code class="docutils literal notranslate"><span class="pre">1k</span></code>, <code class="docutils literal notranslate"><span class="pre">10K</span></code>, <code class="docutils literal notranslate"><span class="pre">20m</span></code>, <code class="docutils literal notranslate"><span class="pre">20M</span></code>, <code class="docutils literal notranslate"><span class="pre">30g</span></code>, <code class="docutils literal notranslate"><span class="pre">30G</span></code>, <code class="docutils literal notranslate"><span class="pre">2t</span></code> or <code class="docutils literal notranslate"><span class="pre">2T</span></code>).</p> </section> <section id="including-files"> <h2>Including Files<a class="headerlink" href="#including-files" title="Permalink to this headline">¶</a></h2> <p>The options <code class="docutils literal notranslate"><span class="pre">--files-from</span></code>, <code class="docutils literal notranslate"><span class="pre">--files-from-verbatim</span></code> and <code class="docutils literal notranslate"><span class="pre">--files-from-raw</span></code> allow you to give restic a file containing lists of file patterns or paths to be backed up. This is useful e.g. when you want to back up files from many different locations, or when you use some other software to generate the list of files to back up.</p> <p>The argument passed to <code class="docutils literal notranslate"><span class="pre">--files-from</span></code> must be the name of a text file that contains one <em>pattern</em> per line. The file must be encoded as UTF-8, or UTF-16 with a byte-order mark. Leading and trailing whitespace is removed from the patterns. Empty lines and lines starting with a <code class="docutils literal notranslate"><span class="pre">#</span></code> are ignored and each pattern is expanded when read, such that special characters in it are expanded using the Go function <a class="reference external" href="https://golang.org/pkg/path/filepath/#Glob">filepath.Glob</a> - please see its documentation for the syntax you can use in the patterns.</p> <p>The argument passed to <code class="docutils literal notranslate"><span class="pre">--files-from-verbatim</span></code> must be the name of a text file that contains one <em>path</em> per line, e.g. as generated by GNU <code class="docutils literal notranslate"><span class="pre">find</span></code> with the <code class="docutils literal notranslate"><span class="pre">-print</span></code> flag. Unlike <code class="docutils literal notranslate"><span class="pre">--files-from</span></code>, <code class="docutils literal notranslate"><span class="pre">--files-from-verbatim</span></code> does not expand any special characters in the list of paths, does not strip off any whitespace and does not ignore lines starting with a <code class="docutils literal notranslate"><span class="pre">#</span></code>. This option simply reads and uses each line as-is, although empty lines are still ignored. Use this option when you want to backup a list of filenames containing the special characters that would otherwise be expanded when using <code class="docutils literal notranslate"><span class="pre">--files-from</span></code>.</p> <p>The <code class="docutils literal notranslate"><span class="pre">--files-from-raw</span></code> option is a variant of <code class="docutils literal notranslate"><span class="pre">--files-from-verbatim</span></code> that requires each line in the file to be terminated by an ASCII NUL character (the <code class="docutils literal notranslate"><span class="pre">\0</span></code> zero byte) instead of a newline, so that it can even handle file paths containing newlines in their name or are not encoded as UTF-8 (except on Windows, where the listed filenames must still be encoded in UTF-8. This option is the safest choice when generating the list of filenames from a script (e.g. GNU <code class="docutils literal notranslate"><span class="pre">find</span></code> with the <code class="docutils literal notranslate"><span class="pre">-print0</span></code> flag).</p> <p>All three options interpret the argument <code class="docutils literal notranslate"><span class="pre">-</span></code> as standard input and will read the list of files/patterns from there instead of a text file.</p> <p>In all cases, paths may be absolute or relative to <code class="docutils literal notranslate"><span class="pre">restic</span> <span class="pre">backup</span></code>’s working directory.</p> <p>For example, maybe you want to backup files which have a name that matches a certain regular expression pattern (uses GNU <code class="docutils literal notranslate"><span class="pre">find</span></code>):</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>find /tmp/some_folder -regex PATTERN -print0 > /tmp/files_to_backup </pre></div> </div> <p>You can then use restic to backup the filtered files:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo backup --files-from-raw /tmp/files_to_backup </pre></div> </div> <p>You can combine all three options with each other and with the normal file arguments:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic backup --files-from /tmp/files_to_backup /tmp/some_additional_file <span class="gp">$ </span>restic backup --files-from /tmp/glob-pattern --files-from-raw /tmp/generated-list /tmp/some_additional_file </pre></div> </div> </section> <section id="comparing-snapshots"> <h2>Comparing Snapshots<a class="headerlink" href="#comparing-snapshots" title="Permalink to this headline">¶</a></h2> <p>Restic has a <cite>diff</cite> command which shows the difference between two snapshots and displays a small statistic, just pass the command two snapshot IDs:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo diff 5845b002 2ab627a6 <span class="go">password is correct</span> <span class="go">comparing snapshot ea657ce5 to 2ab627a6:</span> <span class="go"> C /restic/cmd_diff.go</span> <span class="go">+ /restic/foo</span> <span class="go"> C /restic/restic</span> <span class="go">Files: 0 new, 0 removed, 2 changed</span> <span class="go">Dirs: 1 new, 0 removed</span> <span class="go">Others: 0 new, 0 removed</span> <span class="go">Data Blobs: 14 new, 15 removed</span> <span class="go">Tree Blobs: 2 new, 1 removed</span> <span class="go"> Added: 16.403 MiB</span> <span class="go"> Removed: 16.402 MiB</span> </pre></div> </div> </section> <section id="backing-up-special-items-and-metadata"> <h2>Backing up special items and metadata<a class="headerlink" href="#backing-up-special-items-and-metadata" title="Permalink to this headline">¶</a></h2> <p><strong>Symlinks</strong> are archived as symlinks, <code class="docutils literal notranslate"><span class="pre">restic</span></code> does not follow them. When you restore, you get the same symlink again, with the same link target and the same timestamps.</p> <p>If there is a <strong>bind-mount</strong> below a directory that is to be saved, restic descends into it.</p> <p><strong>Device files</strong> are saved and restored as device files. This means that e.g. <code class="docutils literal notranslate"><span class="pre">/dev/sda</span></code> is archived as a block device file and restored as such. This also means that the content of the corresponding disk is not read, at least not from the device file.</p> <p>By default, restic does not save the access time (atime) for any files or other items, since it is not possible to reliably disable updating the access time by restic itself. This means that for each new backup a lot of metadata is written, and the next backup needs to write new metadata again. If you really want to save the access time for files and directories, you can pass the <code class="docutils literal notranslate"><span class="pre">--with-atime</span></code> option to the <code class="docutils literal notranslate"><span class="pre">backup</span></code> command.</p> </section> <section id="reading-data-from-stdin"> <h2>Reading data from stdin<a class="headerlink" href="#reading-data-from-stdin" title="Permalink to this headline">¶</a></h2> <p>Sometimes it can be nice to directly save the output of a program, e.g. <code class="docutils literal notranslate"><span class="pre">mysqldump</span></code> so that the SQL can later be restored. Restic supports this mode of operation, just supply the option <code class="docutils literal notranslate"><span class="pre">--stdin</span></code> to the <code class="docutils literal notranslate"><span class="pre">backup</span></code> command like this:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">set</span> -o pipefail <span class="gp">$ </span>mysqldump <span class="o">[</span>...<span class="o">]</span> <span class="p">\|</span> restic -r /srv/restic-repo backup --stdin </pre></div> </div> <p>This creates a new snapshot of the output of <code class="docutils literal notranslate"><span class="pre">mysqldump</span></code>. You can then use e.g. the fuse mounting option (see below) to mount the repository and read the file.</p> <p>By default, the file name <code class="docutils literal notranslate"><span class="pre">stdin</span></code> is used, a different name can be specified with <code class="docutils literal notranslate"><span class="pre">--stdin-filename</span></code>, e.g. like this:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>mysqldump <span class="o">[</span>...<span class="o">]</span> <span class="p">\|</span> restic -r /srv/restic-repo backup --stdin --stdin-filename production.sql </pre></div> </div> <p>The option <code class="docutils literal notranslate"><span class="pre">pipefail</span></code> is highly recommended so that a non-zero exit code from one of the programs in the pipe (e.g. <code class="docutils literal notranslate"><span class="pre">mysqldump</span></code> here) makes the whole chain return a non-zero exit code. Refer to the <a class="reference external" href="http://redsymbol.net/articles/unofficial-bash-strict-mode/">Use the Unofficial Bash Strict Mode</a> for more details on this.</p> </section> <section id="tags-for-backup"> <h2>Tags for backup<a class="headerlink" href="#tags-for-backup" title="Permalink to this headline">¶</a></h2> <p>Snapshots can have one or more tags, short strings which add identifying information. Just specify the tags for a snapshot one by one with <code class="docutils literal notranslate"><span class="pre">--tag</span></code>:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>restic -r /srv/restic-repo backup --tag projectX --tag foo --tag bar ~/work <span class="go">[...]</span> </pre></div> </div> <p>The tags can later be used to keep (or forget) snapshots with the <code class="docutils literal notranslate"><span class="pre">forget</span></code> command. The command <code class="docutils literal notranslate"><span class="pre">tag</span></code> can be used to modify tags on an existing snapshot.</p> </section> <section id="space-requirements"> <h2>Space requirements<a class="headerlink" href="#space-requirements" title="Permalink to this headline">¶</a></h2> <p>Restic currently assumes that your backup repository has sufficient space for the backup operation you are about to perform. This is a realistic assumption for many cloud providers, but may not be true when backing up to local disks.</p> <p>Should you run out of space during the middle of a backup, there will be some additional data in the repository, but the snapshot will never be created as it would only be written at the very (successful) end of the backup operation. Previous snapshots will still be there and will still work.</p> </section> <section id="environment-variables"> <h2>Environment Variables<a class="headerlink" href="#environment-variables" title="Permalink to this headline">¶</a></h2> <p>In addition to command-line options, restic supports passing various options in environment variables. The following lists these environment variables:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">RESTIC_REPOSITORY_FILE Name of file containing the repository location (replaces --repository-file)</span> <span class="go">RESTIC_REPOSITORY Location of repository (replaces -r)</span> <span class="go">RESTIC_PASSWORD_FILE Location of password file (replaces --password-file)</span> <span class="go">RESTIC_PASSWORD The actual password for the repository</span> <span class="go">RESTIC_PASSWORD_COMMAND Command printing the password for the repository to stdout</span> <span class="go">RESTIC_KEY_HINT ID of key to try decrypting first, before other keys</span> <span class="go">RESTIC_CACHE_DIR Location of the cache directory</span> <span class="go">RESTIC_PROGRESS_FPS Frames per second by which the progress bar is updated</span> <span class="go">TMPDIR Location for temporary files</span> <span class="go">AWS_ACCESS_KEY_ID Amazon S3 access key ID</span> <span class="go">AWS_SECRET_ACCESS_KEY Amazon S3 secret access key</span> <span class="go">AWS_DEFAULT_REGION Amazon S3 default region</span> <span class="go">ST_AUTH Auth URL for keystone v1 authentication</span> <span class="go">ST_USER Username for keystone v1 authentication</span> <span class="go">ST_KEY Password for keystone v1 authentication</span> <span class="go">OS_AUTH_URL Auth URL for keystone authentication</span> <span class="go">OS_REGION_NAME Region name for keystone authentication</span> <span class="go">OS_USERNAME Username for keystone authentication</span> <span class="go">OS_USER_ID User ID for keystone v3 authentication</span> <span class="go">OS_PASSWORD Password for keystone authentication</span> <span class="go">OS_TENANT_ID Tenant ID for keystone v2 authentication</span> <span class="go">OS_TENANT_NAME Tenant name for keystone v2 authentication</span> <span class="go">OS_USER_DOMAIN_NAME User domain name for keystone authentication</span> <span class="go">OS_USER_DOMAIN_ID User domain ID for keystone v3 authentication</span> <span class="go">OS_PROJECT_NAME Project name for keystone authentication</span> <span class="go">OS_PROJECT_DOMAIN_NAME Project domain name for keystone authentication</span> <span class="go">OS_PROJECT_DOMAIN_ID Project domain ID for keystone v3 authentication</span> <span class="go">OS_TRUST_ID Trust ID for keystone v3 authentication</span> <span class="go">OS_APPLICATION_CREDENTIAL_ID Application Credential ID (keystone v3)</span> <span class="go">OS_APPLICATION_CREDENTIAL_NAME Application Credential Name (keystone v3)</span> <span class="go">OS_APPLICATION_CREDENTIAL_SECRET Application Credential Secret (keystone v3)</span> <span class="go">OS_STORAGE_URL Storage URL for token authentication</span> <span class="go">OS_AUTH_TOKEN Auth token for token authentication</span> <span class="go">B2_ACCOUNT_ID Account ID or applicationKeyId for Backblaze B2</span> <span class="go">B2_ACCOUNT_KEY Account Key or applicationKey for Backblaze B2</span> <span class="go">AZURE_ACCOUNT_NAME Account name for Azure</span> <span class="go">AZURE_ACCOUNT_KEY Account key for Azure</span> <span class="go">GOOGLE_PROJECT_ID Project ID for Google Cloud Storage</span> <span class="go">GOOGLE_APPLICATION_CREDENTIALS Application Credentials for Google Cloud Storage (e.g. $HOME/.config/gs-secret-restic-key.json)</span> <span class="go">RCLONE_BWLIMIT rclone bandwidth limit</span> </pre></div> </div> <p>See <a class="reference internal" href="manual_rest.html#caching"><span class="std std-ref">Caching</span></a> for the rules concerning cache locations when <code class="docutils literal notranslate"><span class="pre">RESTIC_CACHE_DIR</span></code> is not set.</p> <p>The external programs that restic may execute include <code class="docutils literal notranslate"><span class="pre">rclone</span></code> (for rclone backends) and <code class="docutils literal notranslate"><span class="pre">ssh</span></code> (for the SFTP backend). These may respond to further environment variables and configuration files; see their respective manuals.</p> </section> <section id="exit-status-codes"> <h2>Exit status codes<a class="headerlink" href="#exit-status-codes" title="Permalink to this headline">¶</a></h2> <p>Restic returns one of the following exit status codes after the backup command is run:</p> <blockquote> <div><ul class="simple"> <li><p>0 when the backup was successful (snapshot with all source files created)</p></li> <li><p>1 when there was a fatal error (no snapshot created)</p></li> <li><p>3 when some source files could not be read (incomplete snapshot with remaining files created)</p></li> </ul> </div></blockquote> <p>Fatal errors occur for example when restic is unable to write to the backup destination, when there are network connectivity issues preventing successful communication, or when an invalid password or command line argument is provided. When restic returns this exit status code, one should not expect a snapshot to have been created.</p> <p>Source file read errors occur when restic fails to read one or more files or directories that it was asked to back up, e.g. due to permission problems. Restic displays the number of source file read errors that occurred while running the backup. If there are errors of this type, restic will still try to complete the backup run with all the other files, and create a snapshot that then contains all but the unreadable files.</p> <p>One can use these exit status codes in scripts and other automation tools, to make them aware of the outcome of the backup run. To manually inspect the exit code in e.g. Linux, run <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">$?</span></code>.</p> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="030_preparing_a_new_repo.html" class="btn btn-neutral float-left" title="Preparing a new repository" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="045_working_with_repos.html" class="btn btn-neutral float-right" title="Working with repositories" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p>© Copyright 2024, restic authors.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>

| ver. 1.4 | Github | . | PHP 8.2.28 | Generation time: 0.02 | proxy | phpinfo | Settings