File manager - Edit - /home/newsbmcs.com/public_html/static/img/logo/080_examples.html.tar
Back
usr/share/doc/restic/html/080_examples.html 0000644 00000065270 15030063066 0014565 0 ustar 00 <!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>Examples — 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="Participating" href="090_participating.html" /> <link rel="prev" title="Scripting" href="075_scripting.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"><a class="reference internal" href="040_backup.html">Backing up</a></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 current"><a class="current reference internal" href="#">Examples</a><ul> <li class="toctree-l2"><a class="reference internal" href="#setting-up-restic-with-amazon-s3">Setting up restic with Amazon S3</a><ul> <li class="toctree-l3"><a class="reference internal" href="#preface">Preface</a></li> <li class="toctree-l3"><a class="reference internal" href="#prerequisites">Prerequisites</a></li> <li class="toctree-l3"><a class="reference internal" href="#logging-into-aws">Logging into AWS</a></li> <li class="toctree-l3"><a class="reference internal" href="#creating-the-bucket">Creating the bucket</a></li> <li class="toctree-l3"><a class="reference internal" href="#creating-a-user">Creating a user</a></li> <li class="toctree-l3"><a class="reference internal" href="#initializing-the-restic-repository">Initializing the restic repository</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#backing-up-your-system-without-running-restic-as-root">Backing up your system without running restic as root</a><ul> <li class="toctree-l3"><a class="reference internal" href="#motivation">Motivation</a></li> <li class="toctree-l3"><a class="reference internal" href="#capabilities-on-linux">Capabilities on Linux</a></li> <li class="toctree-l3"><a class="reference internal" href="#full-backup-without-root">Full backup without root</a></li> </ul> </li> </ul> </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>Examples</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/080_examples.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="examples"> <h1>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h1> <section id="setting-up-restic-with-amazon-s3"> <h2>Setting up restic with Amazon S3<a class="headerlink" href="#setting-up-restic-with-amazon-s3" title="Permalink to this headline">¶</a></h2> <section id="preface"> <h3>Preface<a class="headerlink" href="#preface" title="Permalink to this headline">¶</a></h3> <p>This tutorial will show you how to use restic with AWS S3. It will show you how to navigate the AWS web interface, create an S3 bucket, create a user with access to only this bucket, and finally how to connect restic to this bucket.</p> </section> <section id="prerequisites"> <h3>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h3> <p>You should already have a <code class="docutils literal notranslate"><span class="pre">restic</span></code> binary available on your system that you can run. Furthermore, you should also have an account with <a class="reference external" href="https://aws.amazon.com/">AWS</a>. You will likely need to provide credit card details for billing purposes, even if you use their <a class="reference external" href="https://aws.amazon.com/free/">free-tier</a>.</p> </section> <section id="logging-into-aws"> <h3>Logging into AWS<a class="headerlink" href="#logging-into-aws" title="Permalink to this headline">¶</a></h3> <p>Point your browser to <a class="reference external" href="https://console.aws.amazon.com">https://console.aws.amazon.com</a> and log in using your AWS account. You will be presented with the AWS homepage:</p> <img alt="AWS Homepage" src="_images/01_aws_start.png" /> <p>By using the “Services” button in the upper left corder, a menu of all services provided by AWS can be opened:</p> <img alt="AWS Services Menu" src="_images/02_aws_menu.png" /> <p>For this tutorial, the Simple Storage Service (S3), as well as Identity and Access Management (IAM) are relevant.</p> </section> <section id="creating-the-bucket"> <h3>Creating the bucket<a class="headerlink" href="#creating-the-bucket" title="Permalink to this headline">¶</a></h3> <p>First, a bucket to store your backups in must be created. Using the “Services” menu, navigate to S3. In case you already have some S3 buckets, you will see a list of them here:</p> <img alt="List of S3 Buckets" src="_images/03_buckets_list_before.png" /> <p>Click the “Create bucket” button and choose a name and region for your new bucket. For the purpose of this tutorial, the bucket will be named <code class="docutils literal notranslate"><span class="pre">restic-demo</span></code> and reside in Frankfurt. Because the bucket name space is shared among all AWS users, the name <code class="docutils literal notranslate"><span class="pre">restic-demo</span></code> may not be available to you. Be creative and choose a unique bucket name.</p> <img alt="Create a Bucket" src="_images/04_bucket_create_start.png" /> <p>It is not necessary to configure any special properties or permissions of the bucket just yet. Therefore, just finish the wizard without making any further changes:</p> <img alt="Review Bucket Creation" src="_images/05_bucket_create_review.png" /> <p>The newly created <code class="docutils literal notranslate"><span class="pre">restic-demo</span></code> bucket will now appear on the list of S3 buckets:</p> <img alt="List With New Bucket" src="_images/06_buckets_list_after.png" /> </section> <section id="creating-a-user"> <h3>Creating a user<a class="headerlink" href="#creating-a-user" title="Permalink to this headline">¶</a></h3> <p>Use the “Services” menu of the AWS web interface to navigate to IAM. This will bring you to the IAM homepage. To create a new user, click on the “Users” menu entry on the left:</p> <img alt="IAM Home Page" src="_images/07_iam_start.png" /> <p>In case you already have set-up users with IAM before, you will see a list of them here. Use the “Add user” button at the top to create a new user:</p> <img alt="IAM User List" src="_images/08_user_list.png" /> <p>For this tutorial, the new user will be named <code class="docutils literal notranslate"><span class="pre">restic-demo-user</span></code>. Feel free to choose your own name that best fits your needs. This user will only ever access AWS through the <code class="docutils literal notranslate"><span class="pre">restic</span></code> program and not through the web interface. Therefore, “Programmatic access” is selected for “Access type”:</p> <img alt="Choose User Name and Access Type" src="_images/09_user_name.png" /> <p>During the next step, permissions can be assigned to the new user. To use this user with restic, it only needs access to the <code class="docutils literal notranslate"><span class="pre">restic-demo</span></code> bucket. Select “Attach existing policies directly”, which will bring up a list of pre-defined policies below. Afterwards, click the “Create policy” button to create a custom policy:</p> <img alt="Assign a Policy" src="_images/10_user_pre_policy.png" /> <p>A new browser window or tab will open with the policy wizard. In Amazon IAM, policies are defined as JSON documents. For this tutorial, the “Visual editor” will be used to generate a policy:</p> <img alt="Create a New Policy" src="_images/11_policy_start.png" /> <p>For restic to work, two permission statements must be created using the visual policy editor. The first statement is set up as follows:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Service</span><span class="p">:</span> <span class="n">S3</span> <span class="n">Allow</span> <span class="n">Actions</span><span class="p">:</span> <span class="n">DeleteObject</span><span class="p">,</span> <span class="n">GetObject</span><span class="p">,</span> <span class="n">PutObject</span> <span class="n">Resources</span><span class="p">:</span> <span class="n">arn</span><span class="p">:</span><span class="n">aws</span><span class="p">:</span><span class="n">s3</span><span class="p">:::</span><span class="n">restic</span><span class="o">-</span><span class="n">demo</span><span class="o">/*</span> </pre></div> </div> <p>This statement allows restic to create, read and delete objects inside the S3 bucket named <code class="docutils literal notranslate"><span class="pre">restic-demo</span></code>. Adjust the bucket’s name to the name of the bucket you created earlier. Next, add a second statement using the “Add additional permissions” button:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Service</span><span class="p">:</span> <span class="n">S3</span> <span class="n">Allow</span> <span class="n">Actions</span><span class="p">:</span> <span class="n">ListBucket</span><span class="p">,</span> <span class="n">GetBucketLocation</span> <span class="n">Resource</span><span class="p">:</span> <span class="n">arn</span><span class="p">:</span><span class="n">aws</span><span class="p">:</span><span class="n">s3</span><span class="p">:::</span><span class="n">restic</span><span class="o">-</span><span class="n">demo</span> </pre></div> </div> <p>Again, substitute <code class="docutils literal notranslate"><span class="pre">restic-demo</span></code> with the actual name of your bucket. Note that, unlike before, there is no <code class="docutils literal notranslate"><span class="pre">/*</span></code> after the bucket name. This statement allows restic to list the objects stored in the <code class="docutils literal notranslate"><span class="pre">restic-demo</span></code> bucket and to query the bucket’s region.</p> <p>Continue to the next step by clicking the “Review policy” button and enter a name and description for this policy. For this tutorial, the policy will be named <code class="docutils literal notranslate"><span class="pre">restic-demo-policy</span></code>. Click “Create policy” to finish the process:</p> <img alt="Policy Review" src="_images/13_policy_review.png" /> <p>Go back to the browser window or tab where you were previously creating the new user. Click the button labeled “Refresh” above the list of policies to make sure the newly created policy is available to you. Afterwards, use the search function to search for the <code class="docutils literal notranslate"><span class="pre">restic-demo-policy</span></code>. Select this policy using the checkbox on the left. Then, continue to the next step.</p> <img alt="Attach Policy to User" src="_images/14_user_attach_policy.png" /> <p>The next page will present an overview of the user account that is about to be created. If everything looks good, click “Create user” to complete the process:</p> <img alt="User Creation Review" src="_images/15_user_review.png" /> <p>After the user has been created, its access credentials will be displayed. They consist of the “Access key ID” (think user name), and the “Secret access key” (think password). Copy these down to a safe place.</p> <img alt="User Credentials" src="_images/16_user_created.png" /> <p>You have now completed the configuration in AWS. Feel free to close your web browser now.</p> </section> <section id="initializing-the-restic-repository"> <h3>Initializing the restic repository<a class="headerlink" href="#initializing-the-restic-repository" title="Permalink to this headline">¶</a></h3> <p>Open a terminal and make sure you have the <code class="docutils literal notranslate"><span class="pre">restic</span></code> binary ready. First, choose a password to encrypt your backups with. In this tutorial, <code class="docutils literal notranslate"><span class="pre">apg</span></code> is used for this purpose:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>apg -a <span class="m">1</span> -m <span class="m">32</span> -n <span class="m">1</span> -M NCL <span class="go">I9n7G7G0ZpDWA3GOcJbIuwQCGvGUBkU5</span> </pre></div> </div> <p>Note this password somewhere safe along with your AWS credentials. Next, the configuration of restic will be placed into environment variables. This will include sensitive information, such as your AWS secret and repository password. Therefore, make sure the next commands <strong>do not</strong> end up in your shell’s history file. Adjust the contents of the environment variables to fit your bucket’s name and your user’s API credentials.</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">unset</span> HISTFILE <span class="gp">$ </span><span class="nb">export</span> <span class="nv">RESTIC_REPOSITORY</span><span class="o">=</span><span class="s2">"s3:https://s3.amazonaws.com/restic-demo"</span> <span class="gp">$ </span><span class="nb">export</span> <span class="nv">AWS_ACCESS_KEY_ID</span><span class="o">=</span><span class="s2">"AKIAJAJSLTZCAZ4SRI5Q"</span> <span class="gp">$ </span><span class="nb">export</span> <span class="nv">AWS_SECRET_ACCESS_KEY</span><span class="o">=</span><span class="s2">"LaJtZPoVvGbXsaD2LsxvJZF/7LRi4FhT0TK4gDQq"</span> <span class="gp">$ </span><span class="nb">export</span> <span class="nv">RESTIC_PASSWORD</span><span class="o">=</span><span class="s2">"I9n7G7G0ZpDWA3GOcJbIuwQCGvGUBkU5"</span> </pre></div> </div> <p>After the environment is set up, restic may be called to initialize the repository:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./restic init <span class="go">created restic backend b5c661a86a at s3:https://s3.amazonaws.com/restic-demo</span> <span class="go">Please note that knowledge of your password is required to access</span> <span class="go">the repository. Losing your password means that your data is</span> <span class="go">irrecoverably lost.</span> </pre></div> </div> <p>restic is now ready to be used with AWS S3. Try to create a backup:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>dd <span class="k">if</span><span class="o">=</span>/dev/urandom <span class="nv">bs</span><span class="o">=</span>1M <span class="nv">count</span><span class="o">=</span><span class="m">10</span> <span class="nv">of</span><span class="o">=</span>test.bin <span class="go">10+0 records in</span> <span class="go">10+0 records out</span> <span class="go">10485760 bytes (10 MB, 10 MiB) copied, 0,0891322 s, 118 MB/s</span> <span class="gp">$ </span>./restic backup test.bin <span class="go">scan [/home/philip/restic-demo/test.bin]</span> <span class="go">scanned 0 directories, 1 files in 0:00</span> <span class="gp">[0:04] 100.00% </span><span class="m">2</span>.500 MiB/s <span class="m">10</span>.000 MiB / <span class="m">10</span>.000 MiB <span class="m">1</span> / <span class="m">1</span> items ... ETA <span class="m">0</span>:00 <span class="go">duration: 0:04, 2.47MiB/s</span> <span class="go">snapshot 10fdbace saved</span> <span class="gp">$ </span>./restic snapshots <span class="go">ID Date Host Tags Directory</span> <span class="go">----------------------------------------------------------------------</span> <span class="go">10fdbace 2017-03-26 16:41:50 blackbox /home/philip/restic-demo/test.bin</span> </pre></div> </div> <p>A snapshot was created and stored in the S3 bucket. By default backups to AWS S3 will use the <code class="docutils literal notranslate"><span class="pre">STANDARD</span></code> storage class. Available storage classes include <code class="docutils literal notranslate"><span class="pre">STANDARD</span></code>, <code class="docutils literal notranslate"><span class="pre">STANDARD_IA</span></code>, <code class="docutils literal notranslate"><span class="pre">ONEZONE_IA</span></code>, <code class="docutils literal notranslate"><span class="pre">INTELLIGENT_TIERING</span></code>, and <code class="docutils literal notranslate"><span class="pre">REDUCED_REDUNDANCY</span></code>. A different storage class could have been specified in the above command by using <code class="docutils literal notranslate"><span class="pre">-o</span></code> or <code class="docutils literal notranslate"><span class="pre">--option</span></code>:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./restic backup -o s3.storage-class<span class="o">=</span>REDUCED_REDUNDANCY test.bin </pre></div> </div> <p>This snapshot may now be restored:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>mkdir restore <span class="gp">$ </span>./restic restore 10fdbace --target restore <span class="go">restoring <Snapshot 10fdbace of [/home/philip/restic-demo/test.bin] at 2017-03-26 16:41:50.201418102 +0200 CEST by philip@blackbox> to restore</span> <span class="gp">$ </span>ls restore/ <span class="go">test.bin</span> </pre></div> </div> <p>The snapshot was successfully restored. This concludes the tutorial.</p> </section> </section> <section id="backing-up-your-system-without-running-restic-as-root"> <h2>Backing up your system without running restic as root<a class="headerlink" href="#backing-up-your-system-without-running-restic-as-root" title="Permalink to this headline">¶</a></h2> <section id="motivation"> <h3>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h3> <p>Creating a complete backup of a machine requires a privileged process that is able to read all files. On UNIX-like systems this is traditionally the <code class="docutils literal notranslate"><span class="pre">root</span></code> user. Processes running as root have superpower. They cannot only read all files but do also have the power to modify the system in any possible way.</p> <p>With great power comes great responsibility. If a process running as root malfunctions, is exploited, or simply configured in a wrong way it can cause any possible damage to the system. This means you only want to run programs as root that you trust completely. And even if you trust a program, it is good and common practice to run it with the least possible privileges.</p> </section> <section id="capabilities-on-linux"> <h3>Capabilities on Linux<a class="headerlink" href="#capabilities-on-linux" title="Permalink to this headline">¶</a></h3> <p>Fortunately, Linux has functionality to divide root’s power into single separate <em>capabilities</em>. You can remove these from a process running as root to restrict it. And you can add capabilities to a process running as a normal user, which is what we are going to do.</p> </section> <section id="full-backup-without-root"> <h3>Full backup without root<a class="headerlink" href="#full-backup-without-root" title="Permalink to this headline">¶</a></h3> <p>To be able to completely backup a system, restic has to read all the files. Luckily Linux knows a capability that allows precisely this. We can assign this single capability to restic and then run it as an unprivileged user.</p> <p>First we create a new user called <code class="docutils literal notranslate"><span class="pre">restic</span></code> that is going to create the backups:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">root@a3e580b6369d:/# </span>useradd -m restic </pre></div> </div> <p>Then we download and install the restic binary into the user’s home directory (please adjust the URL to refer to the latest restic version).</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">root@a3e580b6369d:/# </span>mkdir ~restic/bin <span class="gp">root@a3e580b6369d:/# </span>curl -L https://github.com/restic/restic/releases/download/v0.9.6/restic_0.9.6_linux_amd64.bz2 <span class="p">|</span> bunzip2 > ~restic/bin/restic </pre></div> </div> <p>Before we assign any special capability to the restic binary we restrict its permissions so that only root and the newly created restic user can execute it. Otherwise another - possibly untrusted - user could misuse the privileged restic binary to circumvent file access controls.</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">root@a3e580b6369d:/# </span>chown root:restic ~restic/bin/restic <span class="gp">root@a3e580b6369d:/# </span>chmod <span class="m">750</span> ~restic/bin/restic </pre></div> </div> <p>Finally we can use <code class="docutils literal notranslate"><span class="pre">setcap</span></code> to add an extended attribute to the restic binary. On every execution the system will read the extended attribute, interpret it and assign capabilities accordingly.</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">root@a3e580b6369d:/# </span>setcap <span class="nv">cap_dac_read_search</span><span class="o">=</span>+ep ~restic/bin/restic </pre></div> </div> <div class="admonition important"> <p class="admonition-title">Important</p> <p>The capabilities of the <code class="docutils literal notranslate"><span class="pre">setcap</span></code> command only applies to this specific copy of the restic binary. If you run <code class="docutils literal notranslate"><span class="pre">restic</span> <span class="pre">self-update</span></code> or in any other way replace or update the binary, the capabilities you added above will not be in effect for the new binary. To mitigate this, simply run the <code class="docutils literal notranslate"><span class="pre">setcap</span></code> command again, to make sure that the new binary has the same and intended capabilities.</p> </div> <p>From now on the user <code class="docutils literal notranslate"><span class="pre">restic</span></code> can run restic to backup the whole system.</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">root@a3e580b6369d:/# </span>sudo -u restic /home/restic/bin/restic --exclude<span class="o">={</span>/dev,/media,/mnt,/proc,/run,/sys,/tmp,/var/tmp<span class="o">}</span> -r /tmp backup / </pre></div> </div> </section> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="075_scripting.html" class="btn btn-neutral float-left" title="Scripting" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="090_participating.html" class="btn btn-neutral float-right" title="Participating" 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