GEFS(8) GEFS(8)
NAME
gefs - file server maintenance
SYNOPSIS
mount /srv/gefs /adm adm
/adm/ctl
/adm/status
/adm/users
/srv/gefs.cmd
DESCRIPTION
Gefs(4) provides a number of special files for administra-
tion in the adm snapshot (traditionally mounted in /adm), as
well as an interactive console on /srv/gefs.cmd.
SNAPSHOTS
Snapshots are views of a filesystem hierarchy within a
branching timeline. The branch may have a single mutable
snapshot which will update the branch when written to. All
other snapshots are immutable and frozen in time. Each
branch evolves independently of all other branches, and is
referred to by the label of its head snapshot. All branches
are forked from an empty snapshot.
Any snapshot is mountable by label via mount(1)'s attach
spec. When the attach spec starts with the % sigil, that
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 adm group.
There are several attach names that are reserved for the
file system's internal use. All except main may not be
removed by the user.
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.
empty:
This is an empty snapshot. It contains no files or
directories. All other snapshots are forked off of it.
adm: This is the snapshot where special adminstrative files
live. It contains the users file, the adm file, and
the ctl fil These files are described in detail in the
following sections.
main:
Page 1 Plan 9 (printed 10/25/26)
GEFS(8) GEFS(8)
This branch is mounted by default if a mount spec is
not provided. It may be deleted, created, and freely
modified.
All snapshots are allocated from the same storage pool, and
therefore share space.
ADM FILES
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 adm.
The adm snapshot would conventionally be mounted in /adm.
It contains the users(6) file. The users file is read at
file system startup, or when the 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.
Permissive mode will allow the file system to fall back to a
default users table. It will also allow any user to mount
the adm snapshot: this can help recover from disasters.
The default table looks like this:
-1:adm:adm:
0:none::
1:$user:$user:
Where $user is specified at the time that the file system is
reamed.
The /adm/status file contains a read-only view of the con-
figuration of the filesystem as well as a list of snapshots.
The control file, located at /adm/ctl, takes the following
commands:
check Check filesystem for consistency, sending
results to stdout.
debug [ 0 | 1 ]
Toggle debug output.
delsnap snap Delete a snapshot, reclaiming whatever space
is not shared with other snapshots.
halt Sync all IO to disk and exit the file system.
usereserve [ 0 | 1 ]
When the storage is full, it may be impossi-
ble to delete snapshots. With an argument of
Page 2 Plan 9 (printed 10/25/26)
GEFS(8) GEFS(8)
1, temporarily allow the file system to use a
small reserve space to recover from this sce-
nario.
retain snap timespec
Set a schedule for snapshot retention of the
given label. If the label passed is - the
global retention is set to timespec, from the
default of `60@1m 24@1h @1d'
The timespec is a sequence of counts and
intervals, in the form of
<count>@<interval><scale>. Every interval, a
new snapshot is taken. Up to count snapshots
are retained in the history, with old ones
aging out. If the count is omitted, then old
snapshots are not trimmed. If the interval
is omitted, it defaults to 1.
Two special timespec values are possible.
Specifying 'none' disables automatic snapshot
retention, while 'default' clears the config-
ured retention settings for the targeted
label, deferring to the global settings.
snap name tag Create a new snap of name, tagging it with
the tag.
fork base new Create a new fork from base, giving it the
name new. The new label will be the label
used to mutate the new branch.
sync Write dirty blocks in memory to the disk.
The write will not return until all data that
was in flight when the sync was issued has
been written to disk.
users Attempt to reload the user ids from
/adm/users. If the user table fails to
reload, the write will error.
CONSOLE
The console at /srv/gefs.cmd handles the following commands:
check Performs the same checks as the ctl file, but shows
results on the cmd console, instead of on stdout.
halt Sync all IO to disk and exits the file system. While
the syncing occurs, the file system does not allow new
writes.
Page 3 Plan 9 (printed 10/25/26)
GEFS(8) GEFS(8)
help Print a summary of the available commands. This table
includes additional debug commands that are subject to
change, and are intentionally undocumented.
EXAMPLES
To show current disk usage:
grep '^usage' /adm/status
To create a new snapshot:
echo 'snap main myimmutable' > /adm/ctl
To create a new mutable snapshot that does not take auto-
matic checkpoints:
echo 'fork main mymutable' > /adm/ctl
echo 'retain mymutable none > /adm/ctl
To delete a snapshot:
echo 'delsnap mysnap' > /adm/ctl
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:
echo retain main 12@5m 48@2h @d > /adm/ctl
To set the default snapshot retention to daily, with no
minute or hour snapshots:
echo retain - @d > /adm/ctl
To create a new user:
# 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
# Reload the user table. If there are syntax errors
# in the file, they will be shown here and the reload
# will be aborted; fix them and try again.
% echo 'users' > /adm/ctl
# 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
Page 4 Plan 9 (printed 10/25/26)
GEFS(8) GEFS(8)
# Create 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 /n/o/usr/$newuser^('' /tmp)
BUGS
Currently, it's not possible to change the mutability of a
snapshot. Instead, a new label needs to be created.
SEE ALSO
gefs(4)
Page 5 Plan 9 (printed 10/25/26)