Move out docs
This commit is contained in:
parent
75ff3a3009
commit
b9fbcd70fd
14 changed files with 0 additions and 262 deletions
|
|
@ -1,20 +0,0 @@
|
|||
The `check` option performs two tasks through the configuration processing functions available at `src/configuration.sh`
|
||||
|
||||
1. Traversing the configuration directory to assemble a file list containing full paths for both the `base` and `bkp` directories
|
||||
2. Comparing the installed packages with the `packages` file at the root of the configuration directory
|
||||
|
||||
The first task is currently accomplished by resorting to `find`. While this allows for cleaner code, it relies on a utility with variable behavior across operating systems. Given the simplicity of the query, a better option might be using a POSIX-compliant wildcard such as `.[!.]* ..?* *` to match the files directly (e.g., in a for loop). Another option that may provide both readability and portability is repeating the match, once for hidden file and once for non-hidden files.
|
||||
|
||||
The second task is accomplished by resorting to the package management functions available at `src/package.sh`. The `package_manager` function abstracts the actual package manager in the underlying system and provides an OS-independent way to query manually installed packages.
|
||||
|
||||
Through the parsed `packages` configuration file at the root of the configuration directory (`~/.config/tori/packages` by default), both package lists are sorted and deduplicated before they can be filtered by each other using `grep` inverted matching.
|
||||
|
||||
This allows obtaining both differences and displaying them to the user. If no conflict resolution strategy has been configured or passed through the command line interface, several options are displayed:
|
||||
|
||||
1. Install/uninstall all
|
||||
2. Enter packages to install/uninstall
|
||||
3. Add all to/remove all from configuration
|
||||
4. Enter packages to add to/remove from configuration
|
||||
5. Decide in editor
|
||||
|
||||
Not all of these options are implemented and some require significant more effort than others. The last option, in particular, requires defining and parsing a syntax that allows users to interface with the possible options.
|
||||
|
|
@ -1,30 +0,0 @@
|
|||
`tori`'s role is to manage your configuration files and installed packages, allowing you to transfer this configuration between different versions of an operating system or even between different Unix and Unix-like operating systems, provided they are presently supported.
|
||||
|
||||
Because the application is meant to manage the installation of packages for you, it would defeat its purpose for it to require any packages to already be installed in order to function. It must be a portable application with minimal dependencies, so it can perform its functions on brand new systems where very few packages have been installed and little to no configuration has been done.
|
||||
|
||||
To achieve this portability and independence, it is meant to run on a POSIX-compatible shell where POSIX utilities are available. If your system does not provide this, it is very unlikely `tori` will function.
|
||||
|
||||
Note that while `tori` expects a POSIX _shell_, it is not meant as a universal tool able to run on any POSIX system. A POSIX shell is required because it is the interpreter for the whole source code in which tori was implemented, but for some of its purposes `tori` needs to be running in a supported operating system. For example, it has specific package management features that work by abstracting the actual package manager options behind a function that detects the operating system and then runs the apropriate command.
|
||||
|
||||
While it strives to do so, in some situations, tori may perform tasks by relying on resources not specified by POSIX, such as when there is no option or the available option has readability or usability downsides. In these situations, tori tends to rely on specific functions that will switch their behavior depending on the operating system's support for the operation.
|
||||
|
||||
Below is a list of assumptions made about what your system supports:
|
||||
|
||||
- shell
|
||||
- `local`
|
||||
- `read` with `read -r -p <prompt> <variable_with_user_input>` syntax
|
||||
- `mkdir` with `-pggjj
|
||||
- `find`
|
||||
- `grep`
|
||||
- `sed`
|
||||
- `xargs`
|
||||
- `uname`
|
||||
- `date`
|
||||
- with nanoseconds as `%N`
|
||||
- While nanoseconds support in `date` is not in the POSIX 2017 standard, it is used only when `$DEBUG` is set in the environment and is available on the currently supported systems (FreeBSD, Void Linux) and on the next operating system with planned support (Debian).
|
||||
- with `-r` for getting a modification date
|
||||
- This feature is not specified on POSIX. So far it was tested on FreeBSD and Void Linux.
|
||||
- `env` at `/usr/bin/env`
|
||||
- While this may be an issue from a portability standpoint, hardcoding the path where `sh` is also poses another portability issue. A more robust way to find it would be desirable.
|
||||
|
||||
`tori` is currently only tested on the `sh` Almquist shell as shipped by FreeBSD and the `dash` Almquist shell as shipped by Void Linux.
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
To do:
|
||||
|
||||
- When deciding to install/uninstall packages, there should be the option to also add/remove them from the configuration, both interactively and non-interactively
|
||||
|
||||
- Make configurable:
|
||||
- authorizer command (sudo/doas/su)
|
||||
- package cache update frequency (currently defaults to daily)
|
||||
|
||||
- Add a `--break` flag to the `log` function to print a newline before any output
|
||||
- Add this flag to the `log debug "user:\n$user_packages"` call on `scan_packages()` in `configuration.sh`
|
||||
|
||||
- Add install, uninstall and query commands to check the status of packages and simultaneously add/remove to/from system and configuration
|
||||
- Once install/uninstall and add/remove to/from configuration conflict resolution strategies have been implemented, the same functions can be reused to implement this
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
tori determines what is the running operating system through the output of `uname -s`. If it cannot get a descriptive enough, it will look for the `/etc/os-release` file.
|
||||
|
||||
If a `/etc/os-release` file is present, it takes precedence over the output of `uname`. Both the `NAME` and `ID` values will be looked at. This is aimed at helping to disambiguate between different variants of the same operating system.
|
||||
|
||||
The `NAME` value may be the only queried value if for the given supported operating system it is enough to disambiguate between the variants tori needs to be aware of.
|
||||
|
||||
In case there is no `/etc/os-release` file found, the output of `uname` is the next value considered.
|
||||
|
||||
If a supported operating system is not detected on neither of these, tori will exit with an error.
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
User data is initially configured to $HOME/.config/tori. At this stage, this allows concentrating all necessary data in a single place, however it is not ideal to have non-configuration files, such as backups, all in the same location.
|
||||
|
||||
When making these configurable, it would be interesting to move the default backup location to $HOME/.local.
|
||||
|
||||
User data is organized in two main directories: `base` and `bkp`.
|
||||
|
||||
- `base`: contains the files that will be matched against the current system's files
|
||||
- `bkp`: contains the original files prior to any intervention by `tori`. This directory is further split into two directories:
|
||||
- `canonical`: contains the very first version found for this file prior to any intervention by `tori`. If `tori` is running for the first time on a brand new system, this directory should contain the original files shipped by the operating system.
|
||||
- `ephemeral`: contains date-stamped versions of files prior to each occasion in which `tori` had to modify, delete or move them. This directory is not essential to the functioning of `tori`. It is provided as a safety net for the user and may be deleted at any time. It will be automatically recreated.
|
||||
|
||||
Both of these directories mimic the file structure found from the root of the file system. For example, this is how one such structure could look like:
|
||||
|
||||
```
|
||||
/home/user/.config/tori
|
||||
├── base
|
||||
│ └── home
|
||||
│ └── user
|
||||
├── .profile
|
||||
│ └── .shrc
|
||||
└── bkp
|
||||
└── canonical
|
||||
└── home
|
||||
└── user
|
||||
├── .profile
|
||||
└── .shrc
|
||||
```
|
||||
|
||||
`tori` will look only for regular files inside your configuration directory and currently will ignore symbolic link and any other filetype when scanning it.
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
`tori` can track if a given file in the configuration directory is present and matches the content of the corresponding file on the system level.
|
||||
|
||||
However, if a file changed on the system level is not in the configuration directory, `tori` can only alert you to that if the operating system provides some way to compare the present state of the system to the original one prior to user intervention.
|
||||
|
||||
One example would be FreeBSD's intrusion detection system, which provides a way to know which files have been changed. Another way would be by relying on a file system that provides the ability to compare differences between snapshots, such as ZFS. A third way would be if the operating system's package manager provides a command line interface to read the contents of packages and has packages that correspond to the core system, such as Void Linux's package manager, `xbps`.
|
||||
|
||||
The resource-intensiveness of each of these methods will vary greatly and therefore checking the whole system for changes can be time-consuming or provide overwhelming output. For this reason, `tori` by default operates in a more minimal fashion where you take responsibility for adding the files you would like to track to your configuration and only get warnings of untracked files when explicitly asked.
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
In order to take advantage of all the features offered by `tori` for package management, the operating system's package manager must provide a way to:
|
||||
|
||||
- install and uninstall packages from a command-line interface
|
||||
- query manually installed packages
|
||||
|
||||
The `packages` file is located at the root of the configuration directory and contains a list of package names, one per line. Blank lines and lines beginning with `#` are ignored.
|
||||
|
||||
When processing the package list, `tori` will compare the list of installed packages to the list in the configuration and ask the user for what action to take in order to conciliate them, unless a default action has been specified.
|
||||
|
||||
For information on how the application determines differences between the configuration package list and installed packages, see [`check`](./check.md).
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
The utilities functions available at `src/utility.sh` provide functionality that is either very simple in purpose or general to the whole application.
|
||||
|
||||
The two utility functions presently implemented are:
|
||||
|
||||
1. `log <level> <message>`
|
||||
2. `prepare_directories`
|
||||
|
||||
## `log`
|
||||
|
||||
This utility takes a log level as its first argument and a message as its second argument. The log message must be wrapped in double quotes, otherwise only the first word will be considered part of the message and the rest will be discarded.
|
||||
|
||||
The current log levels are:
|
||||
- `debug`: Displays only when `DEBUG` is set in the environment with a nanosecond-precision timestamp. The value `DEBUG` is set to does not matter. To disable the log messages, unset `DEBUG`, for example, with `export DEBUG=` or `unset DEBUG`
|
||||
- `user`: Always displays, with `[tori]` at the very left followed by a second-precision timestamp, a colon and the message
|
||||
- `fatal`: Always displays, exactly as in the `user` level
|
||||
|
||||
For now, all log messages are printed to `STDERR` so as not to shadow function return values.
|
||||
|
||||
## `prepare_directories`
|
||||
|
||||
`prepare_directories` runs at the very start of execution in order to verify that critical directories exist. These directories are:
|
||||
|
||||
- `TMP_DIR`, default `/tmp/tori`: created if not found
|
||||
- `CONFIG_ROOT`, default `~/.config/tori`: application exits with an error and exit code 1 if not found
|
||||
|
|
@ -1,28 +0,0 @@
|
|||
This function takes a list of package names separated by spaces and verifies that:
|
||||
|
||||
- Characters are only:
|
||||
- The package is a valid package name
|
||||
|
||||
## Character validation
|
||||
|
||||
An OS-specific pattern will be matched against the package name to decide which characters are valid or invalid by the naming standards its package repository uses.
|
||||
|
||||
If no OS-specific documentation is found on what are the allowed characters in package names, the obtained package list containing all available packages in the operating system's main repository will be analyzed to determine what is the current range of characters it uses.
|
||||
|
||||
The following character ranges have been determined so far:
|
||||
|
||||
- FreeBSD `pkg`
|
||||
- uppercase and lowercase letters
|
||||
- numbers
|
||||
- dashes
|
||||
- underscores
|
||||
- dots
|
||||
- plus signs
|
||||
|
||||
## Package validation
|
||||
|
||||
To determine if a package really exists, there must be a quick way to query a list of all available packages that does not mean individually making requests with each package name.
|
||||
|
||||
If the package manager provides a way to fetch a list of all available packages, tori will cache this list for each execution on a given day.
|
||||
|
||||
The user may also manually trigger a cache refresh through the command line interface using `tori cache`.
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
tori creates a backup directory called `bkp` that contains two top-level directories:
|
||||
|
||||
- `canonical`: Canonical backups are created the first time tori is told to modify a given file. If there is already a canonical backup, it defers to the cretaion of an ephemeral one. If tori is running against a recently-instaled system, the canonical backups should be close to the original state of the system as of its installation.
|
||||
- `ephemeral`: Ephemeral backups are timestamped backups created every time tori has to modify a file. This is mainly meant as a safety net against undesired consequences when using non-interactive options.
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
tori caches your package repository's list of all available packages in order to check if a given package name really corresponds to a package name available to install or uninstall.
|
||||
|
||||
This works by asking your package manager for this list and then storing it in the configured cache directory. It defaults to `~/.cache/tori/${OS}_packages.cache`. For example, on FreeBSD this will be `FreeBSD_packages.cache`.
|
||||
|
||||
The modification date of this file is accessed every time tori is launched. By default, if it differs from the current day it will trigger a refresh. Note that this is not a comparison on whether 24 hours have passed since the last refresh.
|
||||
|
||||
For this reason, tori may ask you for your password on startup with the message "Updating package cache".
|
||||
|
||||
If you would like to manually refresh the cache, you can use the `tori cache` command.
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
When you run `tori check`, tori will look into your configuration files and perform two tasks:
|
||||
|
||||
- Compare the files inside the `base` directory to the actual matching files on the system
|
||||
- Compare the package list in the `packages` file to the manually installed packages
|
||||
|
||||
If any divergence is found, it will prompt you on what action to take.
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
tori looks for configuration in `~/.config/tori`.
|
||||
|
||||
In this directory, you can create the following files and directories:
|
||||
|
||||
- `tori.conf`: configures options that will determine how tori itself behaves
|
||||
- `packages`: a list of packages containing one package name per line
|
||||
- blank lines and lines beginning with a `#` are ignored
|
||||
- `base`: a directory containing any number of files you can tell tori to copy to specific locations
|
||||
|
||||
## Configuration options
|
||||
|
||||
The `tori.conf` file must use the following format:
|
||||
|
||||
```conf
|
||||
tori_root = ~/.local/apps/my-tori-installation
|
||||
```
|
||||
|
||||
The following configuration options can be used to specify how you want tori to behave:
|
||||
|
||||
- `tori_root`
|
||||
|
||||
|
||||
Configuration options are case insensitive. The spaces around the `=` character are optional. Blank lines and lines beginning with a `#` are ignored.
|
||||
|
||||
You can use `~` and `$HOME` to represent your home directory. `$HOME` will be replaced in every occasion with your home directory, while `~` will only be replaced for the first occasion it appears in the configuration value.
|
||||
|
||||
Configuration values must _not_ contain the character `*`.
|
||||
|
||||
## Package lists
|
||||
|
||||
tori will read the `packages` file and check if it matches the currently installed packages. If it does not match, it will ask you how to proceed.
|
||||
|
||||
If you would prefer not to be asked how to proceed, you can configure a default action to be taken for package lists conflict resolution.
|
||||
|
||||
The application only concerns itself with manually installed packages. Any dependencies pulled automatically should not be added to the removal list. This is done by querying your package manager specifically for a list of manually installed packages.
|
||||
|
||||
## Base files
|
||||
|
||||
tori will go through the contents of the `base` directory and take different actions depending on how they are laid out.
|
||||
|
||||
If you have top-level directories inside `base` that match the directories starting from your system's root (for example, a `base/etc` directory), tori will recursively inspect this directory for files and compare them to the contents of the matching directories in the system.
|
||||
|
||||
If any of the files differ from their counterparts on the actual system, tori will ask you how to proceed. If you do not want to be asked every time, you can configure tori to take a specific action without asking.
|
||||
|
||||
If you decide to do so, bear in mind important files may get overwritten without warning. tori will create backups in the `bkp` directory every time a file is modified or overwritten.
|
||||
|
||||
If you would rather not replicate the system directory hierarchy in your `base`directory, you can also place the files inside `base` itself or in any other structure you desire.
|
||||
|
||||
In this case, you will have to manually specify if you want these files to be matched against any system-level files, and, if so, where those files are.
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
When running `tori check`, tori will generate two package lists: one with your installed packages and one from the `packages` file in your configuration directory.
|
||||
|
||||
In case it finds differences between the two lists, its default behavior is to ask you what to do. This approach is described in the following section.
|
||||
|
||||
You can also configure tori to automatically choose a given strategy in case you would prefer not to answer every time or if you are setting up an automated workflow. For details on this approach, see the section on **Non-Interactive Configuration**.
|
||||
|
||||
## Interactive Resolution
|
||||
|
||||
If it finds a difference between the two package lists, it will present you with a list of packages and a menu with several conflict resolution strategies.
|
||||
|
||||
tori will perform two separate checks that may produce two separate dialogues like the one described above. It checks for packages found in the configuration that are missing from the system and for packages found in the system but missing from the configuration.
|
||||
|
||||
If it finds packages in your configuration that are not installed on the system, it will present you with the following choices:
|
||||
|
||||
- `Install all`: The exact list of packages just displayed is passed to the package manager's install option. The package manager may ask for additional confirmation.
|
||||
|
||||
If it finds packages installed on the system but not listed in your configuration, it will present you with the following choices:
|
||||
|
||||
- `Uninstall all`: The exact list of packages just displayed is passed to the package manager's uninstall option. The package manager may ask for additional confirmation.
|
||||
- `Cancel`: Do nothing and close the dialog
|
||||
|
||||
## Non-Interactive Resolution
|
||||
|
||||
Non-Interactive Resolution is not yet implemented.
|
||||
Loading…
Reference in a new issue