.Dd $Mdocdate: March 14 2022 $
.Dt IMPERMANENCE 1
.Os
.Sh NAME
.Nm impermanence
.Nd manage a ramdisk with a collection of persistent files
.Sh SYNOPSIS
.Nm
.Fl t Ar conf 
.Nm
.Op Fl v
.Fl d Ar directory
.Fl u Ar user
.Op Cm start | Cm stop | Cm status | Cm restart
.Sh DESCRIPTION
.Pp
.Nm
is a program to manage an user directory mounted as a volatile
ramdisk and filling it with symlinks to persistent files and
directories taken from an user managed configuration file.
.Pp
The advantages of such a setup is to have a reproducible home
environment that won't keep undesirable changes over time which
happen regularly when running new software or different desktop
environment.
.Pp
However, this requires the user to be mindful of the setup to prevent
data loss.
.Sh OPTIONS
.Bl -tag -width -u user -c /home/persistent
.It Fl t Ar conf
Enable test mode which will parse the configuration file
.Ar conf ,
validates it and output its content in a human readable format
before exiting gracefully.
.It Op Fl v
Enable verbose mode adding debug information to stderr and syslog.
.It Fl d Ar directory
Tell
.Nm
where to look for the user persistent directory.
Note that it will look for a directory with the user name in the
directory given in this parameter.
.It Fl u Ar username
Tell
.Nm
which user will have its $HOME directory mounted as ramdisk.
.It Cm start
Create the ramdisk using
.Xr mount_mfs 8
and fill it with the listed content using
.Xr symlink 2
from the persistent directory for each file and directory listed
in the configuration file.
.It Cm stop
Umount the ramdisk using
.Xr umount 8 ,
all data that wasn't listed in the configuration file at start time
will be lost.
.It Cm restart
Do a stop and a start.
.It Cm status
Returns 0 if the user directory is already mounted as mfs, returns
1 otherwise.
.El
.Sh FILES
.Nm
will look for a file
.Sy impermanence.yml
in the directory
.Ar user
found in the directory
.Ar directory.
.Pp
The 
.Sy impermanence.yml
file is a YAML formatted configuration file using three keys.
.Bd -literal -offset indent
size: 200m
files:
  - .bashrc
  - .xsession
directories:
  - .config
  - .ssh
  - Documents
.Ed
.Pp
With
.Cm size
being the size parameter given to
.Xr mount_mfs 8
.Cm files
being the list of files relative to the user persistent directory
that must be symlinked to the ramdisk.
.Cm directories
being the list of directories relative to the user persistent
directory that must be symlinked to the ramdisk.
.Sh EXIT STATUS
.Pp
In case of a fatal error,
.Nm
will exit on a status code 2.
.Pp
In case of a misusage,
.Nm
will exit on a status code 1.
.Pp
In normal operations,
.Nm
will exit on a status code 0.
.Sh EXAMPLES
Let's say you want user
.Em alice
to have its
.Em /home/alice
$HOME directory mounted with a ram disk.
.Pp
You need to create a place where to store
.Cm alice
files, you can move
.Sy /home/alice
to
.Sy /home/persistent/alice
and recreate
.Sy /home/alice .
.Pp
Create a file in
.Sy /home/persistent/alice/impermanence.yml
following the file format to list every file and
directories that must be linked from
.Sy /home/persistent/alice/
to
.Sy /home/alice/
when
.Nm
is started using the following command line:
.Bd -literal -offset indent
impermanence -u alice -d /home/persistent start
.Ed
.Sh DIAGNOSTICS
.Nm
has a verbose mode to get more information.
Normal output and verbose output if enabled are both sent to
.Xr syslog 3 .
.Sh SEE ALSO
.Xr mount_mfs 8 ,
.Xr symlink 2,
.Xr syslog 3,
.Xr umount 8
.Sh HISTORY
This software tries to be an OpenBSD implementation of the NixOS
community impermanence module.
.Sh AUTHORS
.An See the LICENSE file for the authors .
.Sh LICENSE
See the LICENSE file for the terms of redistribution.
.Sh BUGS
Some programs may misbehave under these conditions.