docs

2025-09-02 00:30:40 +00:00 · 2020-11-06 22:42:00 +01:00
parent b5bc1a4cee
commit d959a50b5a
70 changed files with 4912 additions and 2664 deletions
--- a/docs/location/cron.html
+++ b/docs/location/cron.html
--- a/docs/location/cron.md
+++ b/docs/location/cron.md
@@ -0,0 +1,47 @@
+# Cron
+
+Often it is usefull to trigger backups autmatically. For this we can specify a `cron` attribute to each location.
+
+> Available since version 0.18
+
+```yaml | .autorestic.yml
+locations:
+  my-location:
+    from: /data
+    to: my-backend
+    cron: '0 3 * * 0' # Every Sunday at 3:00
+```
+
+Here is a awesome website with [some examples](https://crontab.guru/examples.html) and an [explorer](https://crontab.guru/)
+
+## Installing the cron
+
+**This has to be done only once, regadless of now many cros you have in your config file.**
+
+To actually enable cron jobs you need something to call `autorestic cron` on a timed shedule.
+Note that the shedule has nothing to do with the `cron` attribute in each location.
+My advise would be to trigger the command every 5min, but if you have a cronjob that runs only once a week, it's probably enough to shedule it once a day.
+
+### Crontab
+
+Here is an example using crontab, but systemd would do too.
+
+First, open your crontab in edit mode
+
+```bash
+crontab -e
+```
+
+Then paste this at the bottom of the file and save it. Note that in this specific example the `.autorestic.yml` is located in `/srv/`. You need to modify that part of course to fit your config file.
+
+```bash
+# This is required, as it otherwise cannot find restic as a command.
+PATH="/usr/local/bin:/usr/bin:/bin"
+
+# Example running every 5 minutes
+*/5 * * * * autorestic -c /srv/.autorestic.yml cron
+```
+
+Now you can add as many `cron` attributes as you wish ⏱
+
+> :ToCPrevNext
--- a/docs/location/docker.html
+++ b/docs/location/docker.html
--- a/docs/location/docker.md
+++ b/docs/location/docker.md
@@ -0,0 +1,58 @@
+# Docker
+
+autorestic supports docker volumes directly, without needing them to be mounted to the host filesystem.
+
+> Available since version 0.13
+
+Let see an example.
+
+```yaml | docker-compose.yml
+version: '3.7'
+
+volumes:
+  data:
+    name: my-data
+
+services:
+  api:
+    image: alpine
+    volumes:
+      - data:/foo/bar
+```
+
+```yaml | .autorestic.yml
+locations:
+  hello:
+    from: 'volume:my-data'
+    to:
+      - remote
+    options:
+      forget:
+        keep-last: 14 # Useful for limitations explained belowd
+
+backends:
+  remote: ...
+```
+
+Now you can backup and restore as always.
+
+```bash
+autorestic -l hello backup
+```
+
+```bash
+autorestic -l hello restore
+```
+
+If the volume does not exist on restore, autorestic will create it for you and then fill it with the data.
+
+## Limitations
+
+Unfortunately there are some limitations when backing up directly from a docker volume without mounting the volume to the host:
+
+1. Incremental updates are not possible right now due to how the current docker mounting works. This means that it will take significantely more space.
+2. Exclude patterns and files also do not work as restic only sees a compressed tarball as source and not the actual data.
+
+If you are curious or have ideas how to improve this, please [read more here](https://github.com/cupcakearmy/autorestic/issues/4#issuecomment-568771951). Any help is welcomed 🙂
+
+> :ToCPrevNext
--- a/docs/location/exclude.html
+++ b/docs/location/exclude.html
--- a/docs/location/exclude.md
+++ b/docs/location/exclude.md
@@ -0,0 +1,20 @@
+# Excluding files
+
+If you want to exclude certain files or folders it done easily by specifiyng the right flags in the location you desire to filter.
+
+The flags are taken straight from the [restic cli exclude rules](https://restic.readthedocs.io/en/latest/040_backup.html#excluding-files) so you can use any flag used there.
+
+```yaml
+locations:
+  my-location:
+    from: /data
+    to: my-backend
+    options:
+      backup:
+        exclude:
+          - '*.nope'
+          - '*.abc'
+        exclude-file: .gitignore
+```
+
+> :ToCPrevNext
--- a/docs/location/forget.html
+++ b/docs/location/forget.html
--- a/docs/location/forget.md
+++ b/docs/location/forget.md
@@ -0,0 +1,25 @@
+# Forget/Prune Policies
+
+Autorestic supports declaring snapshot policies for location to avoid keeping old snapshot around if you don't need them.
+
+This is based on [Restic's snapshots policies](https://restic.readthedocs.io/en/latest/060_forget.html#removing-snapshots-according-to-a-policy), and can be enabled for each location as shown below:
+
+> **Note** This is a full example, of course you also can specify only one of them
+
+```yaml | .autorestic.yml
+locations:
+  etc:
+    from: /etc
+    to: local
+    options:
+      forget:
+        keep-last: 5 # always keep at least 5 snapshots
+        keep-hourly: 3 # keep 3 last hourly shapshots
+        keep-daily: 4 # keep 4 last daily shapshots
+        keep-weekly: 1 # keep 1 last weekly shapshots
+        keep-monthly: 12 # keep 12 last monthly shapshots
+        keep-yearly: 7 # keep 7 last yearly shapshots
+        keep-within: '2w' # keep snapshots from the last 2 weeks
+```
+
+> :ToCPrevNext
--- a/docs/location/hooks.html
+++ b/docs/location/hooks.html
--- a/docs/location/hooks.md
+++ b/docs/location/hooks.md
@@ -0,0 +1,18 @@
+# Hooks
+
+Sometimes you might want to stop an app/db before backing up data and start the service again after the backup has completed. This is what the hooks are made for. Simply add them to your location config. You can have as many commands as you wish.
+
+```yml | .autorestic.yml
+locations:
+  my-location:
+    from: /data
+    to: my-backend
+    hooks:
+      before:
+        - echo "Hello"
+        - echo "Human"
+      after:
+        - echo "kthxbye"
+```
+
+> :ToCPrevNext
--- a/docs/location/overview.html
+++ b/docs/location/overview.html
@@ -1,63 +0,0 @@
-<!DOCTYPE html><html><head><title>Autorestic | 🗂 Locations</title><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"><meta name="robots" content="index,follow"><meta name="theme-color" content="#212121"><meta name="apple-mobile-web-app-status-bar-style" content="black-translucent"><link href="https://fonts.googleapis.com/css?family=Hind:400,700&amp;display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:300,400&amp;display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/icon?family=Material+Icons|Material+Icons+Outlined" rel="stylesheet"><style>
-      body, input, button {
-        font-family: 'Hind', sans-serif;
-      }
-
-      code, .hljs {
-        font-family: 'Source Code Pro', 'Courier New', Courier, monospace;
-      }
-
-      .icon-font {
-        font-family: 'Material Icons';
-        font-weight: normal;
-        font-style: normal;
-        font-size: 24px;  /* Preferred icon size */
-        display: inline-block;
-        line-height: 1;
-        text-transform: none;
-        letter-spacing: normal;
-        word-wrap: normal;
-        white-space: nowrap;
-        direction: ltr;
-      
-        /* Support for all WebKit browsers. */
-        -webkit-font-smoothing: antialiased;
-        /* Support for Safari and Chrome. */
-        text-rendering: optimizeLegibility;
-      
-        /* Support for Firefox. */
-        -moz-osx-font-smoothing: grayscale;
-      
-        /* Support for IE. */
-        font-feature-settings: 'liga';
-      }
-
-      .icon-font.outline {
-        font-family: 'Material Icons Outlined';
-      }
-    </style><link href="/autorestic/./dist/codedoc-styles.css" rel="stylesheet"><script async="" defer="" src="/autorestic/./dist/codedoc-bundle.js"></script></head><body><div class="header-0-0-9"><script async="" defer="" src="https://buttons.github.io/buttons.js"></script><a class="github-button" data-color-scheme="no-preference: light; light: light; dark: dark;" data-icon="false" data-show-count="true" data-size="false" href="https://github.com/cupcakearmy/autorestic/">Star</a><br><br><a class="watermark-0-0-8" href="https://github.com/CONNECT-platform/codedoc" target="_blank">Created With<svg viewBox="0 0 536 296" version="1.1" xmlns="http://www.w3.org/2000/svg"><g id="codedoc" transform="translate(-244.000000, -364.000000)" fill-rule="nonzero"><path d="M580,532 C615.346224,532 644,560.653776 644,596 C644,631.346224 615.346224,660 580,660 C544.653776,660 516,631.346224 516,596 C516,560.653776 544.653776,532 580,532 Z M716,532 C751.346224,532 780,560.653776 780,596 C780,631.346224 751.346224,660 716,660 L692,660 C687.581722,660 684,656.418278 684,652 C684,647.581722 687.581722,644 692,644 L716,644 C742.509668,644 764,622.509668 764,596 C764,569.490332 742.509668,548 716,548 L692,548 C687.581722,548 684,544.418278 684,540 C684,535.581722 687.581722,532 692,532 L716,532 Z M468,532 C472.418278,532 476,535.581722 476,540 L476,652 C476,656.418278 472.418278,660 468,660 L444,660 C408.653776,660 380,631.346224 380,596 C380,560.653776 408.653776,532 444,532 L468,532 Z M332,532 C336.418278,532 340,535.581722 340,540 L340,652 C340,656.418278 336.418278,660 332,660 L252,660 C247.581722,660 244,656.418278 244,652 L244,540 C244,535.581722 247.581722,532 252,532 L332,532 Z M580,548 C553.490332,548 532,569.490332 532,596 C532,622.509668 553.490332,644 580,644 C606.509668,644 628,622.509668 628,596 C628,569.490332 606.509668,548 580,548 Z M461,548 L444,548 C417.490332,548 396,569.490332 396,596 C396,622.509668 417.490332,644 444,644 L461,644 L461,548 Z M444,364 C479.346224,364 508,392.653776 508,428 C508,463.346224 479.346224,492 444,492 C408.653776,492 380,463.346224 380,428 C380,392.653776 408.653776,364 444,364 Z M332,364 C336.418278,364 340,367.581722 340,372 C340,376.418278 336.418278,380 332,380 L308,380 C281.490332,380 260,401.490332 260,428 C260,454.509668 281.490332,476 308,476 L332,476 C336.418278,476 340,479.581722 340,484 C340,488.418278 336.418278,492 332,492 L308,492 C272.653776,492 244,463.346224 244,428 C244,392.653776 272.653776,364 308,364 L332,364 Z M580,364 C615.346224,364 644,392.653776 644,428 C644,463.346224 615.346224,492 580,492 L556,492 C551.581722,492 548,488.418278 548,484 L548,372 C548,367.581722 551.581722,364 556,364 L580,364 Z M772,364 C776.418278,364 780,367.581722 780,372 C780,376.418278 776.418278,380 772,380 L700,380 L700,420 L772,420 C776.418278,420 780,423.581722 780,428 C780,432.418278 776.418278,436 772,436 L700,436 L700,476 L772,476 C776.418278,476 780,479.581722 780,484 C780,488.418278 776.418278,492 772,492 L692,492 C687.581722,492 684,488.418278 684,484 L684,372 C684,367.581722 687.581722,364 692,364 L772,364 Z M444,380 C417.490332,380 396,401.490332 396,428 C396,454.509668 417.490332,476 444,476 C470.509668,476 492,454.509668 492,428 C492,401.490332 470.509668,380 444,380 Z M580,380 L563,380 L563,476 L580,476 C606.509668,476 628,454.509668 628,428 C628,401.490332 606.509668,380 580,380 Z"></path></g></svg></a></div><div id="-codedoc-container" class="container"><h1 id="🗂-locations" class="heading-0-0-1"><span class="anchor-0-0-2" data-ignore-text=""><span class="icon-font" data-ignore-text="" style="vertical-align: sub">link</span></span>🗂 Locations</h1><p>Locations can be seen as the input to the backup process. Generally this is simply a folder.
-The paths can be relative from the config file. A location can have multiple backends, so that the data is secured across multiple servers.</p><pre class="with-bar"><code class="yaml code-0-0-3" tabindex="0"><span class="wmbar-0-0-6"><span></span><span></span><span></span><span>.autorestic.yml</span></span><div class="line-0-0-5 " data-content="locations:"><span class="lineCounter-0-0-4 prim">1</span><span class="token key atrule">locations</span><span class="token punctuation">:</span></div><br><div class="line-0-0-5 " data-content="  my-location-name:"><span class="lineCounter-0-0-4">2</span>  <span class="token key atrule">my-location-name</span><span class="token punctuation">:</span></div><br><div class="line-0-0-5 " data-content="    from: path/to/backup"><span class="lineCounter-0-0-4">3</span>    <span class="token key atrule">from</span><span class="token punctuation">:</span> path/to/backup</div><br><div class="line-0-0-5 " data-content="    to:"><span class="lineCounter-0-0-4">4</span>    <span class="token key atrule">to</span><span class="token punctuation">:</span></div><br><div class="line-0-0-5 " data-content="      - name-of-backend"><span class="lineCounter-0-0-4 prim">5</span>      <span class="token punctuation">-</span> name<span class="token punctuation">-</span>of<span class="token punctuation">-</span>backend</div><br><div class="line-0-0-5 " data-content="      - also-backup-to-this-backend"><span class="lineCounter-0-0-4 prim">6</span>      <span class="token punctuation">-</span> also<span class="token punctuation">-</span>backup<span class="token punctuation">-</span>to<span class="token punctuation">-</span>this<span class="token punctuation">-</span>backend</div><br></code></pre><h2 id="from" class="heading-0-0-1"><span class="anchor-0-0-2" data-ignore-text=""><span class="icon-font" data-ignore-text="" style="vertical-align: sub">link</span></span><code>from</code></h2><p>This is the source of the location.</p><h4 id="how-are-paths-resolved" class="heading-0-0-1"><span class="anchor-0-0-2" data-ignore-text=""><span class="icon-font" data-ignore-text="" style="vertical-align: sub">link</span></span>How are paths resolved?</h4><p>Paths can be absolute or relative. If relative they are resolved relative to the location of the config file. Tilde <code>~</code> paths are also supported for home folder resolution.</p><h2 id="to" class="heading-0-0-1"><span class="anchor-0-0-2" data-ignore-text=""><span class="icon-font" data-ignore-text="" style="vertical-align: sub">link</span></span><code>to</code></h2><p>This is einther a single backend or an array of backends. The backends have to be configured in the same config file.</p><script id="UtxCDNLxWb">(function(){function load(){if (window.__sdh_transport){window.__sdh_transport("UtxCDNLxWb", "qcaKEY878Mn2dFQW/lSrDg==", {});} }; if (document.readyState == 'complete') load(); else window.addEventListener('load', load); })()</script><div class="contentnav-0-0-14" data-no-search=""><a href="#🗂-locations" class="h1" data-content-highlight="🗂-locations">🗂 Locations</a><a href="#from" class="h2" data-content-highlight="from">from</a><a href="#how-are-paths-resolved" class="h4" data-content-highlight="how-are-paths-resolved">How are paths resolved?</a><a href="#to" class="h2" data-content-highlight="to">to</a></div></div><div id="-codedoc-toc" class="toc-0-0-11"><script>
-     if (window.matchMedia('(min-width: 1200px)').matches) {
-       if (!localStorage.getItem('-codedoc-toc-active')) {
-         localStorage.setItem('-codedoc-toc-active', "true");
-       }
-     }
-     </script><div class="content-0-0-12"><p><a href="/autorestic/">Home</a>
-<a href="/autorestic/quick">Quick Start</a>
-<a href="/autorestic/installation">Installation</a>
-<a href="/autorestic/config">Configuration</a></p><div class="collapse-0-0-7 "><script id="OjrBIwpcML">(function(){function load(){if (window.__sdh_transport){window.__sdh_transport("OjrBIwpcML", "fz894w7KG2/tX4kLbbA1Kg==", {});} }; if (document.readyState == 'complete') load(); else window.addEventListener('load', load); })()</script><div class="label" onclick="this.parentElement.classList.toggle('open')"><span class="text">Locations</span><span class="icon-font closed">chevron_right</span></div><div class="content"><p><a href="/autorestic/location/overview">Overview</a>
-<a href="/autorestic/location/hooks">Hooks</a>
-<a href="/autorestic/location/exclude">Excluding Files</a>
-<a href="/autorestic/location/forget">Forget Policy</a>
-<a href="/autorestic/location/cron">Cron</a>
-<a href="/autorestic/location/docker">Docker Volumes</a></p></div></div><div class="collapse-0-0-7 "><script id="ITowATuoIl">(function(){function load(){if (window.__sdh_transport){window.__sdh_transport("ITowATuoIl", "fz894w7KG2/tX4kLbbA1Kg==", {});} }; if (document.readyState == 'complete') load(); else window.addEventListener('load', load); })()</script><div class="label" onclick="this.parentElement.classList.toggle('open')"><span class="text">Backend</span><span class="icon-font closed">chevron_right</span></div><div class="content"><p><a href="/autorestic/backend/overview">Overview</a>
-<a href="/autorestic/backend/available">Available Backends</a></p></div></div><div class="collapse-0-0-7 "><script id="uZkmwddyAM">(function(){function load(){if (window.__sdh_transport){window.__sdh_transport("uZkmwddyAM", "fz894w7KG2/tX4kLbbA1Kg==", {});} }; if (document.readyState == 'complete') load(); else window.addEventListener('load', load); })()</script><div class="label" onclick="this.parentElement.classList.toggle('open')"><span class="text">CLI</span><span class="icon-font closed">chevron_right</span></div><div class="content"><p><a href="/autorestic/cli/info">Info</a>
-<a href="/autorestic/cli/check">Check</a>
-<a href="/autorestic/cli/backup">Backup</a>
-<a href="/autorestic/cli/restore">Restore</a>
-<a href="/autorestic/cli/forget">Forget</a>
-<a href="/autorestic/cli/cron">Cron</a>
-<a href="/autorestic/cli/exec">Exec</a>
-<a href="/autorestic/cli/install">Install</a>
-<a href="/autorestic/cli/uninstall">Uninstall</a>
-<a href="/autorestic/cli/update">Update</a></p></div></div><p><a href="/autorestic/examples">Examples</a></p><p><a href="/autorestic/qa">QA</a></p><p><a href="/autorestic/contrib">Contributors</a></p></div><div class="search-0-0-13"><script id="GYYUHymBgV">(function(){function load(){if (window.__sdh_transport){window.__sdh_transport("GYYUHymBgV", "+SrlfVhZ/PRQ5WhUlZbTaA==", {"repo":"autorestic","user":"cupcakearmy","root":"docs/md","pick":"\\.md$","drop":"(^_)|(\\/_)"});} }; if (document.readyState == 'complete') load(); else window.addEventListener('load', load); })()</script></div></div><div class="footer-0-0-10"><div class="left"><script id="TxuSEUJbDE">(function(){function load(){if (window.__sdh_transport){window.__sdh_transport("TxuSEUJbDE", "XsNW3ht5ee+RmVUActEo9g==", {});} }; if (document.readyState == 'complete') load(); else window.addEventListener('load', load); })()</script></div><div class="main"><div class="inside"><a href="https://github.com/cupcakearmy/autorestic/" target="_blank">GitHub</a></div></div><div class="right"><script id="TjsjVMapDr">(function(){function load(){if (window.__sdh_transport){window.__sdh_transport("TjsjVMapDr", "Y1WWvCKxkgk1yh8xbCfXqw==", {});} }; if (document.readyState == 'complete') load(); else window.addEventListener('load', load); })()</script></div></div><script id="wOqKaBgDQf">(function(){function load(){if (window.__sdh_transport){window.__sdh_transport("wOqKaBgDQf", "v641FmLj+AeGp0uuFTI6ug==", {"namespace":"/autorestic"});} }; if (document.readyState == 'complete') load(); else window.addEventListener('load', load); })()</script></body></html>
--- a/docs/location/overview.md
+++ b/docs/location/overview.md
@@ -0,0 +1,27 @@
+# 🗂 Locations
+
+Locations can be seen as the input to the backup process. Generally this is simply a folder.
+The paths can be relative from the config file. A location can have multiple backends, so that the data is secured across multiple servers.
+
+```yaml | .autorestic.yml
+locations:
+  my-location-name:
+    from: path/to/backup
+    to:
+      - name-of-backend
+      - also-backup-to-this-backend
+```
+
+## `from`
+
+This is the source of the location.
+
+#### How are paths resolved?
+
+Paths can be absolute or relative. If relative they are resolved relative to the location of the config file. Tilde `~` paths are also supported for home folder resolution.
+
+## `to`
+
+This is einther a single backend or an array of backends. The backends have to be configured in the same config file.
+
+> :ToCPrevNext