.TH FS 8
.SH NAME
fs, exsort \- file server maintenance
.SH SYNOPSIS
.PD 0
.B help
[
.I command ...
]
.PP
.B arp
.I subcommand
.PP
.B cfs
.I filesystem
.PP
.B check
.RI [ options ]
.PP
.B clri
.RI [ file ...]
.PP
.B cpu
.RI [ proc ]
.PP
.B create
.I path uid gid perm
.RB [ lad ]
.PP
.B cwcmd
.I subcommand
.PP
.B cycl
.I subcommand
.PP
.B date
.RB [[ +- ]
.IR seconds ]
.PP
.B duallow
.RI [ uid ]
.PP
.B dump
.PP
.B files
.PP
.B flag
.I flag
[
.I channel
]
.PP
.B halt
.PP
.B newuser
.I name
.RI [ options ]
.PP
.B noattach
.PP
.B passwd
.PP
.B profile
.RB [ 01 ]
.PP
.B remove
.RI [ files ...]
.PP
.B route
.I subcommand
.PP
.BR stat [ acdejklw ]
.PP
.B stats
.RB [[ - ]
.IR flags ...]
.PP
.B sync
.PP
.B time
.I command
.PP
.B trace
.RI [ number ]
.PP
.B users
.RI [ file ]
.PP
.B vcache
.PP
.B version
.PP
.B who
.RI [ user ...]
.PP
.B wormcp
[
.I funit
.I tunit
.RI [ nblock ]]
.PP
.B wormeject
[
.I tunit
]
.PP
.B wormingest
[
.I tunit
]
.PP
.B wormoffline
[
.I tunit
]
.PP
.B wormonline
[
.I tunit
]
.PD
.PP
.B disk/exsort
.RB [ -w ]
.RI [ file ]
.SH DESCRIPTION
Except for
.IR exsort ,
these commands are available only on the console of an
.IR fs (4)
file server.
.PP
The console requires the machine's password to be supplied before
accepting commands.  Typing a control-D will cause
the server to request
the password again.
.PP
.I Help
prints a `usage string' for the named
.IR commands ,
by default all commands.
Also, many commands print menus of their options if given
incorrect or incomplete parameters.
.PP
.I Arp
has two
.IR subcommands :
.B print
prints the contents of the ARP cache and
.B flush
flushes it.
.PP
.I Cfs
changes the current file system, that is, the file tree to which
commands
.RB ( check ,
.BR clri ,
.BR create ,
.BR newuser ,
.BR profile ,
.BR remove ,
and
.BR users )
apply.
The initial
.I filesystem
is
.BR main .
.PP
.I 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:
.TF touch
.PD
.TP
.B rdall
Read every block in the file system (can take a
.I long
time).
Normally,
.I check
will stop short of the actual contents
of a file and just verify the block addresses.
.TP
.B tag
Fix bad
.IR tags ;
each block has a tag that acts as a backwards pointer for
consistency checking.
.TP
.B ream
Fix bad tags
and also clear the contents
of blocks that have bad tags.
.TP
.B pfile
Print every file name.
.TP
.B pdir
Print every directory name.
.TP
.B 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.
.TP
.B 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
.I check
to find the bad file
(by number of diagnostic messages)
and then use
.I clri
to clear the addresses in that file.
After that,
.I check
can be used to reclaim the free list.
.TP
.B 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.
.PP
.I Clri
clears the internal directory entry and abandons storage
associated with
.IR files .
It ignores the usual rules for sanity, such as checking against
removing a non-empty directory.
A subsequent
.B check
.B free
will place the abandoned storage in the free list.
.PP
.I 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.
.PP
.I Create
creates a file on the current file system.
.I Uid
and
.I gid
are names or numbers from
.BR /adm/users .
.I Perm
is the low 9 bits of the permission mode of the file, in octal.
An optional final
.BR l ,
.BR a ,
or
.BR d
creates a locked file, append-only file, or directory.
.PP
.I Cwcmd
controls the cached WORM file systems.  The subcommands are:
.TP
.BI mvstate " state1 state2 " [ platter ]
States are
.BR none ,
.BR dirty ,
.BR dump ,
.BR dump1 ,
.BR error ,
.BR read ,
and
.BR write .
A
.B mvstate
.B dump1
.B dump
will cause I/O errors in the last dump to be retried.
A
.B mvstate
.B dump1
.B write
will cause I/O errors in the last dump to be retried in
reallocated slots in the next dump.
A
.B mvstate
.B read
.B none
will flush the cache associated with the WORM.
A
.B mvstate
.B dump
.B 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
.I platter
limits affected blocks to those on that platter.
.TP
.BR prchain " [\fIstart\fP] [\fLback\fP]
Print the chain of superblocks for the directory containing the
roots of the dumped file systems, starting at block number
.I start
(default 0) going forward (backwards if
.B back
is supplied).
.TP
.BR savecache " [\fIpercent\fP]
Copy the block numbers, in native endian longwords, of blocks in the
.B read
state to the file
.BR /adm/cache
for use by
.BR disk/exsort .
If an argument is given,
then that percent (most recently used) of each cache bucket
is copied.
.TP
.BR loadcache " [\fIdskno\fP]
Read
.B /adm/cache
and for every block there on WORM disk
.IR dskno ,
read the block from WORM to the cache.
If
.I dskno
is not supplied, all blocks in
.B /adm/cache
are read.
.TP
.BR startdump \ [ 01 ]
Suspend
.RB ( 0 )
or restart
.RB ( 1 )
the background dump process.
.TP
.B touchsb
Verify that the superblock on the WORM is readable, ignoring the cached copy.
.TP
.B acct
Prints how many times each user has caused the system to allocate new space on the WORM;
the units are megabytes.
.TP
.B clearacct
Clears the accounting records for
.BR acct .
.PP
.I Cycl
controls the Cyclone fiber link to the main CPU server.
The one subcommand is
.BR reboot ,
which reinitializes the Cyclone board and connection.
.PP
.I Date
prints the current date.  It may be adjusted
using
.BI +- seconds\f1.
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.
.PP
.I Duallow
sets permissions such that
the named
.I user
can read and search any directories.
This is the permission necessary to do a
.IR du (1)
command anywhere in the file system to discover disk usage.
.PP
.I Dump
starts a dump to WORM immediately for all file systems that have
a WORM associated.
File service is suspended while the cache is scanned;
service resumes when the copy to WORM starts.
.PP
.I Files
prints for every connection the number of allocated fids.
.PP
.I Flag
toggles flags, initially all off:
.TF attachxx
.TP
.B arp
Report ARP activity.
.TP
.B attach
Report as connections are made to the file server.
.TP
.B chat
(Very noisy.)  Print all 9P messages to and from the server.
.TP
.B dkit
Report Datakit activity.
.TP
.B route
Report received RIP packets.
.TP
.B ro
Report I/O on the WORM device.
.PD
.PP
If given a second numeric
.I channel
argument,
as reported by
.IR who ,
the flag is altered only on that connection.
.PP
.I Halt
does a
.B sync
and halts the machine, returning to the boot ROM.
.PP
.I Newuser
requires a
.I name
argument.
With no options it adds user
.IR name ,
with group leader
.IR name ,
to
.B /adm/users
and makes the directory
.BI /usr/ name
owned by user and group
.IR name .
The options are
.TF =leaderxx
.TP
.B ?
Print the entry for
.IR name .
.TP
.B :
Add a group: add the name to
.B /adm/users
but don't create the directory.
By convention, groups are numbered starting from 10000, users from 0.
.TP
.I newname
Rename existing user
.I name
to
.IR newname .
.TP
.BI = leader
Change the leader of
.I name
to
.IR leader .
If
.I leader
is missing, remove the existing leader.
.TP
.BI + member
Add
.I member
to the member list of
.IR name .
.TP
.BI - member
Remove existing
.I member
from the member list of
.IR name .
.PD
.PP
After a successful
.I newuser
command the file server overwrites
.B /adm/users
to reflect the internal state of the user table.
.PP
.I Noattach
disables
.IR attach (5)
messages, in particular for system maintenance.
Previously attached connections are unaffected.
Another
.I noattach
will enable normal behavior.
.PP
.I Passwd
sets the machine's password and writes it in non-volatile RAM.
.PP
.I Profile
.B 0
clears the profiling buffer and enables profiling;
.I profile
.B 1
stops profiling and writes the data to
.B /adm/kprofdata
for use by
.B kprof
(see
.IR prof (1)).
If a number is not specified, the profiling state toggles.
.PP
.I Remove
removes
.IR files .
.PP
.I Route
maintains an IP routing table.  The
.I subcommands are:
.TF "add dest gate mask"
.TP
.B add \f2dest gate \fP[\f2mask\fP]
Add a static route from IP address
.I dest
using gateway
.I gate
with an optional subnet
.IR mask .
.TP
.B delete \f2dest\fP
Delete an entry from the routing table.
.TP
.B print
Display the contents of the routing table.
.TP
.B ripon
Enables the table to be filled from RIP packets.
.TP
.B ripoff
Disables the table from being updated by RIP packets.
.PD
.PP
The
.I stat
commands are connected with a service or device identified by the
last character of the name:
.BR c ,
Cyclone fiber link;
.BR d ,
SCSI targets;
.BR e ,
Eagle Ethernet controller;
.BR j ,
Jaguar SCSI/VME disk controller;
.BR k ,
Datakit;
.BR l ,
LANCE Ethernet controller;
.BR w ,
cached WORM.
The
.I Statp
command prints statistics about processes; an optional argument identifies the
process to be displayed;
.I stata
prints overall statistics about the file system.
The
.I stats
command takes an optional argument identifying the characters
of
.I stat
commands to run.  The option is remembered and becomes the
default for subsequent
.I stats
commands if it begins with a minus sign.
.PP
.I Sync
writes dirty blocks in memory to the magnetic disk cache.
.PP
.I Time
reports the time required to execute the
.IR command .
.PP
.I 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
.I number
it prints a stack traceback of that process.
.PP
.I Users
uses the contents of
.I file
(default
.BR /adm/users )
to initialize the file server's internal representation of the users
structure.
Incorrectly formatted entries in
.I file
will be ignored.
If file is explicitly
.BR default ,
the system builds a minimal functional users table internally;
this can help recover from disasters.
If the
.I file
cannot be read, you
.I must
run
.IP
.EX
users default
.EE
.PP
for the system to function.  The
.B default
table looks like this:
.IP
.EX
-1:adm:adm:
0:none:adm:
1:tor:tor:
10000:sys::
10001:map:map:
10002:doc::
10003:upas:upas:
10004:font::
10005:bootes:bootes:
.EE
.PP
.I Vcache
displays statistics about the virtual buffer cache on machines with mapped
caches such as the Sparcstation 2.
.PP
.I Version
reports when the file server was last compiled and last rebooted.
.PP
.I 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
.I users
are given the output selects connections owned by those users.
.PP
.I Wormcp
copies from WORM disk
.I funit
to WORM disk
.I tunit
.I nblock
native blocks (default the whole disk).
If
.I tunit
is written,
.I wormcp
guarantees the written data is equal to the data on
.I funit
and stops if not.
.I Wormcp
does a binary search to find the lowest unwritten block on
.I tunit
at which to start the copy.
With no arguments,
.I wormcp
stops a running copy.
.PP
.I Wormeject
moves the WORM disk in slot
.I tunit
to the output shelf.
.PP
.I Wormingest
moves the WORM disk from the input shelf to
slot
.IR tunit .
.PP
.I Wormoffline
will take the designated
WORM controller out of service.
This is done in software by
ignoring that logical unit when
changing platters.
Note that the controller will
be restored on a reboot.
.PP
.I Wormonline
will restore the designated
.I unit
to service.
.PP
When the file server boots, it prints the message
.IP
.EX
for config mode hit a key within 5 seconds
.EE
.PP
If a character is typed within 5 seconds of the message appearing,
the server will enter config mode.
See
.IR 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.
.PP
.I Exsort
is a regular command to be run on a CPU server, not on the file server
console.
It reads the named
.I file
(default
.BR /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
.B -w
it writes the sorted data back to
.IR file .
.SH SOURCE
.B /sys/src/fs
.br
.B /sys/src/cmd/disk/exsort.c
.SH SEE ALSO
.IR fs (4)
.br
Ken Thompson,
``The Plan 9 File Server''.
