GEFS(8)GEFS(8)

NAME

gefs – file server maintenance

SYNOPSIS

mount /srv/gefs /adm adm

unhandled troff command .sp

/adm/ctl /adm/status /adm/users /srv/gefs.cmd

DESCRIPTION

Gefs(4) provides a number of special files for administration 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.

This is the name used to mount a list of all snapshots. Each snapshot in the file system will be listed in a directory.  

This is an empty snapshot. It contains no files or directories. All other snapshots are forked off of it.  

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.  

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

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 configuration of the filesystem as well as a list of snapshots.

The control file, located at /adm/ctl, takes the following commands:

Check filesystem for consistency, sending results to stdout.  

Toggle debug output.  

Delete a snapshot, reclaiming whatever space is not shared with other snapshots.  

Sync all IO to disk and exit the file system.  

When the storage is full, it may be impossible to delete snapshots. With an argument of 1, temporarily allow the file system to use a small reserve space to recover from this scenario.  

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 configured retention settings for the targeted label, deferring to the global settings.  

Create a new snap of name, tagging it with the tag.  

Create a new fork from base, giving it the name new. The new label will be the label used to mutate the new branch.  

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.  

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:

Performs the same checks as the ctl file, but shows results on the cmd console, instead of on stdout.  

Sync all IO to disk and exits the file system. While the syncing occurs, the file system does not allow new writes.  

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 automatic 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

# 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

gefs(4)