check that link() doesn't cause statinfo to be corrupted/reverted for

[arla.git] / appl / fs / fs.1

.\" Copyright (c) 2000 - 2005 Kungliga Tekniska Högskolan
.\" (Royal Institute of Technology, Stockholm, Sweden).
.\" All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" 3. Neither the name of the Institute nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     $Id$
.\"
.Dd April 13, 2005
.Dt FS 1
.Os "The Arla Project"
.Sh NAME
.Nm fs
.Nd Manage AFS directories
.Sh SYNOPSIS
.Nm
.Op Ar command
.Op Ar args
.Sh DESCRIPTION
The
.Nm
utility is used to manipulate the AFS filesystem.
Note that the
.Nm
utility does
.Em not
modify the traditional
.Ux
filesystem, only files in AFS.
.Pp
The
.Nm
utility provides several commands:
.Pp
.Bl -tag -width setmaxpriority -compact
.It Cm apropos
locate commands by keyword
.It Cm arladebug
tweek arla-debugging flags
.It Cm checkservers
check if servers are up
.It Cm checkvolumes
check that all volume mapping are correct
.It Cm cleanacl
not yet implemented
.It Cm copyacl
not yet implemented
.It Cm diskfree
show free partition space
.It Cm examine
examine volume status
.It Cm flush
remove file from cache
.It Cm flushvolume
remove volumedata (and files in volume) from cache
.It Cm gcpags
garbage collect pags
.It Cm getcacheparms
get cache usage
.It Cm getcalleraccess
get current user's access permisssions
.It Cm gca
shorthand for the
.Cm getcalleraccess
command
.It Cm getcrypt
get encrypt status
.It Cm getcellstatus
get suid cell status
.It Cm getfid
get fid
.It Cm getserverprefs
not yet implemented
.It Cm getstatistics
get statistics from the cache manager
.It Cm getpriority
get priority of a file/dir
.It Cm gp
shorthand for the
.Cm getpriority
command
.It Cm getmaxpriority
get max priority for a file gc
.It Cm gmp
shorthand for the
.Cm getmaxpriority
command
.It Cm help
get help for
.Nm
.It Cm incompat
report interface of the pioctl interface
.It Cm listacl
show acl
.It Cm la
shorthand for the
.Cm listacl
command
.It Cm listcells
list cells that the cache handler can communicate with
.It Cm listquota
show volume quota
.It Cm lq
shorthand for the
.Cm listquota
command
.It Cm quota
shorthand for the
.Cm listquota
command
.It Cm lsmount
show a mount point
.It Cm messages
not yet implemented
.It Cm mkmount
create mount point
.It Cm mkm
shorthand for the
.Cm mkmount
command
.It Cm connect
connect mode
.It Cm monitor
set remote logging host
.It Cm newcell
add new cell
.It Cm nop
do a pioctl-nop
.It Cm quit
leave interactive mode
.It Cm exit
leave interactive mode
.It Cm rmmount
delete a mount point
.It Cm removepriority
remove priority from file/directory
.It Cm rmp
shorthand for the
.Cm removepriority
command
.It Cm setacl
add an acl entry on a directory
.It Cm sa
shorthand for the
.Cm setacl
command
.It Cm setcachesize
change disk cache size
.It Cm setcell
change cell status
.It Cm setpriority
set priority of a file/directory
.It Cm sp
shorthand for the
.Cm setpriority
command
.It Cm setmaxpriority
set upper limit of prio gc
.It Cm smq
shorthand for the
.Cm setmaxpriority
command
.It Cm setquota
change quota on a volume
.It Cm sq
shorthand for the
.Cm setquota
command
.It Cm setserverprefs
not yet implemented
.It Cm setcrypt
set encryption on/off
.It Cm setvol
not yet implemented
.It Cm suidcells
list status of cells
.It Cm sysname
read/change sysname
.It Cm version
get version of fs and fs_lib
.It Cm venuslog
make arlad print status
.It Cm whereis
show server(s) of file
.It Cm whichcell
show cell of file
.It Cm wscell
display cell of workstation
.It Cm nnpfsdebug
tweek nnpfs-debugging flags
.It Cm nnpfsprint
make nnpfs print debug info
.El
.Pp
.Bd -filled -offset indent -compact
.Ed
The syntax of the
.Nm
commands:
.Pp
.Ic fs apropos
.Bd -filled -offset indent -compact
Locate commands by keyword
.Ed
.Pp
.Ic fs arladebug
.Op Ar flags
.Bd -filled -offset indent -compact
Tweek arla-debugging flags.
.Ed
.Pp
.Ic fs checkservers
.Op Fl cell Ar cellname
.Op Fl nopoll
.Bd -filled -offset indent -compact
Check if the servers in a cell are available.
If
.Fl nopoll
is specified, the servers are not contactad; only internal information is
printed.
.Ed
.Pp
.Ic fs checkvolumes
.Bd -filled -offset indent -compact
Check that all volume mapping are correct and flush all mountpoints
from the cache to force them to be reread.
.Ed
.Pp
.Ic fs cleanacl
.Bd -filled -offset indent -compact
Not yet implemented.
.Ed
.Pp
.Ic fs copyacl
.Bd -filled -offset indent -compact
Not yet implemented.
.Ed
.Pp
.Ic fs diskfree
.Ar path
.Bd -filled -offset indent -compact
Show free space on the partition where the file or directory
.Ar path
is stored
.Ed
.Pp
.Ic fs examine
.Op Ar path
.Bd -filled -offset indent -compact
Print detailed information about the volume mounted on the specified
.Ar path
or the current directory.
.Ed
.Pp
.Ic fs flush
.Ar file
.Bd -filled -offset indent -compact
Flush
.Ar file
from the cache, causing it to be stored on the fileserver.
.Ed
.Pp
.Ic fs flushvolume
.Ar file
.Bd -filled -offset indent -compact
Flush all the files in the volume where the
.Ar file
is stored, causing them to be stored on the fileserver.
Meta information about the volume is also flushed.
.Ed
.Pp
.Ic fs gcpags
.Bd -filled -offset indent -compact
Remove unused PAGs from the kernel.
.Ed
.Pp
.Ic fs getcacheparms
.Bd -filled -offset indent -compact
Print information about cache usage.
.Ed
.Pp
.Ic fs getcalleraccess
.Op Ar path
.Bd -filled -offset indent -compact
Show current user's permissions for the specified
.Ar path
or the current directory.
.Ed
.Pp
.Ic fs gca
.Op Ar path
.Bd -filled -offset indent -compact
Shorthand for the
.Cm getcalleraccess
command.
.Ed
.Pp
.Ic fs getcrypt
.Bd -filled -offset indent -compact
Display whether traffic between the client and server is encrypted.
.Ed
.Pp
.Ic fs getcellstatus
.Ar cellname
.Bd -filled -offset indent -compact
Indicate if the setuid bit on executable files are honored for
the specified cell.
.Ed
.Pp
.Ic fs getfid
.Ar path
.Bd -filled -offset indent -compact
Print fid information for a file.
.Ed
.Pp
.Ic fs getserverprefs
.Bd -filled -offset indent -compact
Not yet implemented.
.Ed
.Pp
.Ic fs getstatistics
.Bd -filled -offset indent -compact
Get statistics from the cache manager.  Possible type to get statistics
for are fetchstatus, fetchdata, storestatus, storedata, bulkstatus.
.Ed
.Pp
.Ic fs getpriority
.Bd -filled -offset indent -compact
Display priority of a file or directory.
.Ed
.Pp
.Ic fs gp
.Bd -filled -offset indent -compact
Shorthand for the
.Cm getpriority
command
.Ed
.Pp
.Ic fs getmaxpriority
.Bd -filled -offset indent -compact
Display max priority for a file.
.Ed
.Pp
.Ic fs gmp
.Bd -filled -offset indent -compact
Shorthand for the
.Cm getmaxpriority
command.
.Ed
.Pp
.Ic fs help
.Bd -filled -offset indent -compact
Get help for
.Nm
.Ed
.Pp
.Ic fs incompat
.Bd -filled -offset indent -compact
Returns what interface of the pioctl interface currently is in use.
.Ed
.Pp
.Ic fs listacl
.Op Ar path
.Bd -filled -offset indent -compact
Show acl for the specified
.Ar path
or the current directory.
.Ed
.Pp
.Ic fs la
.Op Ar path
.Bd -filled -offset indent -compact
Shorthand for the
.Cm listacl
command.
.Ed
.Pp
.Ic fs listcells
.Bd -filled -offset indent -compact
List cells that the cache handler can communicate with.
These are the cells listed in the file
.Pa CellServDB .
.Ed
.Pp
.Ic fs listquota
.Op Ar path
.Bd -filled -offset indent -compact
Show the quota for the volume of the specified
.Ar path
or the current directory.
.Ed
.Pp
.Ic fs lq
.Op Ar path
.Bd -filled -offset indent -compact
Shorthand for the
.Cm listquota
command.
.Ed
.Pp
.Ic fs quota
.Bd -filled -offset indent -compact
Shorthand for the
.Ic listquota
command.
.Ed
.Pp
.Ic fs lsmount
.Ar path
.Bd -filled -offset indent -compact
Show a mount point.
.Ed
.Pp
.Ic fs messages
.Bd -filled -offset indent -compact
Not yet implemented.
.Ed
.Pp
.Ic fs mkmount
.Ar directory
.Ar volume
.Op Fl cell Ar cell
.Op Fl rw
.Bd -filled -offset indent -compact
Create a mountpoint pointing to
.Ar volume
in optional
.Ar cell .
If
.Fl rw
is given, a mountpoint to the readwrite volume is created.
.Pp
Note that there must not exist a directory named like
the mount point you are creating.
.Ed
.Pp
.Ic fs connect
.Op Ar mode
.Bd -filled -offset indent -compact
Set or get connected mode, if a
.Ar mode
is specified, the cache manager will be set to that mode.
If not, the current mode will be printed.
.Pp
Valid modes are:
.Bl -tag -width -Fl -compact
.It Cm connected
Connected mode - this is the normal operating mode.
.It Cm fetch
Fetch only mode - files are retrieved from fileserver but are not stored back.
.It Cm disconnected
Disconnected mode - files are read and written from/to the cache, and no
attempt is made to contact a fileserver-
.El
.Pp
Disconnected mode is very useful for machines that are not connected to
the network at all times, such as laptops.
Disconnected mode is to be considered very experimental at this stage.
.Ed
.Pp
.Ic fs monitor
.Bd -filled -offset indent -compact
Not yet implemented.
.Ed
.Pp
.Ic fs newcell
.Fl cell Ar cellname
.Fl servers Ar vldb-servers
.Op Fl help
.Bd -filled -offset indent -compact
Add a new cell to the running configuration of the cache manager, or update
already existing information.
This information should also be entered in the file
.Pa /usr/arla/etc/CellServDB .
.Ed
.Pp
.Ic fs nop
.Bd -filled -offset indent -compact
Do a pioctl-nop.
This is useful for debugging.
.Ed
.Pp
.Ic fs quit
.Bd -filled -offset indent -compact
Leave interactive mode.
.Ed
.Pp
.Ic fs exit
.Bd -filled -offset indent -compact
Leave interactive mode.
.Ed
.Pp
.Ic fs rmmount
.Ar mountpoint
.Bd -filled -offset indent -compact
Delete
.Ar mountpoint .
.Ed
.Pp
.Ic fs removepriority
.Ar path
.Bd -filled -offset indent -compact
Remove priority from file or directory
.Ar path .
.Ed
.Pp
.Ic fs rmp
.Bd -filled -offset indent -compact
Shorthand for the
.Cm removepriority
command.
.Ed
.Pp
.Ic fs setacl
.Ar directory
.Ar permissions
.Bd -filled -offset indent -compact
Add an acl entry on a directory.
Each entry consists of two components:
a user or group and a character string describing the permissions granted
for that user or group.
These characters and the permission they represent are:
.Bl -tag -width Fl -compact
.It Cm r
read the files
.It Cm l
list the files
.It Cm i
insert new files
.It Cm d
delete files
.It Cm w
write (change) the files
.It Cm k
lock files
.It Cm a
administer the acl, that is, to change the acl
.El
.Pp
There are also a few convinience strings recognized by
.Ic fs setacl :
.Bl -tag -width Fl -compact
.It Cm none
removes all permissions.
.It Cm read
adds 'rl' permissions, which are suitable for a read-only directory.
.It Cm write
adds all permissions except 'a', that is, the user/group can read, write,
delete etc. but not change the acl of the directory.
.It Cm all
add all permissions.
.El
.Pp
Note that in AFS you set the permissions on a directory, and the permissions
of a file are those of their directory.
So, if you move a file from one
directory to another, you might change the permission of the file, as
the two directories may have different permissions.
.Pp
Of the traditional
.Ux
permission bits only the user part is honored, and is used for any
user permissioned by the directorys acl.
The group and world permission bits are ignored, but they are stored.
.Ed
.Pp
.Ic fs sa
.Ar directory
.Ar permissions
.Bd -filled -offset indent -compact
Shorthand for the
.Cm setacl
command.
.Ed
.Pp
.Ic fs setcachesize
.Ar lowvnodes
.Op Ar highvnodes Ar lowbytes Ar highbytes
.Bd -filled -offset indent -compact
Set the size of the disk cache.
.Ed
.Pp
.Ic fs setcell
.Bd -filled -offset indent -compact
Not yet implemented.
.Ed
.Pp
.Ic fs setpriority
.Ar file
.Ar priority
.Bd -filled -offset indent -compact
Set priority of a file/directory.
.Ed
.Pp
.Ic fs sp
.Bd -filled -offset indent -compact
Shorthand for the
.Cm setpriority
command.
.Ed
.Pp
.Ic fs setmaxpriority
.Ar priority
.Bd -filled -offset indent -compact
Set upper limit of priority.
.Ed
.Pp
.Ic fs smq
.Bd -filled -offset indent -compact
Shorthand for the
.Cm setmaxpriority
command.
.Ed
.Pp
.Ic fs setquota
.Ar path
.Ar quota
.Bd -filled -offset indent -compact
Set the
.Ar quota
(in Kbytes) on a volume pointed out by
.Ar path .
.Ed
.Pp
.Ic fs sq
.Bd -filled -offset indent -compact
Shorthand for the
.Cm setquota
command.
.Ed
.Pp
.Ic fs setserverprefs
.Bd -filled -offset indent -compact
Not yet implemented.
.Ed
.Pp
.Ic fs setcrypt
.Ar yes | no
.Bd -filled -offset indent -compact
If
.Ar no
is specified, encryption of the traffic to/from fileservers is
disabled, and if
.Ar yes
is specified, it is enabled.
.Ed
.Pp
.Ic fs setvol
.Bd -filled -offset indent -compact
Not yet implemented.
.Ed
.Pp
.Ic fs suidcells
.Bd -filled -offset indent -compact
Print cells and whether setuid execution is allowed for them.
.Ed
.Pp
.Ic fs sysname
.Op Ar sysname
.Bd -filled -offset indent -compact
Get or set the value of the '@sys' value.
.Ed
.Pp
.Ic fs version
.Bd -filled -offset indent -compact
Print version of fs and fs_lib.
.Ed
.Pp
.Ic fs venuslog
.Bd -filled -offset indent -compact
Make arlad print status.
.Ed
.Pp
.Ic fs whereis
.Op Ar path
.Bd -filled -offset indent -compact
Show server(s) of the specified file or the current directory.
.Ed
.Pp
.Ic fs whichcell
.Op Ar path
.Bd -filled -offset indent -compact
Show cell of a file or the current directory.
.Ed
.Pp
.Ic fs wscell
.Bd -filled -offset indent -compact
Display default cell of the client.
.Ed
.Pp
.Ic fs nnpfsdebug
.Bd -filled -offset indent -compact
Tweek nnpfs-debugging flags
.Ed
.Pp
.Ic fs nnpfsprint
.Op Ar flags
.Bd -filled -offset indent -compact
Make nnpfs print debug info.
.Ed
.Sh SEE ALSO
.Xr pts 1 ,
.Xr arlad 8 ,
.Xr bos 8 ,
.Xr vos 8
.Sh STANDARDS
The Arla authors are trying to mimic the behaviour of the original AFS
utilities.
.Sh AUTHORS
The Arla project <http://www.stacken.kth.se/project/arla/>.
.Sh BUGS
Some commands are not implemented yet.