ref: 434e5cdd3a8c94a4bae99fc30278cd9627f96936
parent: b343553909fba36dc9a576f405a46668ed6be505
author: Ori Bernstein <ori@eigenstate.org>
date: Sat Jul 19 00:17:36 EDT 2025
gefs(8): fix botched commit
--- /dev/null
+++ b/sys/man/8/gefs
@@ -1,0 +1,355 @@
+.TH GEFS 8
+.SH NAME
+gefs \- file server maintenance
+.SH SYNOPSIS
+.PD 0
+.PP
+.B check
+.PP
+.B df
+.PP
+.B halt
+.PP
+.B help
+.PP
+.B permit
+[
+.B on
+|
+.BR off
+]
+.PP
+.B save trace
+.I filename
+.PP
+.B set
+[
+.I snap
+]
+.I key
+.I val
+.PP
+.B clr
+[
+.I snap
+]
+.I key
+.PP
+.B snap
+[
+-mdl
+]
+[
+.I old
+[
+.I new
+]
+]
+.PP
+.B sync
+.PP
+.B users
+.SH DESCRIPTION
+.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,
+reporting invalid blocks, broken metadata, and other
+similar structural issues.
+.PP
+.I Df
+prints the amount of used space and total space in megabytes,
+as well as the percentage of space occupied.
+.PP
+.I Halt
+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.
+This table includes additional debug commands that are
+subject to change, and are intentionally undocumented.
+.PP
+.I Permit
+[
+.B on
+|
+.B off
+]
+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
+.I Set
+or
+.I clr
+sets or clears a configuration key, respectively.
+If the
+.I snap
+name is passed, then the key is set in that snapshot.
+If not, then it is set globally.
+This key is a free form string which controls
+some aspect of file system behavior on that snapshot.
+All changes take effect after the file system is restarted.
+Currently, one configuration option is supported:
+.TP
+.BI retain 'timespec'
+sets the schedule for which snapshots are retained.
+The timespec is a sequence of counts and intervals,
+in the form <
+.BR count >@<
+.BR interval ><
+.BR scale >.
+Every
+.BR interval ,
+a new snapshot is taken.
+Up to
+.B count
+snapshots are retained in the history, with old ones aging out.
+If the
+.B count
+is omitted, then old snapshots are not trimmed.
+If the
+.B interval
+is omitted, it defaults to 1.
+.IP
+Snapshot timing is taken from the config key attached to the snapshot.
+If there is no key attached to the snapshot,
+the global config key is used.
+If there is no global config key, the default value
+.B `60@1m 24@1h @1d'
+is used.
+.PP
+.B Snap
+manages snapshots.
+It can be invoked as
+.I snap
+.BR -l ,
+.I snap
+.B -d
+.IR snap ,
+or
+.I snap
+[
+.B -flags
+]
+.IR "[[old] new]" ,
+which will list, delete, or create new snapshots respectively.
+By default, the
+.I snap
+command creates a snapshot of
+.IR old ,
+tagging it with the name
+.IR new .
+It accepts the following options:
+.TP
+.B -l
+Lists snapshots and their attributes.
+This flag accepts no arguments.
+.TP
+.BI "-d " snap
+Deletes a snapshot, reclaiming whatever space
+is not shared with other snapshots.
+This flag accepts a single argument,
+.IR old ,
+as the partition to delete.
+.TP
+.B -m
+Marks the newly created snapshot as mutable,
+rather than read-only.
+This flag only has an effect when tagging a new snapshot,
+and is ignored otherwise.
+.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 SNAPSHOTS
+Snapshots are independent views of a filesystem hierarchy.
+A snapshot may be mutable or immutable.
+Mutable snapshots can be mounted and written to;
+immutable snapshots are a view of a file system hierarchy at a point in time.
+They are referred to by name, and are selected at mount time with an attach spec.
+When the attach spec starts with the
+.B %
+sigil, a snapshot is mounted in permissive mode.
+This allows the mounting user to bypass normal file system permission checks.
+In order to mount a snapshot in permissive mode, the mounting user must be in the
+.I adm
+group.
+.PP
+There are several attach names that are reserved for the file system's internal use.
+All of these other than the
+.I main
+snapshot are required for the file system to work correctly, and may not be removed.
+.TP
+.I dump:
+This is the name used to mount a list of all snapshots.
+Each snapshot in the file system will be listed in a directory.
+.TP
+.I empty:
+This is a read-only empty snapshot.
+It contains no files or directories.
+The empty snapshot may be forked in order to create a new hierarchy,
+independent of other snapshots.
+.TP
+.I adm:
+This is the snapshot where administrative files live.
+The
+.I users
+file is read at gefs startup, and define the users and groups for all snapshots.
+This file is described in detail in the following section.
+.TP
+.I main:
+This snapshot is less special than the other special snapshots.
+It is created by default at file system mount time,
+and is the snapshot which is mounted when an attach specifier is not given.
+However, it is otherwise not special.
+It may be deleted, created, and freely modified.
+.PP
+All snapshots are allocated from the same storage pool, and therefore
+share space.
+.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
+gefs# df
+.EE
+.PP
+To create a new snapshot:
+.IP
+.EX
+gefs# snap main myimmutable
+.EE
+.PP
+To create a new mutable snapshot that does not take automatic
+checkpoints:
+.IP
+.EX
+gefs# snap -m main mymutable
+gefs# set mymutable retain ''
+.EE
+.PP
+To delete a snapshot:
+.IP
+.EX
+gefs# snap -d mysnap
+.EE
+.PP
+To set the snapshot retention on the main snapshot
+to 12 snapshots taken every five minutes,
+along with 48 snapshots taken every 2 hours,
+and a daily snapshot with no trimming:
+.IP
+.EX
+gefs# set main retain '12@5m 48@2h @d'
+.EE
+.PP
+To set the default snapshot retention to daily,
+with no minute or hour snapshots:
+.IP
+.EX
+gefs# set retain @d
+.EE
+.PP
+To create a new user:
+.IP
+.EX
+# Mount the adm namespace (as a user in adm group):
+# and add the user to the user file
+% mount /srv/gefs /adm adm
+% sam /adm/users
+
+# From the console, reload the user table.
+# if there is an error in the user file,
+# an error will be printed on the console.
+% con -C /srv/gefs.cmd
+gefs# users
+refreshed users
+gefs# ^\\
+>>> q
+
+# Mount the file system in permissive mode to allow
+# changing file ownership, then create the user dir
+% mount /srv/gefs /n/u %main
+% mkdir /n/u/usr/$newuser
+% chgrp -u $newuser /n/u/usr/$newuser
+% chgrp $newuser /n/u/usr/$newuser
+
+# Ceate a tmp dir in the unsnapshotted 'other'
+# dataset. If it's present, the default namespace
+# will use it.
+% mount -c /srv/gefs /n/o %other
+% mkdir -p /n/o/usr/$newuser/tmp
+% chgrp $newuser /n/o/usr/$newuser^('' /tmp)+% chmod 700 $newuser/n/o/usr/$newuser^('' /tmp)+.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)
+
--
⑨