.TH ΘFS 4
.SH NAME
θfs \- disk file system
.SH SYNOPSIS
.B θfs
[
.B -anrsACD
] [
.B -m
.I nblk
] [
.B -p
.I port
]
.B device
.SH DESCRIPTION
.I Θfs
is a user-level file, block, and object storage server for Plan 9.
When used in conjunction with
.IR snap (3),
it can be used to provide the same functionality as fossil/venti
or the classic Plan 9 file server.
In addition to exporting its file system via 9P as with other Plan 9
file servers,
.I θfs
also exports its file system via NFSv3.
Finally,
.I θfs
also provides access to block storage via the AoE protocol
and to object storage via an experimental object extension to AoE
.PP
The command-line arguments for
.I θfs
are definted as follows:
.TP
.I -a
Disable AoE functionality, both the bock and object support.
.TP
.I -n
Disable NFS functionality.
.TP
.I -m
Set the number of blocks to keep in the in-memory cache.
.TP
.I -p
Set the port number on which to listen for 9P connections.
.TP
.I -r
Reame the file system on start up.
.TP
.I -s
Read 9P messages from the standard input.
This is used when a system takes its root from a local instance of
.IR θfs .
.TP
.I -A
Update access times on reads.
.TP
.I -C
Post a console descriptor to
.BR /srv .
.TP
.I -D
Turn on 9P debugging.
.PP
.SH CONSOLE
.PP
When invoked with the
.IR -C option, θfs
posts a file descriptor to
.BR /srv/θfscons .
This console can be accessed by connecting to the descriptor with
the command:
.IP
.EX
con -C /srv/θfscons
.EE
.PP
This interactive console supports the following commands:
.TP
.I allow
Turns off permissions checking and allows
.IR wstat (5)
messages to change file ownerships.
.TP
.I blockuse n
Looks up a specified block number and reports its role.
This is intended primarily for debugging purposes.
.TP
.I checkalloc
Scans the file system looking for inconsistancies in the block
allocation, reporting what it finds.
It also rebuilds the free block map.
.TP
.I cstat
Reports on in-memory block cache statistics.
.TP
.I disallow
Reinstates permissions checking and prohibits file ownership
changes.
.TP
.I dumpusers
Prints a list of all Plan 9 users and all NFS UID information
loaded either at start-up or by the
.I inituid
command.
.TP
.I fixfamilies
Scans the file system examining all parent/child/sibling
relationships and removes entries with no valid metadata.
.TP
.I fixpaths
Removes path names in the path hash table that do not
have valid metadata.
.TP
.I halt
Flushes all modified blocks from the cache and terminates
9P and NFS service.
.TP
.I help
Prints a list of the commands supported in the console and the
number of command arguments each uses.
.TP
.I hstat
Prints a summary of hash table statistics.
In particular, it reports on the number of bucket collisions and
maximum search depth encountered since start-up.
.TP
.I inituid
Reloads the Plan 9 user file
.B /adm/users
and the NFS UID mappings specified in
.BR /adm/nfs .
.TP
.I lcreate lun nblocks
Creates an AoE LUN with a specified AoE ID and size.
.TP
.I lls
Prints a list of AoE LUNs.
.TP
.I lmeta lun
Prints the metadata for the specified AoE LUN.
.TP
.I lrm lun
Removes the specified AoE LUN.
.TP
.I mpred n
Locates the predecessor to the specified meatadatum in the
metadata list of which it's a part.
.TP
.I mprint n
Prints the details of the specified metadatum.
.TP
.I mstat
Prints a summary of metadata statistics.
.TP
.I newroot name
Creates a new file tree within the file system storage
space.
The file tree named
.B dump
has a special role for storing the file system's snapshot
history.
Named roots are accessible by way of the mount specifier
in 9P and as top-level directories in a virtual root in NFS.
.TP
.I nfsdebug
Prints the current debug level of NFS when invoked with no
arguments.
Otherwise, sets the NFS debug level to the specified value.
.TP
.I p2q path
Looks up and prints the QID path value for the specified path
name.
.TP
.I p9debug n
Sets the value of the
.B chatty9p
variable.
.TP
.I phash path
Shows the bucket number and the location of the hash list
for the specified path name.
.TP
.I pmeta path
Prints the metadata list for the specified path name.
.TP
.I q2m qid
Looks up and prints the index of the first metadatum for
the specified QID path.
.TP
.I qmeta qid
Prints the metadata list for the specified QID path.
.TP
.I recovermeta
Scans the file system and rebuilds the free list of metadata
entries.
.TP
.I revert name
Reverses the effect of changes made since a specified snapshot.
The file system is rolled back in time to the point at which the
specified snapshot was taken.
.TP
.I rmp path
Removes the specified path name from the path hash table.
.TP
.I rootallow
Gives UID 0 unchecked access over NFS according to traditional
UNIX superuser privileges.
.TP
.I rootdisallow
Treats UID 0 as though it were any normal user and enforces
permissions checking for it as such.
.TP
.I setmeta qid type name value
Adds (or modifies) a metadatum for the specified QID path.
Its arguments are QID path, metadata type, name, and value.
.TP
.I setmstruct n next name type value
Explicitly sets the fields of a specified metadatum.
Useful mostly to do very low-level repairs on a mangled file
system.
.TP
.I setqhash qid n
Points a QID hash table entry to a specified metadatum.
.TP
.I snap
Creates a file system snapshot when using
.IR snap (3)
and when using a dump file system.
Snapshots are named in the same style as fossil and the
traditional Plan 9 file server.
Each year for which at least one shapshot exists has a directory
and each snapshot is a directory named
.B mmddn
where
.B mm
is the month,
.B dd
is the day on which the snapshot is taken.
For the first snapshot of the day,
.B n
is the empty string.
For subsequent snapsthots it takes on the values: 1, 2, ... 9.
.TP
.I super
Prints a summary of the file system super block.
.TP
.I sync
Flushes any modified blocks in the cache.
.SH EXAMPLES
Create a file system listening on port 1992 and mount it on
.BR /n/θfs .
.IP
.EX
% θfs -rCp1992 /dev/sdE0/data
% srv tcp!127.1!1992 θfs
% mount -c /srv/θfs /n/θfs
.EE
.PP
.SH FILES
.TF /adm/users
.TP
.B /adm/users
File containing Plan 9 user and group IDs.
.TP
.B /adm/nfs
File specifying the other files containing NFS client
UID to Plan 9 user name mappings.
.SH SOURCE
.B /sys/src/cmd/θfs
.SH "SEE ALSO"
.IR fossil (4),
.IR kfs (4),
.IR mkfs (8),
.IR prep (8),
.IR sd (3)
.SH BUGS
Certainly numerous:
.TF \(bu
.IP \(bu
The mechanism for implementing daily snapshots is ugly and
there's no current way to set the time of day when this is
done.
.IP \(bu
The block and object storage support has had precious little testing.
.IP \(bu
The default cache size should be computed as a percentage of
the use memory space, rather than being a hard coded number of blocks.
.IP \(bu
Although performance has not yet been an issue, no significant effort
has yet gone into improving it.