GEFS(8)                                                   GEFS(8)

     NAME
          gefs - file server maintenance

     SYNOPSIS
          check
          df
          halt
          help
          permit [ on | off ]
          save trace filename
          set [ snap ] key val
          clr [ snap ] key
          snap [ -mdl ] [ old [ new ] ]
          sync
          users

     DESCRIPTION
          Gefs(4) provides an administration console on /srv/gefs.cmd.
          By default, this console is only readable and writable by
          the owner of the file system.

     CONSOLE
          The console handles the following commands:

          Check applies basic consistency checks to the file system,
          reporting invalid blocks, broken metadata, and other similar
          structural issues.

          Df prints the amount of used space and total space in mega-
          bytes, as well as the percentage of space occupied.

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

          Help prints a summary of the available commands.  This table
          includes additional debug commands that are subject to
          change, and are intentionally undocumented.

          Permit [ on | 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 %
          sigil.  Permissive disables permissions checks when access-
          ing files, and allows wstat(5) to modify the owner of the
          file.  This may be useful during file system initialization.

          Set or clr sets or clears a configuration key, respectively.

     Page 1                       Plan 9              (printed 7/9/25)

     GEFS(8)                                                   GEFS(8)

          If the 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:

          retain'timespec'
               sets the schedule for which snapshots are retained.
               The timespec is a sequence of counts and intervals, in
               the form < 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.

               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 `60@1m 24@1h
               @1d' is used.

          Snap manages snapshots.  It can be invoked as snap -l, snap
          -d snap, or snap [ -flags ] [[old] new], which will list,
          delete, or create new snapshots respectively.  By default,
          the snap command creates a snapshot of old, tagging it with
          the name new. It accepts the following options:

          -l   Lists snapshots and their attributes.  This flag
               accepts no arguments.

          -d snap
               Deletes a snapshot, reclaiming whatever space is not
               shared with other snapshots.  This flag accepts a sin-
               gle argument, old, as the partition to delete.

          -m   Marks the newly created snapshot as mutable, rather
               than read-only.  This flag only has an effect when tag-
               ging a new snapshot, and is ignored otherwise.

          Sync writes dirty blocks in memory to the disk.

          Users attempts to reload the user table from /adm/users.

          Save trace saves a trace of recent operations to a file.  If
          a file is not specified, it prints to the console.

     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

     Page 2                       Plan 9              (printed 7/9/25)

     GEFS(8)                                                   GEFS(8)

          are referred to by name, and are selected at mount time with
          an attach spec.  When the attach spec starts with the %
          sigil, a snapshot is mounted in permissive mode.  This
          allows the mounting user to bypass normal file system per-
          mission 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 of these other than the
          main snapshot are required for the file system to work cor-
          rectly, and may not be removed.

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

          adm: This is the snapshot where administrative files live.
               The 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.

          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 oth-
               erwise not special.  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 con-
          sole.  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

     Page 3                       Plan 9              (printed 7/9/25)

     GEFS(8)                                                   GEFS(8)

          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.

     EXAMPLES
          To show current disk usage, the following may be written on
          the console:

               gefs# df

          To create a new snapshot:

               gefs# snap main myimmutable

          To create a new mutable snapshot that does not take auto-
          matic checkpoints:

               gefs# snap -m main mymutable
               gefs# set mymutable retain ''

          To delete a snapshot:

               gefs# snap -d mysnap

          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:

               gefs# set main retain '12@5m 48@2h @d'

          To set the default snapshot retention to daily, with no
          minute or hour snapshots:

               gefs# set retain @d

          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

               # From the console, reload the user table.
               # if there is an error in the user file,
               # an error will be printed on the console.

     Page 4                       Plan 9              (printed 7/9/25)

     GEFS(8)                                                   GEFS(8)

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

     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 7/9/25)