moebiusband/home-impermanence
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Update README

Browse Source
This commit is contained in:
Jan Eitzinger 2024-04-28 09:25:19 +02:00
parent ad29df951a
commit 778a2c67ef
1 changed files with 64 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
README.md
View File

@ -2,11 +2,17 @@
OpenBSD and Linux compatible implementation of the [impermanence project from the NixOS community](https://nixos.wiki/wiki/Impermanence) OpenBSD and Linux compatible implementation of the [impermanence project from the NixOS community](https://nixos.wiki/wiki/Impermanence)
Such a tool permits to have your $HOME mounted with a memory filesystem and populate it from an explicit list of files and directories hooked from a persistent storage directory (like a place in your /home partition), the point is to have a clean and reproducible environment every time you log in with only the content you selected. No more extra files when you start a program only once. Such a tool permits to have your $HOME mounted with a memory filesystem and
populate it from an explicit list of files and directories hooked from a
persistent storage directory (like a place in your /home partition), the point
is to have a clean and reproducible environment every time you log in with only
the content you selected. No more extra files when you start a program only
once.
# Installation # Installation
Run `make install` as root, this will copy the program file in `/usr/local/bin/impermanence` and the service file in `/etc/rc.d/impermanence`. Run `make install` as root, this will copy the program file in
`/usr/local/bin/impermanence` and the service file in `/etc/rc.d/impermanence`.
On OpenBSD, You need some packages as dependencies: On OpenBSD, You need some packages as dependencies:
- p5-File-HomeDir - p5-File-HomeDir
@ -17,17 +23,21 @@ On Alpine Linux, you need the following packages: `apk add perl-file-homedir per
# Configuration # Configuration
The configuration is done in two parts, system wide to configure the **impermanence** service that will mount the memory filesystem and populate it. The configuration is done in two parts, system wide to configure the
**impermanence** service that will mount the memory filesystem and populate it.
## System wide ## System wide
### OpenBSD ### OpenBSD
Using rcctl: `rcctl set impermanence flags -d /home/persist/ -u my-user` and `rcctl enable impermanence`. Using rcctl: `rcctl set impermanence flags -d /home/persist/ -u my-user` and
`rcctl enable impermanence`.
### Alpine Linux ### Alpine Linux
Lazy way is to enable the service local with `rc-update add local`, and create two files `/etc/local.d/99-impermanence.start` and `/etc/local.d/99-impermanence.stop` with the following content: Lazy way is to enable the service local with `rc-update add local`, and create
two files `/etc/local.d/99-impermanence.start` and
`/etc/local.d/99-impermanence.stop` with the following content:
``` ```
#!/bin/sh #!/bin/sh
@ -43,18 +53,23 @@ and
## User configuration ## User configuration
The user configuration will be done in `/home/persist/my-user/impermanence.yml` if you chose `-d /home/persist` for the service and `-u my-user`. The user configuration will be done in `/home/persist/my-user/impermanence.yml`
if you chose `-d /home/persist` for the service and `-u my-user`.
The configuration file describes the size of the memory filesystem, the list of files and the list of directories that should be added to the filesystem as symbolic links from the persistent directory. The configuration file describes the size of the memory filesystem, the list of
files and the list of directories that should be added to the filesystem as
symbolic links from the persistent directory.
There are currently three keys: There are currently five keys:
- **size**: which is a parameter to mount_mfs -s to give the ramdisk size - **size**: which is a parameter to `mount_mfs -s` to give the ramdisk size
- **files**: which is a list of files relative to $HOME - **files**: which is a list of files relative to $HOME to symlink into the persist home
- **directores**: which is a list of directories relative to $HOME - **directores**: which is a list of directories relative to $HOME to symlink into the persist home
- **skeleton**: which is a list of directories relative to $HOME to recreate on every mount
- **chezmoi**: indicate to use `chezmoi apply` for populating config files
Minimalistic example of `/home/persist/my-user/impermanence.yml`: Minimalistic example of `/home/persist/my-user/impermanence.yml`:
``` ``` yaml
size: 200m size: 200m
files: files:
- .bashrc - .bashrc
@ -67,17 +82,20 @@ directories:
- .local/share - .local/share
- .mozilla - .mozilla
- .ssh - .ssh
- Data - src
- Documents skeleton:
- tmp
- prg
- Downloads - Downloads
- dev chezmoi: true
``` ```
# home-impermanence rc service # home-impermanence rc service
## restart ## restart
The restart parameter to the service will unmount the device and recreate it, allowing a fresh restart. The restart parameter to the service will unmount the device and recreate it,
allowing a fresh restart.
It is a bad idea to use while the user is connected. It is a bad idea to use while the user is connected.
@ -99,34 +117,53 @@ Tells if the mount is currently done.
## I configured something in a GUI program, how do I know what changed on disk? ## I configured something in a GUI program, how do I know what changed on disk?
If you want to add a file to the persistent area after a change, you may want to know exactly what changed on disk to add the file or directory to your configuration file. If you want to add a file to the persistent area after a change, you may want to
know exactly what changed on disk to add the file or directory to your
configuration file.
Using `find` it's easy to scan all the files from the ramdisk (excluding the symbolic links) and order them by date of change. Using `find` it's easy to scan all the files from the ramdisk (excluding the
symbolic links) and order them by date of change.
This can be done with `find -x ~/ -type f -exec ls -altr {} +`, the last files are the most recently modified. This can be done with `find -x ~/ -type f -exec ls -altr {} +`, the last files
are the most recently modified.
## Beware file loss ## Beware file loss
When using this way of life, you need to remember all changes that don't belong in the persistent areas will be lost. For example, this will happen for all new files or directories at the root of your $HOME. When using this way of life, you need to remember all changes that don't belong
in the persistent areas will be lost. For example, this will happen for all new
files or directories at the root of your $HOME.
Impermanence requires the user to be aware of what files must stay over time, this is the point of impermanence after all. Impermanence requires the user to be aware of what files must stay over time,
this is the point of impermanence after all.
## I want to make a new file/directory persistent ## I want to make a new file/directory persistent
If you are using your system and want to keep a newly created file or directory, move it to your persistent area at the correct place and create a symbolic link, this will allow a drop-in replacement without rebooting. If you are using your system and want to keep a newly created file or directory,
move it to your persistent area at the correct place and create a symbolic link,
this will allow a drop-in replacement without rebooting.
Then, update your configuration file to add the new entry. Then, update your configuration file to add the new entry.
## How does a good configuration file look ## How does a good configuration file look
There are no good or bad configuration file content (except if it's invalid obviously). The whole point of impermanence is to hand-pick every directories and files you want to run your session, by admitting all others files will be thrown away at reboot. There are no good or bad configuration file content (except if it's invalid
obviously). The whole point of impermanence is to hand-pick every directories
and files you want to run your session, by admitting all others files will be
thrown away at reboot.
While you can list `.config` and `.local` which is a very large include, you could rather list only a subset of those, which will make a long list and require a few guess&fix sessions to get the things right. While you can list `.config` and `.local` which is a very large include, you
could rather list only a subset of those, which will make a long list and
require a few guess&fix sessions to get the things right.
The less directories are at the top level, the more you will pinpoint the exact configuration you want to keep over time. The less directories are at the top level, the more you will pinpoint the exact
configuration you want to keep over time.
## Restarting impermanence ## Restarting impermanence
If you are actively tweaking your configuration file, you may have issues when impermanence is unmounting the ramdisk device even with your graphical session stopped, a process may still be running and using the partition. You would have to find the running PID by looking at processes and their owner and kill it. If you are actively tweaking your configuration file, you may have issues when
impermanence is unmounting the ramdisk device even with your graphical session
stopped, a process may still be running and using the partition. You would have
to find the running PID by looking at processes and their owner and kill it.
As a side effect, you shouldn't be able to stop impermanence while you are using your session because the system will prevent the ramdisk to be umounted. As a side effect, you shouldn't be able to stop impermanence while you are using
your session because the system will prevent the ramdisk to be umounted.