ref: 4f1090a10d585fabda5c0bed6881c8d680b6955b
parent: 1d897e08bc751d93063846e5d9d2da5c0355a842
author: Ori Bernstein <ori@eigenstate.org>
date: Tue Jan 2 00:35:12 EST 2024
man: update docs
--- a/gefs.4.man
+++ b/gefs.4.man
@@ -33,26 +33,56 @@
.B -s
]
.SH DESCRIPTION
+.PP
.I Gefs
is an experimental file server.
It attempts to be crash safe, snapshotting, and corruption-detecting,
without giving up too much performance.
.PP
-The options are:
+Gefs allows multiple snapshots to be mounted and maintained concurrently.
+These snapshots all share the same storage pool, but can be written to,
+snapshotted, and rolled back independently.
+.PP
+The snapshot to mount is selected by using the attach specifier when
+mounting. If the attach specifier begins with a
+.I %
+sigil, then the snapshot is mounted in permissive mode.
+In permissive mode, permissions are not checked, and
+.IR wstat (5)
+may change any attributes of any file including the owner.
+Unless the file system is started with the permissive flag,
+only users in the
+.I adm
+group may mount snapshots permissively.
+.PP
+Gefs accepts the following options:
.TP
.B -A
Disable auth. Permissions are still checked, but anyone will be able
to attach as any user.
.TP
+.BI "-a " ann
+Announce and listen on the specified network address.
+.TP
.BI "-f " file
Use
.I file
as the disk.
.TP
+.B -g
+Grow the file system to fill the current partition.
+.TP
.BI "-m " mem
-Allocate
+Specify the amount of memory to use as cache.
+The
.I mem
-megabytes to use for cache.
+parameter recognizes
+.IR M ,
+.IR G ,
+and
+.I %
+as suffixes.
+If left unspecified, it defaults to 25% of installed RAM.
.TP
.BI "-n " name
Use
@@ -61,9 +91,6 @@
If unspecified, the default service name is
.IR gefs .
.TP
-.BI "-a " ann
-Announce and listen on the specified network address.
-.TP
.BI "-r " user
Ream the file system, erasing all of the old data.
Create a user named
@@ -76,12 +103,55 @@
will exit.
.TP
.B -S
-Ignore permissions. Without god, all things are permitted.
+Allow permissive mounts for all users.
+Additionally, if the user file is unreadable, fall back to the default user table.
+Without god, all things are permitted.
.TP
.B -s
Read and write protocol messages on standard file descriptors zero and one.
-.PD
-.SH "SEE ALSO"
+.TP
+.B -t
+Set the size of the trace buffer in megabytes.
+If set to 0, no debug traces are recorded.
+By default, 16 megabytes of trace buffer are kept.
+.SH EXAMPLES
+.PP
+Mount snapshots
+.I gefs
+from the partition
+.I /dev/sdE0/fs
+onto a few different mountpoints.
+The
+.I main
+snapshot is mounted to
+.IR /n/gefs .
+The
+.I sys
+snapshot is mounted to
+.IR /n/gefs/sys .
+And finally, the
+.I adm
+snapshot is mounted in permissive mode to
+.IR /n/adm .
+.IP
+.EX
+gefs -f /dev/sdE0/fs
+mount /srv/gefs /n/gefs
+mount /srv/gefs /n/gefs/sys sys
+mount /srv/gefs /n/adm %adm
+.EE
+.PP
+Initialize a new file system on a device.
+Note, this assumes the disk has already been prepared with
+.IR prep (8),
+and a
+.I fs
+partition has been created.
+.IP
+.EX
+gefs -r $user -f /dev/sdE0/fs
+.EE
+.SH SEE ALSO
.IR cwfs (4),
.IR hjfs (4),
.IR gefs (8),
--- a/gefs.8.man
+++ b/gefs.8.man
@@ -12,23 +12,44 @@
.PP
.B help
.PP
-.B permissive
-.RB [on |
-.BR off ]
+.B permit
+[
+.B on
+|
+.BR off
+]
.PP
+.B save trace
+.I filename
+.PP
.B snap
-.I -d old | old new
+[
+-Smdl
+]
+[
+.I old
+[
+.I new
+]
+]
.PP
.B sync
.PP
.B users
.SH DESCRIPTION
-The following commands should be written to the console of an
-.IR gefs (4)
-file server.
+.IR Gefs (4)
+provides an administration console on
+.IR /srv/gefs.cmd .
+By default, this console is only readable
+and writable by the owner of the file system.
+.SH CONSOLE
.PP
+The console handles the following commands:
+.PP
.I Check
-applies basic consistency checks to the file system.
+applies basic consistency checks to the file system,
+reporting invalid blocks, broken metadata, and other
+similar structural issues.
.PP
.I Df
prints the amount of used space and total space in megabytes,
@@ -35,7 +56,9 @@
as well as the percentage of space occupied.
.PP
.I Halt
-syncs all IO to disk and makes the file system read only.
+syncs all IO to disk and exits the file system.
+While the syncing occurs, the file system does not
+allow new writes.
.PP
.I Help
prints a summary of the available commands.
@@ -42,25 +65,53 @@
This table includes additional debug commands that are
subject to change, and are intentionally undocumented.
.PP
-.I Permissive
+.I Permit
[
.B on
|
.B off
]
-flips on permission checking.
+has two effects.
+First, if the user table is broken, it allows a fallback to a default user list.
+This allows the system administrator to recover if they reboot with a broken user file.
+Second, it allows mounts to occur in permissive mode by any user.
+Permissive mounts are designated by prefixing the attach spec with a
+.I %
+sigil.
+Permissive disables permissions checks when accessing files, and allows
+.IR wstat (5)
+to modify the owner of the file.
This may be useful during file system initialization.
.PP
.B Snap
+manages snapshots.
+It can be invoked as
+.I snap
+.BR -l ,
+.I snap
+.B -d
+.IR snap ,
+or
+.I snap
[
-.I -d old
-|
-.I old new
+.B -flags
]
-manages snapshots. When given the
-.I -d
-flag, it deletes an old snapshot.
-When given 2 arguments, it takes a snapshot of
+.IR "old new" ,
+which will list, delete, or create new snapshots respectively.
+It accepts the following options:
+.TP
+.B -l
+Lists snapshots and their attributes.
+.TP
+.BI "-d " snap
+Deletes a snapshot, reclaiming whatever space is not shared
+is not shared with other snapshots.
+.TP
+.B -m
+Flags that the newly created snapshot should be mutable.
+.TP
+.B -S
+Disables automatic snapshots.
.I old
and gives it the name
.IR new .
@@ -67,6 +118,82 @@
.PP
.I Sync
writes dirty blocks in memory to the disk.
+.PP
+.B Users
+attempts to reload the user table from
+.IR /adm/users .
+.PP
+.I save trace
+saves a trace of recent operations to a file.
+If a file is not specified, it prints to the console.
+.SH ADM FILES
+.PP
+Gefs supports independent snapshots in the same file system.
+As a result, global configuration needs to be separated from snapshots.
+The global configuration resides in a well known snapshot called
+.IR adm .
+.PP
+The adm snapshot would conventionally be mounted in
+.IR /adm .
+It contains the
+.IR users (6)
+file.
+.IR
+The
+.I users
+file is read at file system startup, or when the
+.I users
+command is run on the console.
+If the users file is malformed at file system start, then the file system will refuse to initialize.
+.I Permissive
+mode will allow the file system to fall back to a default users table.
+It will also allow any user to mount the
+.I adm
+snapshot: this can help recover from disasters.
+.PP
+The
+.B default
+table looks like this:
+.IP
+.EX
+-1:adm:adm:
+0:none::
+1:$user:$user:
+.EE
+.PP
+Where
+.I $user
+is specified at the time that the file system is reamed.
+.SH EXAMPLES
+.PP
+To show current disk usage, the following may be written on the console:
+.IP
+.EX
+df
+.EE
+To create a new snapshot:
+.IP
+.EX
+snap main myimmutable
+.EE
+.PP
+To create a new mutable snapshot that does not take automatic
+checkpoints:
+.IP
+.EX
+snap -Sm main mymutable
+.EE
+.PP
+To delete a snapshot:
+.IP
+.EX
+snap -d mysnap
+.EE
+.SH BUGS
+.PP
+Currently, it's not possible to change the mutability of a snapshot.
+Instead, a new label needs to be created.
+.PP
.SH SEE ALSO
.IR gefs (4)