diff --git a/README.md b/README.md index 30f62e9..cb6f031 100644 --- a/README.md +++ b/README.md @@ -20,32 +20,39 @@ The script uses rsync to actually run the backup, so you will have to install it sudo pacman -Syu rsync ``` -Optional dependencies are systemd-python to enable using systemd journal for logging, dbus-python for desktop notifications, and paramiko for remote backup. +Optional dependencies are systemd-python to enable using systemd journal for logging, dbus-python for desktop notifications, and paramiko (version 3.2 or later) for remote backup. ## Install -To install the program, first clone the repository: +For Arch Linux and Arch-based distros, two packages are available in the AUR (aur.archlinux.org): +- **simple_backup** for the release version +- **simple_backup-git** for the git version + +To install it from source, first clone the repository: ```bash git clone https://git.shouldnt.work/fuxino/simple_backup.git ``` -Then install the tools required to build the package: - -```bash -pip install --upgrade build -``` - -Finally, run: +Then build the package (this requires the Python `build` module, e.g. the python-build package on Arch Linux): ```bash cd simple_backup python -m build --wheel -python -m pip install dist/*.whl ``` -For Arch Linux and Arch-based distros, two packages are available in the AUR (aur.archlinux.org): -- **simple_backup** for the release version -- **simple_backup-git** for the git version +Many distributions don't allow installing packages with pip into the system Python ("externally-managed-environment" error). +In that case, install the wheel in a virtual environment, for example with pipx: + +```bash +pipx install dist/*.whl +``` + +Optional dependencies can be installed as extras, for example `pipx install 'dist/simple_backup--py3-none-any.whl[REMOTE]'` (available extras: JOURNAL, NOTIFICATIONS, REMOTE). + +## Running as root +To back up files that your user can't read, run simple_backup with sudo or doas. +In that case the user who ran the command is detected automatically, so that '~' (in the inputs and in the default configuration file path) refers to that user's home directory, not root's. +When running as root in other ways (e.g. from a systemd service), specify the user with the --user (or -u) argument. ## Old backups The number of old backups to keep can be set with the --keep (or -k) argument (or in the configuration file). @@ -57,8 +64,16 @@ The only rsync error that is ignored is return code 24 (source files vanished du > This feature is experimental It's possible to use a remote server as destination for the backup. Just use the --ssh-user and --ssh-host arguments (or set them in the configuration file). +Both are required: if only one of them is set, simple_backup exits with an error. For this to work, rsync must be installed on the server too. +The output directory is a path on the server. A leading '~' and relative paths refer to the user's home directory on the server. +On the command line, quote '~' so that your local shell doesn't expand it: + +```bash +simple_backup --ssh-host server --ssh-user user -o '~/backups' +``` + ### Server authentication The best way to handle the authentication is to have an ssh agent running on your system, otherwise if a passphrase is necessary to unlock the ssh key, it will be necessary to enter it more than once. If needed, it's possible to specify the ssh key location with the --keyfile argument or in the configuration file.