From b540e63c0ed0450e0c4c3f8ffe7de186f845c223 Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Sun, 17 Sep 2023 22:46:33 -0700 Subject: [PATCH] Updated documentation so "sudo borgmatic" works for pipx borgmatic installations (#757). --- NEWS | 1 + docs/how-to/develop-on-borgmatic.md | 1 + docs/how-to/set-up-backups.md | 47 +++++++++++++++++++++++------ 3 files changed, 39 insertions(+), 10 deletions(-) diff --git a/NEWS b/NEWS index 8e24ca9..948ca07 100644 --- a/NEWS +++ b/NEWS @@ -6,6 +6,7 @@ format. * #754: Fix error handling to log command output as one record per line instead of truncating too-long output and swallowing the end of some Borg error messages. + * #757: Updated documentation so "sudo borgmatic" works for pipx borgmatic installations. * Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip. See the documentation for more information: https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation diff --git a/docs/how-to/develop-on-borgmatic.md b/docs/how-to/develop-on-borgmatic.md index d71cdb8..f731c24 100644 --- a/docs/how-to/develop-on-borgmatic.md +++ b/docs/how-to/develop-on-borgmatic.md @@ -31,6 +31,7 @@ changes work: ```bash cd borgmatic +pipx ensurepath pipx install --editable . ``` diff --git a/docs/how-to/set-up-backups.md b/docs/how-to/set-up-backups.md index aa8176d..922e2a1 100644 --- a/docs/how-to/set-up-backups.md +++ b/docs/how-to/set-up-backups.md @@ -7,6 +7,8 @@ eleventyNavigation: --- ## Installation +### Prerequisites + First, [install Borg](https://borgbackup.readthedocs.io/en/stable/installation.html), at least version 1.1. borgmatic does not install Borg automatically so as to avoid @@ -18,31 +20,56 @@ Python applications on your system. If you have trouble installing pipx with pip, then you can install a system package instead. E.g. on Ubuntu or Debian, run: -``` +```bash sudo apt update sudo apt install pipx -sudo pipx ensurepath ``` -Finally, install borgmatic with pipx by running the following command: +### Root install + +If you want to run borgmatic on a schedule with privileged access to your +files, then you should install borgmatic as the root user by running the +following commands: ```bash +sudo pipx ensurepath sudo pipx install borgmatic ``` -Check whether all of this worked with: +Check whether this worked with: ```bash -sudo borgmatic --version +sudo su - +borgmatic --version ``` If borgmatic is properly installed, that should output your borgmatic version. +And if you'd also like `sudo borgmatic` to work, keep reading! -Many users need to backup system files that require privileged access, so -these instructions install and run borgmatic as the root user. But if you -don't need to backup such files, you're welcome to install and run borgmatic -as a non-root user. To do that, run the `pipx` and `borgmatic` commands -above without `sudo`. + +### Non-root install + +If you only want to run borgmatic as a non-root user (without privileged file +access) *or* you want to make `sudo borgmatic` work so borgmatic runs as root, +then install borgmatic as a non-root user by running the following commands as +that user: + +```bash +pipx ensurepath +pipx install borgmatic +``` + +This should work even if you've also installed borgmatic as the root user. + +Check whether this worked with: + +```bash +borgmatic --version +``` + +If borgmatic is properly installed, that should output your borgmatic version. +You can also try `sudo borgmatic --version` if you intend to run borgmatic +with `sudo`. ### Other ways to install