ref: f38b2ba20d80d0c8ff62611aa8fcea73bedb85df
dir: /sys/man/8/gefs/
.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 /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)