Add remaining articles, redirects and images.

Author: m3nu

_config.yml

@@ -4,6 +4,7 @@ baseurl: ""
 url: "https://docs.borgbase.com"
 
 permalink: pretty
+include: ["_redirects"]
 exclude: ["README.md", "Rakefile"]
 
 search_enabled: true

_redirects

@@ -0,0 +1,5 @@
+/linux/how-to-restore-files-from-a-borg-backup-using-the-command-line/  /restore
+/backup-strategy/steps-with-template/   /strategy
+/macos/how-to-backup-your-mac-using-the-vorta-backup-gui/   /setup/vorta
+/linux/how-to-create-a-ssh-key-on-macos-or-ubuntu-debian/   /faq/ssh
+/linux/setup-borg-command-line/ /setup/cli

automation.md

@@ -0,0 +1,53 @@
+---
+title: Automation
+nav_order: 4
+layout: page
+description: ""
+---
+# How to Incorporate BorgBase into your Automated Deployment Workflow
+Modern IT would be impossible without automation. We provide the tools to make reliable backups a part of your deployment workflow.
+
+## Ansible Role for Borg Backup Client
+
+This role will install Borg Borgmatic and a cron job on a Linux (tested on Ubuntu/Debian/CentOS/Fedora) client. Learn more on the [Github page of the project](https://github.com/borgbase/ansible-role-borgbackup).
+
+## Ansible Module to set up BorgBase Repo
+
+BorgBase user [@adhawkinsgh](https://twitter.com/adhawkinsgh/) created a range of Ansible modules that interact with the BorgBase API for a fully automated setup. These roles will also set up new repos and SSH keys with BorgBase.
+
+For details see the [Github repo](https://github.com/adhawkins/ansible-borgbase) or the [in-file documentation](https://github.com/adhawkins/ansible-borgbase/blob/master/borgbase_repo.py).
+
+## API
+
+The GraphQL API used by the web interface is also available to automate tasks, like adding keys and repos.
+
+You can use the Python sample client to communicate with this API or implement your own. The full documentation can be accessed via the GraphiQL interface at [https://api.borgbase.com/graphql](https://api.borgbase.com/graphql).
+
+Interfacing with GraphQL is relatively easy and can be done with any tool or library that can do POST requests. To get you started we provide the following [Python client](https://github.com/borgbase/borgbase-api-client) as example. It simply wraps the Python `requests` package and provides sample GraphQL queries.
+
+Example usage:
+
+```
+from borgbase_api_client.client import GraphQLClient
+from borgbase_api_client.mutations import *
+
+client = GraphQLClient()
+client.login(email='xxx', password='xxx')
+
+new_key_vars = {
+    'name': 'Key for VM-004',
+    'keyData': 'ssh-ed25519 AAAAC3Nz......aLqRJw+dl/E+2BJ xxx@yyy'
+}
+res = client.execute(SSH_ADD, new_key_vars)
+new_key_id = res['data']['sshAdd']['keyAdded']['id']
+
+new_repo_vars = {
+    'name': 'VM-004-test',
+    'quotaEnabled': False,
+    'appendOnlyKeys': [new_key_id],
+    'region': 'us'
+}
+res = client.execute(REPO_ADD, new_repo_vars)
+new_repo_path = res['data']['repoAdd']['repoAdded']['repoPath']
+print('Added new repo with path:', new_repo_path)
+```

faq/faq.md

@@ -0,0 +1,7 @@
+---
+title: FAQ
+nav_order: 6
+layout: page
+description: ""
+has_children: true
+---

faq/ssh.md

@@ -0,0 +1,75 @@
+---
+title: New SSH Key
+nav_order: 1
+layout: page
+parent: FAQ
+description: ""
+---
+# How to Create a SSH Key on macOS or Ubuntu/Debian
+
+### Introduction
+SSH (or Secure Shell) was invented as a more secure replacement for **telnet**. It is used to connect to a remote server and run command, transfer files or forward traffic. If you do anything remotely related to server or websites, you probably heard about it.
+
+BorgBackup also uses SSH to securely connect to a backup server and transfer files. It does this by starting another server on the remote end, which makes it quicker than using SFTP (a subset of SSH to transfer files) directly.
+
+To use SSH, you need a keypair, which consists of a public- and a private key. The private key should always stay on your local machine. The public key can be added to remote services (like BorgBase), so you can authenticate yourself to the remote service. This is more convenient and secure than using a password because a key is much longer than a typical password.
+
+## Step 1 – Ensure OpenSSH is available
+OpenSSH is the default SSH server- and client used on most Linux distributions and on macOS. It comes with utilities to generate keys. It's already pre-installed on macOS. On Ubuntu or Debian it will be installed most of the time. Run the following command to make sure it works:
+
+```
+$ ssh-keygen
+```
+
+If OpenSSH is already installed, you will see output like this. Cancel the command with **Ctrl-C** and proceed to step 2.
+<div class='code-label'>ssh-keygen sample output</div>
+```
+Generating public/private rsa key pair.
+Enter file in which to save the key (/Users/manu/.ssh/id_rsa):
+```
+
+If the above command gives an error, you can still install OpenSSH using this command on Ubuntu or Debian. On other distributions this may differ.
+```
+$ apt-get install openssh-client
+```
+
+## Step 2 – Create Keypair
+As computers get faster, encryption needs to adjust. That's why the recommended key algorithm and key length has changed over the years. As of 2018 the recommended key setting[^1] [^2] is:
+
+```
+$ ssh-keygen -t ed25519 -a 100
+```
+
+This will generate an Ed25519 key, which is shorter and faster than a comparable RSA key. If you prefer to use the older RSA format or because you have an older OpenSSH version, you can also use:
+
+```
+$ ssh-keygen -t rsa -b 4096 -o -a 100
+```
+
+After choosing an appropriate key format- and length, the command will ask you a series of questions regarding place to save the key and password. Using the default location in `~/.ssh/id_ed25519` or `~/.ssh/id_rsa` is generally OK and OpenSSH will easily find keys later. Optionally you can also use a password and store it in macOS' Keychain later.
+
+## Step 3 – Using the Public Key Part for Backups
+When done, you will find your newly-generated key in `~/.ssh`. To view your public key:
+```
+$ cat ~/.ssh/id_ed25519.pub
+```
+
+Or if you chose a RSA key
+```
+$ cat ~/.ssh/id_rsa.pub
+```
+
+This will print your **public** key. (Please don't upload your private key.)
+```
+ssh-ed25519 AAAAC3NzaC1lZDI...LqRJw+dl/E+2BJ manu@nyx
+```
+
+You can now simply copy it to the clipboard and add it to [BorgBase.com](https://www.borgbase.com) under **Account** > **SSH Keys**.
+
+When adding a new backup repository, you can choose any of your SSH keys. It's good practice to have one keypair per-server or machine. So each machine can only access its own backups.
+
+During repo initialization, Borg will simply use the key without any further settings.
+
+### References
+[^1]: [Secure Secure Shell](https://stribika.github.io/2015/01/04/secure-secure-shell.html)
+[^2]: [What are ssh-keygen best practices?](https://security.stackexchange.com/questions/143442/what-are-ssh-keygen-best-practices)

img/strategy/Screenshot-2018-12-07-at-12.43.34.png

@@ -6,18 +6,33 @@ description: ""
 permalink: /
 ---
 
-# Focus on writing good documentation
+# BorgBase Documentation Centre
 {: .fs-9 }
 
-Just the Docs gives your documentation a jumpstart with a responsive Jekyll theme that is easily customizable and hosted on GitHub Pages.
+All the resources you need to develop a comprehensive backup strategy with [BorgBase](https://www.borgbase.com) and apply it in your environment.
 {: .fs-6 .fw-300 }
 
-[Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/pmarsceill/just-the-docs){: .btn .fs-5 .mb-4 .mb-md-0 }
-
 ---
 
-## Getting started
+## Steps to Get Started
+
+### Your Backup Strategy and Data
+Even the best tools need a sound strategy. Get started by creating an inventory of your important data assets, catalog where they are stored and discover potential issues in backup workflows. [More...](strategy)
+
+### Sign up with BorgBase
+BorgBase is a dedicated hosting service for Borg backup repositories. It allows you to manage all your backups in one place and use powerful Borg features, like append-only mode in a simple way. 
+
+### Local Borg Setup
+Borg Backup works with most operating systems, like Linux, macOS and Windows WSL. For servers and headless systems, look into our [Command Line Setup Guide]. For desktops, we recommend using our desktop client, [Vorta](setup/vorta).
+
+### Automation
+Use our GraphQL API or Ansible role to automate repeated setup steps on client endpoints. [More...](automation)
+
+### Restore Data from a Backup
+How to restore files from a Borg Backup. [More...](restore)
+
+---
 
-### Dependencies
+## Contribute and Customize
 
-Just the Docs is built for [Jekyll](https://jekyllrb.com), a static site generator. View the [quick start guide](https://jekyllrb.com/docs/) for more information. Just the Docs requires no special Jekyll plugins and can run on GitHub Pages' standard Jekyll compiler.
+Borg and most other tools we provide are fully open source. You can customize and improve them to a degree that wouldn't be possible with commercial products. Look at our [Github page](https://github.com/borgbase) for ongoing open source development.

img/strategy/Screenshot-2018-12-07-at-12.43.45.png

@@ -0,0 +1,153 @@
+---
+title: Restore
+nav_order: 5
+layout: page
+description: "Learn to browse and mount a Borg repository and then restore file in bulk using the `borg extract` command."
+---
+
+# How to Restore Files from a Borg Backup Using the Command Line
+
+Note: You should be comfortable using the command line. If you prefer a graphical, client, look into our [Vorta Tutorial](/macos/how-to-backup-your-mac-using-the-vorta-backup-gui/) instead. These instructions should work on macOS and popular Linux flavors, like Debian, Ubuntu, as well as Red Hat, Fedora and CentOS.
+
+## Goals
+This article assumes that you have set up a backup workflow to a local or remote Borg repository. Now you would like to restore files from it. Borg offers two different ways to restore files. The `borg mount` command allows you to browse multiple archives and find exactly the file you are looking for. Due to some overhead from the FUSE mount library, the speed can be slower when restoring a large number of files. This is where `borg extract` comes in. If you already know which files you need, it can quickly restore large quantities of data including all metadata.
+
+## Prerequisites
+You should already have Borg installed and know how to use the command line. If you didn't install Borg yet, have a look at [this previous guide](https://docs.borgbase.com/linux/setup-borg-command-line/).
+
+## Step 1 - Set up FUSE
+The FUSE library allows mounting arbitrary file systems into user space. It's available for all popular systems. The [official Borg docs](https://borgbackup.readthedocs.io/en/stable/installation.html) have a detailed overview for each system. You will need two parts: the actual FUSE library and Python wrappers for it.
+
+**For macOS**: First install the FUSE library from Homebrew.
+
+```
+$ brew cask install osxfuse
+```
+
+**For Debian/Ubuntu**: The FUSE library is available from the main package repository.
+
+```
+$ sudo apt-get install libfuse-dev fuse pkg-config
+```
+
+**For Red Hat/CentOS**: FUSE is available from the official repository.
+```
+$ yum install fuse-devel fuse pkgconfig
+```
+
+## Step 2 - Install Python FUSE Bindings (optional)
+The `llfuse` [package](https://pypi.org/project/llfuse/) provides Python bindings for FUSE. If you are using the standalone binary of Borg, it already includes FUSE bindings and you can proceed to the next step. If you installed Borg from PyPi, you can install it as follows:
+
+### Install Python FUSE library
+Be sure to install it into the same Python environment as Borg itself.
+
+```
+$ pip install llfuse
+```
+
+If you installed Borg as user-package using the system Python:
+
+```
+$ pip install --user llfuse
+```
+
+Or you could install it together with Borg
+
+```
+$ pip install borgbackup[fuse]
+```
+
+## Step 3 - Validate Installation and Repository
+Next make sure everything is installed properly and you have access to the backup repo.
+
+```
+$ borg info [email protected]:repo
+```
+
+You should see output similar to this. If you get an error, be sure that you have access to the repository. If your repo is encrypted, it will also ask you for the password or keyfile.
+
+```
+Repository ID: daf2e2b94a1b57f0effc96939813ef58d0af04414f92f87c3e092a99adaa90eb
+Location: ssh://[email protected]/./repo
+Encrypted: Yes (repokey BLAKE2b)
+Cache: /Users/manu/.cache/borg/daf2e2b94a1b57f0effc96939813ef58d0af04414f92f87c3e092a99adaa90eb
+Security dir: /Users/manu/.config/borg/security/daf2e2b94a1b57f0effc96939813ef58d0af04414f92f87c3e092a99adaa90eb
+------------------------------------------------------------------------------
+                       Original size      Compressed size    Deduplicated size
+All archives:              665.90 MB            577.88 MB             68.41 MB
+
+                       Unique chunks         Total chunks
+Chunk index:                    1359                 6711
+```
+
+If you installed Borg and llfuse via PIP, you can also validate the packages are installed
+
+```
+$ pip freeze | grep llfuse
+$ pip freeze | grep borgbackup
+```
+
+Step 4 - Using `borg mount` to Browse and Restore Files
+The `borg mount` command allows for simple browsing and restoring individual files without their complete metadata. This is great to restore a few documents or images.
+
+First create a new folder as mount point. Since we're not working with root permissions, we won't use `/mnt`. Instead any empty folder in your home directory will suffice.
+
+```
+$ mkdir borg-mnt
+```
+
+Next mount the whole repository into the newly created folder. This will give us a view of *all* archives in the repository.
+
+```
+$ borg mount [email protected]:repo borg-mount
+```
+
+If there was no error, you should now see all your archives in the `borg-mount` folder:
+
+```
+$ ls -l borg-mount
+```
+
+Depending on the archive names used, the output could look like this.
+
+```
+drwxr-xr-x  1 manu  staff  0 Feb 16 12:04 nyx2-test-repo-2019-02-16T12:04:06
+drwxr-xr-x  1 manu  staff  0 Mar  5 13:12 nyx2-test-repo-2019-03-05T13:12:04
+drwxr-xr-x  1 manu  staff  0 Mar 19 22:36 nyx2-test-repo-2019-03-19T22:36:07
+drwxr-xr-x  1 manu  staff  0 Mar 25 23:29 nyx2-test-repo-2019-03-25T23:29:35
+drwxr-xr-x  1 manu  staff  0 Mar 26 23:02 nyx2-test-repo-2019-03-26T23:01:57
+drwxr-xr-x  1 manu  staff  0 Mar 27 09:21 nyx2-test-repo-2019-03-27T09:21:42
+```
+
+You can now browse this folder structure and copy the files you need.
+
+## Step 5 - Using `borg extract` to Bulk Restore Files
+FUSE can be slow for a large number of files and it can't restore metadata. For this reason, Borg includes a second command for fast bulk-restoring – `borg extract`.
+
+To use it, you will need to know the precise path and archive name to restore. The [`borg mount`](https://borgbackup.readthedocs.io/en/stable/usage/extract.html) command can be helpful for this.
+
+Assuming we got the archive name and path from the previous step, a possible `borg extract` command could be
+
+```
+$ borg extract \
+    --dry-run --list \
+    [email protected]:repo::nyx2-test-repo-2019-02-16T12:04:06 \
+    /Users/manu/Documents/financial
+```
+
+Due to the `--dry-run` and `--list` arguments this will print a list of files to be restored, but won't actually restore any files. To actually restore files, remove `--dry-run`.
+
+The last part of the command gives the path you're looking to restore. If you pass no paths, then *all* the data will be restored.
+
+Borg will restore your files to the current working directory. So be sure you are in the right place before running the command for real. To restore all the data from a specific snapshot to the current directory:
+
+```
+$ borg extract \
+    --list \
+    [email protected]:repo::nyx2-test-repo-2019-02-16T12:04:06
+```
+
+### Conclusion
+Hopefully this guide gave you a good overview of possible restore options for Borg. First we looked at installing required FUSE libraries to comfortably browse a whole repository. In addition, we used the `borg extract` command to quickly restore many files including their metadata.
+
+If you're looking to complement your backup workflow with cost-effective offsite backups, also look into [BorgBase.com](https://www.borgbase.com). There is a free tier of 5 GB for life. Paid plan start at $2/month or $.005/GB for larger plans. We also offer custom solutions to enterprise customers. This includes setting up local backup agents or evaluating your whole backup strategy. Contact [[email protected]](mailto:[email protected]) for more.

img/vorta/Screenshot-2018-11-02-at-19.56.04-300x188.png

@@ -1,8 +1,13 @@
 ---
 title: Setup
-nav_order: 2
+nav_order: 3
 layout: page
 description: ""
 permalink: /setup
 has_children: true
----
+---
+# Setting up Borg for Backups to BorgBase
+
+Borg is a lightweight backup client that you install locally to prepare your data before sending it to BorgBase for storage. Borg will deduplicate, compress and encrypt your files before sending them to us.
+
+There are many ways to use Borg on your computer. Some popular ways are explained in the pages below. See *Command Line* for ways to set up borg on headless systems, like a NAS or a remote server. For desktops we offer Vorta, our desktop client. It provides a graphical user interface around Borg and integrates with your desktop environment to make creating, browsing and restoring backups easier.