shithub: front

--- a/sys/man/8/gefs

+++ /dev/null

@@ -1,355 +1,0 @@

-.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)

--

⑨