home-impermanence/README.md

# home-impermanence

OpenBSD 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, 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

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`.

You need some packages as dependencies:
- p5-File-HomeDir
- p5-YAML

# Configuration

The configuration is done in two part, system wide to configure the
**impermanence** service that will mount the memory filesystem and
populate it.

## System wide

Using rcctl: `rcctl set impermanence flags -d /home/persist/ -u
my-user` and `rcctl enable impermanence`.

## 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 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:
- **size**: which is a parameter to mount_mfs -s to give the ramdisk size
- **files**: which is a list of files relative to $HOME
- **directores**: which is a list of directories relative to $HOME

Minimalistic example of `/home/persist/my-user/impermanence.yml`:

```
size: 200m
files:
  - .bashrc
  - .gitconfig
  - .profile
  - .tmux.conf
  - .xsession
directories:
  - .config
  - .local/share
  - .mozilla
  - .ssh
  - Data
  - Documents
  - Downloads
  - dev
```

# home-impermanence rc service

## restart

The restart parameter to the service will unmount the device and
recreate it, allowing a fresh restart.

This is a bad idea to use it while the user is connected.

## start

Creates and populates the home filesystem.

## stop

Umount the home filesystem.

This is a bad idea to use it while the user is connected.

## status

Tells if the mount is currently done.

# Tips

## 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.

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 one.

## Beware file loss

When using this way of life, you need to remember every changes
that doesn't belong in the persistent areas will be lost. For
example, this will happen for every 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.

## 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.

Then, update your configuration file to add the new entry.