NAME
fs, exsort – file server maintenance

SYNOPSIS
help [ command ... ]

allow [uid]

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.

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 for the specified uid or for any user if omitted. This may help in initializing a file system. Use this with caution.

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 suspends 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 determined 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 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. rtmp    Removes temporary files after a recovery from worm. After a cache ream and recover, temporary files and directories refer to invalid data blocks producing checktag errors on access. To get rid of these errors, the rtmp flag can be used with the check command which will truncate temporary directories and
remove temporary files.

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 storage associated with files. It ignores the usual rules for sanity, such as checking against removing a non–empty directory. 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 mvstate dump write aborts the background process dumping 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 containing the roots of the dumped file systems, starting at block number start (default 0) going forward (backwards if back–flag is supplied and is non–zero).
searchtag [start] [tag] [blocks]
Reads the WORM device starting at block start and proceeding 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.
acctPrints how many times each user has caused the system to allocate new space on the WORM; the units are megabytes.
clearacct
Clears the accounting records for acct.

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 necessary 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; service 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, including 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 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 overwrites /adm/users to reflect the internal state of the user table.

Noattach disables attach(5) messages, in particular for system maintenance. Previously attached connections are unaffected. 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 subnet 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 identified by the last character of the name: d, SCSI targets; e, Ethernet controllers; i, IDE/ATA targets; m, Marvell 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 initialize 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 connections owned by those users.

Wormeject moves the WORM disk in slot tunit of the first 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 configuration.

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