plan9fox/sys/man/8/fs

.TH FS 8
.SH NAME
fs, exsort \- file server maintenance
.SH SYNOPSIS
.PD 0
.B help
[
.I command ...
]
.PP
.B allow
.RI [ uid ]
.PP
.B arp
.I subcommand
.PP
.B cfs
.I filesystem
.PP
.B check
.RI [ options ]
.PP
.B clean
.I file
[
.I bno
[
.I addr
] ]
.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 date
.RB [[ +- ]
.IR seconds ]
.PP
.B disallow
.PP
.B duallow
.RI [ uid ]
.PP
.B dump
[
.I filesystem
]
.PP
.B files
.PP
.B flag
.I flag
[
.I channel
]
.PP
.B fstat
[
.I files
]
.PP
.B halt
.PP
.B hangup
.I channel
.PP
.B newuser
.I name
.RI [ options ]
.PP
.B noattach
.PP
.B passwd
.PP
.B printconf
.PP
.B profile
.RB [ 01 ]
.PP
.B remove
.RI [ files ...]
.PP
.B route
.I subcommand
.PP
.B "sntp kick"
.PP
.BR stat [ admiesw ]
.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 version
.PP
.B who
.RI [ user ...]
.PP
.B wormeject
[
.I tunit
]
.PP
.B wormingest
[
.I tunit
]
.PP
.B wormoffline
.I drive
.PP
.B wormonline
.I drive
.PP
.B wormreset
.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 Allow
disables permission checking and allows
.BR wstat
for the specified
.I uid
or for any user if omitted.
This may help in initializing a file system.
Use this with caution.
.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 clean ,
.BR clri ,
.BR create ,
.BR cwcmd ,
.BR dump ,
.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.
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
.I missing
blocks.
These
.I missing
blocks are actually on the free list and the true
state of the filesystem can be determined by running
.I check
with no arguments.
.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.
.TP
.B trim
reduces the file system's
.I 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
.B "check free"
afterward will construct a new free list that contains no
blocks outside the new, smaller file system.
.TP
.B 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
.I rtmp
flag can be used with the
.I check
command which will truncate temporary directories
and remove temporary files.
.PP
.I Clean
prints the block numbers in
.IR file 's
directory entry (direct, indirect and doubly indirect)
and checks the tags of the blocks cited.
If
.I bno
is supplied, the
.IR bno 'th
block number (using zero origin)
is set to
.I addr
(defaults to zero).
Note that only the block numbers in the directory entry itself
are examined;
.I clean
does not recurse through indirect blocks.
.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,
specifically the current file system.
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] [\fIback-flag\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
.I back-flag
is supplied and is non-zero).
.TP
.BR searchtag " [\fIstart\fP] [\fItag\fP] [\fIblocks\fP]
Reads the WORM device starting at block
.I start
and proceeding for
.I blocks
blocks (default 1000)
until it finds a block with numeric tag
.IR tag .
.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 side
.I dskno
(zero-origin),
read the block from WORM to the cache.
If
.I dskno
is not supplied, all blocks in
.B /adm/cache
are read.
.TP
.BR morecache " dskno [\fIcount\fP]
Read
.I count
blocks from the beginning of WORM disk side
.I dskno
to the cache.
If no count is given,
read all of side
.IR dskno
into the cache.
.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
.BR blockcmp " [\fIwbno\fP] [\fIcbno\fP]
Compares the WORM block
.I wbno
with the cache block
.I cbno
and prints the first 10 differences, if any.
.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 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 Disallow
restores permission checking back to normal after a file system
has been initialized.
.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
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.
.PP
.I Files
prints for every connection the number of allocated fids.
.PP
.I Fstat
prints the current status of each named
.IR file ,
including uid, gid, wuid (uid of the last user to modify the file),
size, qid, and disk addresses.
.PP
.I Flag
toggles flags, initially all off:
.TF authdisablexx
.TP
.B allchans
Print channels in
.I who
output.
.TP
.B arp
Report ARP activity.
.TP
.B attach
Report as connections are made to the file server.
.TP
.B authdebug
Report authentications.
.TP
.B authdisable
Disable authentication.
.TP
.B chat
(Very noisy.)  Print all 9P messages to and from the server.
.TP
.B error
Report 9P errors.
.TP
.B il
Report IL errors.
.TP
.B route
Report received RIP packets.
.TP
.B ro
Report I/O on the WORM device.
.TP
.B sntp
Report SNTP activity.
.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 Hangup
clunks all the fids on the named
.IR channel ,
which has the same format as in the output of the
.I who
command.
.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 Printconf
prints the system configuration information.
.PP
.I Profile
.B 1
clears the profiling buffer and enables profiling;
.I profile
.B 0
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
.I Sntp
.I kick
queries the SNTP server
(see
.IR fsconfig (8))
and sets the time with its response.
.PP
The
.I stat
commands are connected with a service or device identified by the
last character of the name:
.BR d ,
SCSI targets;
.BR e ,
Ethernet controllers;
.BR i ,
IDE/ATA targets;
.BR m ,
Marvell SATA targets;
.BR w ,
cached WORM.
The
.I stata
command 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 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 Wormeject
moves the WORM disk in slot
.I tunit
of the first jukebox to the output shelf.
.PP
.I Wormingest
moves the WORM disk from the input shelf of the first jukebox to slot
.IR tunit .
.PP
.I Wormoffline
takes
.I drive
of the first jukebox out of service;
.I wormonline
puts it back in service.
.PP
.I Wormreset
put discs back where the jukebox thinks they belong,
and does this for all jukeboxes.
.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 SEE ALSO
.IR fs (4)
.br
Ken Thompson,
``The Plan 9 File Server''.
.SH SOURCE
.B /sys/src/fs
.br
.B /sys/src/cmd/disk/exsort.c
.SH BUGS
The
.B worm*
commands should accept an argument identifying a jukebox.