From a101fb8fed2288cfff08e3748f657e955b8a9ea6 Mon Sep 17 00:00:00 2001 From: Fabio Forni Date: Sun, 5 Nov 2023 15:17:53 +0100 Subject: [PATCH] README.md: Update --- README.md | 27 +++++++++------------------ 1 file changed, 9 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index e717718..bd67c93 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,9 @@ Backee is configuration restorer for Unix and Windows computers. It reads a series of `service.yaml` files that contain operating system dependencies, dependencies among other services and POSIX or Powershell scripts (the latter on Windows). Such sections are then used to restore services that a user wanted to backup, right at your fingertip. -It also possible to restore files without scripts. The `links` directory symbolic-links files to their destination path, while the `data` directory *copies* files, optionally by editing it using the Go template engine, so that a file could be customized for a particular platform on-the-fly. You can think Backee as an advanced dotfiles manager, whilst easy to use with its declarative definition files. +It also possible to restore files without scripts. The `links` step symbolic-links files to their destination path, while the `copies` step *copies* files, optionally by editing them using a template engine, so that a file could be customized for a particular user or platform on-the-fly. You can think of Backee as an advanced dotfiles manager, whilst easy to use with its declarative definition files. -While not strictly necessary, Backee should be run by a privileged user to unleash its potential: restoring system-wide configuration files, webserver resources or installing packages, to name a few.
-On Unix, it links and copies files impersonating the owner of the directory. - -If you are using `sudo`, please read the `sudo` caveats below. +Backee performs operations as the user that run it by default. On UNIX, If a permission is denied while copying or linking files, it retries by calling a privilege elevation utility. `sudo` and `doas` are supported at the moment. ## Configuration format @@ -18,7 +15,7 @@ Services to be restored are represented by directories inside a parent directory Each service directory contains: - - A `service.yaml` file, and/or multiple `service_variantName.yaml`. See more documentation below. + - A `service.yaml` file, and/or multiple `service_variantName.yaml`. See further documentation below. - Optional `data` directory, containing files to process. - Optional `links` directory, containing files to be symlinked untouched. @@ -26,18 +23,18 @@ The following is `service.yaml`'s format: |Key|Type|Meaning| |---|---|---| -|`depends`|`list(str)`|List of service names as dependencies.
The services are then parsed from their directories.| +|`depends`|`list(str)`|List of service names as dependencies.
These services will be installed first.| |`setup`|`str`|Shell or Powershell script executed before packages installation.
Doesn't support variables. Data written to the script's stderr is logged on terminal, to show custom messages.| |`pkgmanager`|`list(str)`|Package manager command with its flags. The package manager must accept a list of package names appended, that will be passed by Backee. Defaults to `["pkcon", "install", "-y"]`.| |`packages`|`list(str)`|OS packages to install.| -|`links`|`dict(str, str)`|Source-destination pairs for symlinking files/directories. The source path is relative to the service's `links` directory, while the destination is the symlink path. Non existing parent directories are automatically created. Environment variables can be used to compose the destination path: use the `${VAR_NAME}` syntax to match the `VAR_NAME` enviroment variable.| -|`variables`|`dict(str, str)`|Variables passed to the template engine for file copies and the finalization script. Variables can be in clear text or secret.| -|`copies`|`dict(str, str)`|Source-destination pairs for copying files. The source path is relative to the service's `data` directory, while the destination is the path of the file copied. Non existing parent directories are automatically created. Environment variables can be used to compose the destination path: use the `${VAR_NAME}` syntax to match the `VAR_NAME` enviroment variable. The file can be edited on-the-fly using the Go template engine, using both environment variables and values in `variables`.| -|`finalize`|`str`|Shell or Powershell script executed as the final stage.
It supports variables defined in `variables` using the Go template engine. You may refer to the implicit `datadir` variable to access files inside the `data` directory. Data written to the script's stderr is logged on terminal, to show custom messages.| +|`links`|`dict(str, str)`|Source-destination pairs for symlinking files/directories. The source path is relative to the service's `links` directory, while the destination is the symlink path. Non existing parent directories are automatically created. Variables can be used to compose the destination path.| +|`variables`|`dict(str, str)`|Extra variables on top of environment variables.| +|`copies`|`dict(str, str)`|Source-destination pairs for copying files. The source path is relative to the service's `data` directory, while the destination is the path of the file copied. Non existing parent directories are automatically created. Variables can be used to compose the destination path and to customize the content of each file.| +|`finalize`|`str`|Shell or Powershell script executed as the final stage.
It supports variables to customize the script. You may also refer to the implicit `datadir` variable to access files inside the `data` directory. Data written to the script's stderr is logged on terminal, to show custom messages.| Keys are processed in the above order. Each key is optional, to the point it's (pointlessly) possible to write a no-op service. -See `service.example.yaml` for a complete service definition file. +See `service.example.yaml` for a complete service definition file and learn about the extended form of some keys. ### Secret variables @@ -49,12 +46,6 @@ A service may have different configuration files or scripts depending on the ope Example: run `backee --variant homeServer nginx`. This will fetch definitions from `nginx/service_homeServer.yaml`. -## If you are using `sudo`… - -Running `sudo` alone doesn't preserve your environment variables. If you rely on them for links and/or copies, or in your setup and finalization scripts, run `sudo -E backee` to keep them. - -Some platforms configure `sudo` to not retain your $HOME environment variable: you'll be using the root home instead of yours. Use `sudo -E HOME="$HOME" backee` to ensure your home will be retained. - ## License This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.