FS(8) FS(8)
NAME
fs, exsort - file server maintenance
SYNOPSIS
help [ command ... ]
allow
arp subcommand
cfs filesystem
check [options]
clean file [ bno [ addr ] ]
clri [file...]
cpu [proc]
create path uid gid perm [lad]
cwcmd subcommand
date [[+-] seconds]
disallow
duallow [uid]
dump [ filesystem ]
files
flag flag [ channel ]
fstat [ files ]
halt
hangup channel
newuser name [options]
noattach
passwd
printconf
profile [01]
remove [files...]
route subcommand
sntp kick
stat[admiesw]
stats [[-] flags...]
sync
time command
trace [number]
users [file]
version
who [user...]
wormeject [ tunit ]
wormingest [ tunit ]
wormoffline drive
wormonline drive
wormreset
disk/exsort [-w] [file]
DESCRIPTION
Except for exsort, these commands are available only on the
console of an fs(4) file server.
Page 1 Plan 9 (printed 12/21/24)
FS(8) FS(8)
Help prints a `usage string' for the named commands, by
default all commands. Also, many commands print menus of
their options if given incorrect or incomplete parameters.
Allow disables permission checking and allows wstat. This
may help in initializing a file system. Use this with cau-
tion.
Arp has two subcommands: print prints the contents of the
ARP cache and flush flushes it.
Cfs changes the current file system, that is, the file tree
to which commands (check, clean, clri, create, cwcmd, dump,
newuser, profile, remove, and users) apply. The initial
filesystem is main.
Check verifies the consistency of the current file system.
With no options it checks and reports the status. It sus-
pends service while running. Options are:
rdall Read every block in the file system (can take a long
time). Normally, check will stop short of the actual
contents of a file and just verify the block
addresses.
tag Fix bad tags; each block has a tag that acts as a
backwards pointer for consistency checking.
ream Fix bad tags and also clear the contents of blocks
that have bad tags.
pfile Print every file name.
pdir Print every directory name.
free Rebuild the list of free blocks with all blocks that
are not referenced. This option is only useful on
non-cache/WORM file systems. If the filesystem was
modified, the summary printed at the conclusion of
the check may not reflect the true state of the
freelist and may also print a list of missing blocks.
These missing blocks are actually on the free list
and the true state of the filesystem can be deter-
mined by running check with no arguments.
bad Each block address that is out of range or duplicate
is cleared. Note that only the second and subsequent
use of a block is cleared. Often the problems in a
file system are caused by one bad file that has a lot
of garbage block addresses. In such a case, it is
wiser to use check to find the bad file (by number of
Page 2 Plan 9 (printed 12/21/24)
FS(8) FS(8)
diagnostic messages) and then use clri to clear the
addresses in that file. After that, check can be
used to reclaim the free list.
touch Cause every directory and indirect block not on the
current WORM disk to be advanced to the current WORM
on the next dump. This is a discredited idea to try
to keep operating on the knee of the cache working
set. Buy more cache disk.
trim reduces the file system's fsize to fit the device
containing the file system. This is useful after
copying a partially-full file system into a slightly
smaller device. Running check free afterward will
construct a new free list that contains no blocks
outside the new, smaller file system.
Clean prints the block numbers in file's directory entry
(direct, indirect and doubly indirect) and checks the tags
of the blocks cited. If bno is supplied, the bno'th block
number (using zero origin) is set to addr (defaults to
zero). Note that only the block numbers in the directory
entry itself are examined; clean does not recurse through
indirect blocks.
Clri clears the internal directory entry and abandons stor-
age associated with files. It ignores the usual rules for
sanity, such as checking against removing a non-empty direc-
tory. A subsequent check free will place the abandoned
storage in the free list.
Cpu prints the CPU utilization and state of the processes in
the file server. If the name of a process type argument is
given, then CPU utilization for only those processes is
printed.
Create creates a file on the current file system. Uid and
gid are names or numbers from /adm/users. Perm is the low 9
bits of the permission mode of the file, in octal. An
optional final l, a, or d creates a locked file, append-only
file, or directory.
Cwcmd controls the cached WORM file systems, specifically
the current file system. The subcommands are:
mvstate state1 state2 [platter]
States are none, dirty, dump, dump1, error, read, and
write. A mvstate dump1 dump will cause I/O errors in
the last dump to be retried. A mvstate dump1 write
will cause I/O errors in the last dump to be retried in
reallocated slots in the next dump. A mvstate read
none will flush the cache associated with the WORM. A
Page 3 Plan 9 (printed 12/21/24)
FS(8) FS(8)
mvstate dump write aborts the background process dump-
ing to WORM; as a consequence it leaves holes in the
dump file system. Other uses are possible but arcane.
The optional platter limits affected blocks to those on
that platter.
prchain [start] [back-flag]
Print the chain of superblocks for the directory con-
taining the roots of the dumped file systems, starting
at block number start (default 0) going forward (back-
wards if back-flag is supplied and is non-zero).
searchtag [start] [tag] [blocks]
Reads the WORM device starting at block start and pro-
ceeding for blocks blocks (default 1000) until it finds
a block with numeric tag tag.
savecache [percent]
Copy the block numbers, in native endian longwords, of
blocks in the read state to the file /adm/cache for use
by disk/exsort. If an argument is given, then that
percent (most recently used) of each cache bucket is
copied.
loadcache [dskno]
Read /adm/cache and for every block there on WORM disk
side dskno (zero-origin), read the block from WORM to
the cache. If dskno is not supplied, all blocks in
/adm/cache are read.
morecache dskno [count]
Read count blocks from the beginning of WORM disk side
dskno to the cache. If no count is given, read all of
side dskno into the cache.
startdump [01]
Suspend (0) or restart (1) the background dump process.
touchsb
Verify that the superblock on the WORM is readable,
ignoring the cached copy.
blockcmp [wbno] [cbno]
Compares the WORM block wbno with the cache block cbno
and prints the first 10 differences, if any.
acct Prints how many times each user has caused the system
to allocate new space on the WORM; the units are mega-
bytes.
clearacct
Clears the accounting records for acct.
Page 4 Plan 9 (printed 12/21/24)
FS(8) FS(8)
Date prints the current date. It may be adjusted using
+-seconds. With no sign, it sets the date to the absolute
number of seconds since 00:00 Jan 1, 1970 GMT; with a sign
it trims the current time.
Disallow restores permission checking back to normal after a
file system has been initialized.
Duallow sets permissions such that the named user can read
and search any directories. This is the permission neces-
sary to do a du(1) command anywhere in the file system to
discover disk usage.
Dump starts a dump to WORM immediately for the named
filesystem, or the current filesystem if none is named.
File service is suspended while the cache is scanned; ser-
vice resumes when the copy to WORM starts.
Files prints for every connection the number of allocated
fids.
Fstat prints the current status of each named file, includ-
ing uid, gid, wuid (uid of the last user to modify the
file), size, qid, and disk addresses.
Flag toggles flags, initially all off:
allchans Print channels in who output.
arp Report ARP activity.
attach Report as connections are made to the file
server.
authdebug Report authentications.
authdisable Disable authentication.
chat (Very noisy.) Print all 9P messages to and
from the server.
error Report 9P errors.
il Report IL errors.
route Report received RIP packets.
ro Report I/O on the WORM device.
sntp Report SNTP activity.
If given a second numeric channel argument, as reported by
who, the flag is altered only on that connection.
Halt does a sync and halts the machine, returning to the
boot ROM.
Hangup clunks all the fids on the named channel, which has
the same format as in the output of the who command.
Newuser requires a name argument. With no options it adds
user name, with group leader name, to /adm/users and makes
Page 5 Plan 9 (printed 12/21/24)
FS(8) FS(8)
the directory /usr/name owned by user and group name. The
options are
? Print the entry for name.
: Add a group: add the name to /adm/users but don't
create the directory. By convention, groups are
numbered starting from 10000, users from 0.
newname Rename existing user name to newname.
=leader Change the leader of name to leader. If leader is
missing, remove the existing leader.
+member Add member to the member list of name.
-member Remove existing member from the member list of
name.
After a successful newuser command the file server over-
writes /adm/users to reflect the internal state of the user
table.
Noattach disables attach(5) messages, in particular for sys-
tem maintenance. Previously attached connections are unaf-
fected. Another noattach will enable normal behavior.
Passwd sets the machine's password and writes it in non-
volatile RAM.
Printconf prints the system configuration information.
Profile 1 clears the profiling buffer and enables profiling;
profile 0 stops profiling and writes the data to
/adm/kprofdata for use by kprof (see prof(1)). If a number
is not specified, the profiling state toggles.
Remove removes files.
Route maintains an IP routing table. The subcommands are:
add dest gate [mask]
Add a static route from IP address dest
using gateway gate with an optional sub-
net mask.
delete dest Delete an entry from the routing table.
print Display the contents of the routing
table.
ripon Enables the table to be filled from RIP
packets.
ripoff Disables the table from being updated by
RIP packets.
Sntp kick queries the SNTP server (see fsconfig(8)) and sets
the time with its response.
The stat commands are connected with a service or device
Page 6 Plan 9 (printed 12/21/24)
FS(8) FS(8)
identified by the last character of the name: d, SCSI tar-
gets; e, Ethernet controllers; i, IDE/ATA targets; m, Mar-
vell SATA targets; w, cached WORM. The stata command prints
overall statistics about the file system. The stats command
takes an optional argument identifying the characters of
stat commands to run. The option is remembered and becomes
the default for subsequent stats commands if it begins with
a minus sign.
Sync writes dirty blocks in memory to the magnetic disk
cache.
Time reports the time required to execute the command.
Trace with no options prints the set of queue-locks held by
each process in the file server. If things are quiescent,
there should be no output. With an argument number it
prints a stack traceback of that process.
Users uses the contents of file (default /adm/users) to ini-
tialize the file server's internal representation of the
users structure. Incorrectly formatted entries in file will
be ignored. If file is explicitly default, the system
builds a minimal functional users table internally; this can
help recover from disasters. If the file cannot be read,
you must run
users default
for the system to function. The default table looks like
this:
-1:adm:adm:
0:none:adm:
1:tor:tor:
10000:sys::
10001:map:map:
10002:doc::
10003:upas:upas:
10004:font::
10005:bootes:bootes:
Version reports when the file server was last compiled and
last rebooted.
Who reports, one per line, the names of users connected to
the file server and the status of their connections. The
first number printed on each line is the channel number of
the connection. If users are given the output selects con-
nections owned by those users.
Wormeject moves the WORM disk in slot tunit of the first
Page 7 Plan 9 (printed 12/21/24)
FS(8) FS(8)
jukebox to the output shelf.
Wormingest moves the WORM disk from the input shelf of the
first jukebox to slot tunit.
Wormoffline takes drive of the first jukebox out of service;
wormonline puts it back in service.
Wormreset put discs back where the jukebox thinks they
belong, and does this for all jukeboxes.
When the file server boots, it prints the message
for config mode hit a key within 5 seconds
If a character is typed within 5 seconds of the message
appearing, the server will enter config mode. See
fsconfig(8) for the commands available in config mode. The
system also enters config mode if, at boot time, the non-
volatile RAM does not appear to contain a valid configura-
tion.
Exsort is a regular command to be run on a CPU server, not
on the file server console. It reads the named file
(default /adm/cache) and sorts the cache disk block numbers
contained therein. It assumes the numbers are 4-byte inte-
gers and guesses the endianness by looking at the data. It
then prints statistics about the cache. With option -w it
writes the sorted data back to file.
SEE ALSO
fs(4)
Ken Thompson, ``The Plan 9 File Server''.
SOURCE
/sys/src/fs
/sys/src/cmd/disk/exsort.c
BUGS
The worm* commands should accept an argument identifying a
jukebox.
Page 8 Plan 9 (printed 12/21/24)