160 lines
3.7 KiB
Groff
160 lines
3.7 KiB
Groff
.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.
|