documentation: add a man page
This commit is contained in:
parent
608e496797
commit
ee5d61bec7
|
@ -0,0 +1,159 @@
|
|||
.Dd $Mdocdate: March 14 2021 $
|
||||
.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.
|
Loading…
Reference in New Issue