I have a short-ish TeXinfo document (13 pages of A4), which I include
below. You are welcome to use it for anything you want. We gave a
copy to everyone as we transitioned to AFS, and left an online info
copy where emacs can find it. Some of the stuff is specific to our
setup, but you should be able to edit it into something useful in your
environment. The document only covers the basics; other problems
were worked out in a local news group.
There is an AFS commands card included with each user manual from
Transarc.
--
Alan
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename afs
@settitle Beginners AFS Guide for DSG
@setchapternewpage off @c No new pages for the moment
@c %**end of header
@ifinfo
This file is intended as a short beginners guide to @sc{AFS}. It does not
cover all that you might need to know about @sc{AFS}, but instead tries to
cover the basics of what you will need to know.
@end ifinfo
@titlepage
@title Beginners AFS Guide for DSG
@subtitle Edition 0.6, December 1991
@subtitle @samp{amjudge@@cs.tcd.ie}
@author by Alan Judge
@end titlepage
@ifinfo
@node Top, Basics, (dir), (dir)
@top AFS
@sc{AFS} is a distributed file system. This file is intended as a fairly
short beginners guide to using @sc{AFS}. A working knowledge of standard
@sc{Unix} is assumed. Some specific details of the DSG setup are given.
@menu
* Basics:: Basics of AFS
* More on Volumes:: More on Volumes
* Authentication:: Authentication
* Access control lists:: Access control lists
* Where to find AFS commands:: Where to find AFS commands
@end menu
@end ifinfo
@iftex
@sc{AFS} is a distributed file system. This file is intended as a fairly
short beginners guide to using @sc{AFS}. A working knowledge of standard
@sc{Unix} is assumed. Some specific details of the @sc{DSG} setup are given.
This manual is also available online in the GNU info system. Type
@samp{info} for more details.
@sc{AFS} related discussion may appear in newsgroup @samp{dsg.afs}.
@end iftex
@node Basics, More on Volumes, Top, Top
@comment node-name, next, previous, up
@chapter Basics of AFS
@sc{AFS}, the Andrew File System, is a distributed file system allowing a
potentially large set of machines to share access to a set of files in a
uniform manner.
@sc{AFS} uses the @dfn{client/server} model, where all the data is stored on
file server machines. File are transferred to client machines as
necessary and cached locally.
@menu
* Cells:: Cells and filenames
* Using the system type in a path:: Using the system type in a path
* Volumes:: Volumes
* Tokens:: Tokens
* Checking if the AFS file servers are up::
* File protections:: File protections
* FS:: The @code{fs} command
@end menu
@node Cells, Using the system type in a path, Basics, Basics
@comment node-name, next, previous, up
@section Cells and filenames
A single administrative group of servers and clients is known as an @sc{AFS}
@dfn{cell}. Our local cell, containing all the machine in the
distributed systems group, is called @samp{dsg.cs.tcd.ie}.
Files within @sc{AFS} are named as @file{/afs/<cellname>/filepath}, and such
path names are uniform on all @sc{AFS} clients anywhere in the world. So,
for example, paths such as
@example
/afs/dsg.cs.tcd.ie/users/amjudge/.login
@r{or}
/afs/transarc.com/common/etc/CellServDB
@end example
are valid from @emph{any} @sc{AFS} client in the world.
@noindent To make local pathnames shorter, a symbolic link exists from
@file{/afs/dsg} pointing to@*
@file{/afs/dsg.cs.tcd.ie}, so locally @file{/afs/dsg/path} is valid.
@node Using the system type in a path, Volumes, Cells, Basics
@comment node-name, next, previous, up
@section Using the system type in a path
If the string @samp{@@sys} appears in a file name to be used in
@sc{AFS}, it is automagically replaced with @sc{AFS}'s concept of the
@dfn{type} of the machine that the file name is being expanded on.
So, the path @file{/afs/dsg/@@sys} is replaced with
@file{/afs/dsg/pmax_ul4} if running on a decstation running Ultrix
Version 4; on a sun 4 running SunOS 4.1.1, the pathname becomes
@file{/afs/dsg/sun4c_411}.
This feature may be used in pathnames or symbolic links to allow them to
be machine independent. For example, you may link @file{bin} in your
home directory to @file{@@sys/bin}. As another example,
@file{/usr/local} on most machines is a link to
@file{/afs/dsg/@@sys/usr/local}, and the correct binaries are chosen
automatically.
@node Volumes, Tokens, Using the system type in a path, Basics
@comment node-name, next, previous, up
@section Volumes
@sc{Unix} divides disks into @dfn{partitions}. @sc{AFS} further divides
partitions into subsections called @dfn{volumes}. A volume houses a
subtree of related files and directories. Normally, volumes are
considerably smaller than traditional file systems. For example, each
user's home directory would normally be stored in a separate volume.
Each major sub-directory of @file{/afs/dsg/work} and @file{/afs/dsg/src}
would also be stored in a separate volume. Large sub-directories are
further sub-divided.
You do not need to know which file server houses any volume. @sc{AFS} will
locate the volume automatically. Indeed, it may move during its
lifetime. If you wish to know where a volume is currently stored,
@pxref{Volume location}.
Volumes have a size limit, or @dfn{quota}. You may receive error
messages if the volume you are writing into exceeds its quota.
@xref{More on Volumes} for more details.
Access to volumes is provided through @dfn{mount points} (@pxref{Mount
points}). Mount points appear in the file system as directories. When
you @code{cd} into a directory, you may be crossing a mount point and
accessing a new volume, which may be stored on a different machine.
@node Tokens, Checking if the AFS file servers are up, Volumes, Basics
@comment node-name, next, previous, up
@section Tokens
@sc{AFS} does @emph{not} use @sc{Unix} user @sc{ID}s for authentication. In
order to access files which are not world accessable using @sc{AFS}, you must
have a valid @sc{AFS} @dfn{token}. You may see what tokens you currently hold
using the @samp{tokens} command.
For example:
@example
@cartouche
% tokens
Tokens held by the Cache Manager:
[ 1]User's (AFS ID 1) tokens for afs@@dsg.cs.tcd.ie
[Expires Dec 5 13:39]
[ 2] --End of list--
@end cartouche
@end example
This output says that the user holds a token for the cell
@samp{dsg.cs.tcd.ie} for @sc{AFS} user ID 1. You may hold extra tokens
for different cells, but you may not have more than one token for a
particular cell, so if you use @samp{klog} again, you old token will be
discarded.
Tokens expire after 25 hours, and may need to be renewed using the
@samp{klog} command. @xref{Authentication} for more details.
@node Checking if the AFS file servers are up, File protections, Tokens, Basics
@comment node-name, next, previous, up
@section Checking if the AFS file servers are up
You may check if the @sc{AFS} file servers for the cell are up using the
@samp{fs checkservers} command:
@example
@cartouche
% fs checks
All servers are running.
@end cartouche
@end example
@node File protections, FS, Checking if the AFS file servers are up, Basics
@comment node-name, next, previous, up
@section File protections
File protections do not work the same way in @sc{AFS} as they do in
@sc{Unix}. @sc{AFS} augments the standard @sc{Unix} file protection
mechanism, using a more precise mechanism for controlling access to
files: an @dfn{access control list} (@sc{ACL}).
@xref{Access control lists} for more details.
@node FS, , File protections, Basics
@comment node-name, next, previous, up
@section The @code{fs} command
The most generally useful @sc{AFS} command is @code{fs}. This command
is effectively a suite of commands of the form @samp{fs command args}.
Type @samp{fs help} for a full list. To find out the syntax for a
particular command, you can type @samp{fs help command}. For example:
@example
@cartouche
% fs help listquota
fs listquota: list volume quota
aliases: lq
Usage: fs listquota [-dir <directory>+] [-help ]
@end cartouche
@end example
The help lists any aliases for the command, and the arguments that the
command accepts. In general, the switches to an @sc{AFS} command may be
omitted @emph{if} the arguments are given in the order listed in the
help message. So, valid commands include:
@example
fs lq
fs lq /afs/dsg/src
fs lq -dir /afs/dsg/src
@end example
@node More on Volumes, Authentication, Basics, Top
@comment node-name, next, previous, up
@chapter More on Volumes
This chapter provide some more details about volumes. For even more
details, see the @sc{AFS} User's Guide, or the @sc{AFS} Command Reference Guide.
@menu
* Volume quotas:: Volume quotas
* Mount points:: Mount points
* Volume location:: Volume location
@end menu
@node Volume quotas, Mount points, More on Volumes, More on Volumes
@comment node-name, next, previous, up
@section Volume quotas
To examine the quota on a volume within AFS, the @samp{fs listquota}
command may be used. @samp{fs listquota} responds with the name of the
volume containing the specified directory, the quota size, amount used,
percent used, and the percent of space used on the partition containing
the volume.
@example
@cartouche
% fs lq /afs/dsg/src/X11R5/mit /usr/local/gnu
Volume Name Quota Used % Used Partition
src.X11R5.mit 250000 201262 81% 41%
pmax_ul4.usr.local.gnu 40000 28873 72% 31%
@end cartouche
@end example
All sizes are in kilobytes.
@node Mount points, Volume location, Volume quotas, More on Volumes
@comment node-name, next, previous, up
@section Mount points
You may find out if a particular directory, or list of directories, is a
mount point using the @samp{fs lsmount} command.
@example
@cartouche
% cd /afs/dsg/@@sys/usr/local
% fs lsm TeX X11 courier_database gnu man
'TeX' is a mount point for volume '#pmax_ul4.usr.local.TeX'
'X11' is a mount point for volume '#pmax_ul4.usr.local.X11'
'courier_database' is not a mount point.
'gnu' is a mount point for volume '#pmax_ul4.usr.local.gnu'
'man' is a mount point for volume '#pmax_ul4.usr.local.man'
@end cartouche
@end example
This output shows that all of the directories listed except
@samp{courier_database} are mount points for volumes. One can then use
@samp{fs lq} to get information about the quotas of the various volumes.
@node Volume location, , Mount points, More on Volumes
@comment node-name, next, previous, up
@section Volume location
You may find out what machine, or machines, have copies of a file (or,
more accurately, it's containing volume) using the @samp{fs whereis} command.
For example:
@example
@cartouche
% fs whereis /usr/local/show /afs/dsg/src/afs
File /usr/local/show is on hosts parker quays
File /afs/dsg/src/afs is on host parker
@end cartouche
@end example
Note that any volume which is replicated, such as the one containing
@file{/usr/local}, is read-only. If you need to access the
read-write copy of the volume, you should contact the System
Administrator for instructions.
@node Authentication, Access control lists, More on Volumes, Top
@comment node-name, next, previous, up
@chapter Authentication
The chapter contains some more details about authentication and tokens
for @sc{AFS}.
@menu
* Getting a token:: Getting a token
* Getting rid of a token:: Getting rid of a token
* Changing your AFS password:: Changing your AFS password
@end menu
@node Getting a token, Getting rid of a token, Authentication, Authentication
@comment node-name, next, previous, up
@section Getting a token
If, when you login, @samp{login} prints @samp{AFS 3.1 Login}, then a
token has been automatically obtained for you. You can verify that you have a
valid token with the @samp{tokens} command.
The X display manager (@sc{xdm}) has not yet been modified to obtain
tokens for users, so users using workstations or X terminals will have
to obtain a token manually. (This may change.) You may obtain a token
using the @samp{klog} command:
@example
@cartouche
% klog
Password: @emph{yourpassword}
@end cartouche
@end example
@quotation
@strong{Note:} Even when you log in using @sc{AFS} login, you will still need
to know how @samp{klog} works, as your tokens will still expire after 25 hours.
@end quotation
If you wish to access another users files temporarily, it is not
necessary to log out and log in again. Just issue a @samp{klog user}
command and continue as the other user.
@node Getting rid of a token, Changing your AFS password, Getting a token,
Authentication
@comment node-name, next, previous, up
@section Getting rid of a token
If you wish to destroy your token for a cell, you can use the
@samp{unlog} command. This is useful, for example, when you
authenticate as someone else temporarily, and then want to destroy the
token.
@node Changing your AFS password, , Getting rid of a token, Authentication
@comment node-name, next, previous, up
@section Changing your AFS password
You may change your @sc{AFS} password from any machine within the cell using
the @samp{kpasswd} command. The change takes effect throughout the cell
immediately.
@example
@cartouche
% kpasswd
Changing password for 'amjudge' in cell 'dsg.cs.tcd.ie'.
Old password: @emph{oldpass}
New password (RETURN to abort): @emph{newpass}
Retype new password: @emph{newpass}
Password changed.
@end cartouche
@end example
@quotation
@strong{Note:} We @emph{strongly} recommend that you use the same
password for both @sc{AFS} and your @sc{Unix} login. This will ease problems
as we migrate towards using @sc{AFS} passwords for logins.
@end quotation
@node Access control lists, Where to find AFS commands, Authentication, Top
@comment node-name, next, previous, up
@chapter Access control lists
Access control lists (@sc{ACL}s) are the main way that @sc{AFS} uses to
control access to files and directories. The most important point to
bear in mind when discussing @sc{ACL}s is that @emph{only} directories
have @sc{ACL}s in @sc{AFS}; access to files is controlled by the
@sc{ACL} of the containing directory.
Another important point to bear in mind is that when you create a new
subdirectory, it automatically inherits the @sc{ACL} that the parent had
at the time it was created, i.e., changing the parent @sc{ACL} in the
future will not change the child.
@sc{ACL}s override or replace almost all of the @sc{Unix} protection
bits. See @xref{Unix bits in AFS} for more details.
@menu
* Examining the ACL for a directory:: Examining the ACL for a directory
* How to decode an ACL:: How to decode an ACL
* Changing the ACL of a directory:: Changing the ACL of a directory
* Unix bits in AFS:: Unix bits in AFS
* Protection groups:: Protection groups
@end menu
@node Examining the ACL for a directory, How to decode an ACL, Access control lists,
Access control lists
@comment node-name, next, previous, up
@section Examining the ACL for a directory
You may use the command @samp{fs la}, or @samp{fs listacl}, to examine
the access control list that applies to a directory. For example:
@example
@cartouche
% fs la /afs/dsg/@@sys/usr/local/gnu
Access list for /afs/dsg/@@sys/usr/local/gnu is
Normal rights:
gnu rlidwk
amjudge a
system:administrators rlidwka
system:anyuser rl
@end cartouche
@end example
Every @sc{ACL} contains @samp{system:administrators rlidwka}; the entry
may safely be ignored. The rest of this @sc{ACL} says that anyone can
read files in this directory, and list the contents of the directory.
Members of the @samp{gnu} protection group (@pxref{Protection groups}),
can also write files in the directory, and add/delete files in the
directory. Additionally, user @samp{amjudge} may change the @sc{ACL}s
for the directory.
@node How to decode an ACL, Changing the ACL of a directory, Examining the ACL for a
directory, Access control lists
@comment node-name, next, previous, up
@section How to decode an ACL
Unlike @sc{Unix}, which has only three basic rights that may be controlled,
@sc{AFS} has seven different rights which may be individually controlled.
These rights are subdivided into two groups: four @dfn{directory} access
rights, and three @dfn{file} access rights.
@menu
* Directory access rights:: Directory access rights
* File access rights:: File access rights
@end menu
@node Directory access rights, File access rights, How to decode an ACL, How to decode
an ACL
@comment node-name, next, previous, up
@subsection Directory access rights
The four rights in this group apply to the directory itself. They are:
@table @samp
@item l
The @dfn{lookup} right allows the possessor:
@itemize @bullet
@item
to issue @samp{ls} to list the names of the files and
subdirectories in the directory. It does not allow the possessor to list
the contents of subdirectories unless she also has the lookup right in
the subdirectory's @sc{ACL}.
@item
to @samp{ls -l} the directory itself, and examine the @sc{ACL} for
the directory.
@item
to access the directory's subdirectories, subject to their own @sc{ACL}s.
@end itemize
@item i
The @dfn{insert} right allows the possessor to add new files and
subdirectories to the directory.
@item d
The @dfn{delete} right allows the possessor to remove files and
subdirectories from the directory.
@item a
The @dfn{administer} right allows the possessor to change the @sc{ACL}
for the directory.
@end table
@node File access rights, , Directory access rights, How to decode an ACL
@comment node-name, next, previous, up
@subsection File access rights
The three rights in this group only apply to files in the directory.
They are:
@table @samp
@item r
The @dfn{read} right allows the possessor to look at the contents of the
directory (i.e. @samp{ls -l}). For files in the directory, the
possessor can read the actual data in the file.
@item w
The @dfn{write} right allows the possessor to modify the contents of
files in the directory and to modify their @sc{Unix} mode bits with the
@samp{chmod} command.
@item k
The @dfn{lock} right allows the possessor to run programs that need to
@samp{flock} files in the directory.
@end table
@node Changing the ACL of a directory, Unix bits in AFS, How to decode an ACL, Access
control lists
@comment node-name, next, previous, up
@section Changing the ACL of a directory
The @sc{ACL} of a directory may be changed using the @samp{fs setacl}
command. By default, @samp{fs sa} adds to or alters the existing
@sc{ACL}, rather than replacing it entirely. So, for example, if you
wish to give user @samp{joe} the right to insert and delete files in a directory,
you can say:
@example
fs sa /afs/dsg/foo/bar joe di
@end example
As well as accepting any combination of the seven valid @sc{AFS}
rights as an argument, @samp{fs sa} also accepts the following
shorthand notations:
@table @code
@item write
All rights except @dfn{administer} (@code{a}) (i.e., @code{rlidwk})
@item read
@dfn{Read} and @dfn{lookup} rights (@code{rl})
@item all
All seven rights (@code{rlidwka})
@item none
no rights --- this removes the user's entry from the @sc{ACL} entirely.
@end table
So, if you wish to remove @samp{system:anyuser} from an
@sc{ACL} and allow @samp{system:authuser} to read files, you could say:
@example
fs sa /afs/dsg/foo/bar system:anyuser none system:authuser read
@end example
It is also possible to set @dfn{negative} access rights on a directory,
denying access, but this won't be discussed here.
@node Unix bits in AFS, Protection groups, Changing the ACL of a directory, Access
control lists
@comment node-name, next, previous, up
@section Unix bits in AFS
The @sc{Unix} mode bits set on a directory have @emph{no} effect in
@sc{AFS} and may be safely ignored.
However, the first three bits (the user bits) of a file's mode bits
@emph{do} have a meaning in @sc{AFS}. The file bits may be used to
further restrict access to a file that the @sc{ACL} allows access to.
So, for example, if the @sc{AFS} @sc{ACL} allows write access to a
directory, but the file bits look like @samp{-r--??????}, then the user
will not be allowed to write to the file.
Remember, however, that the user bits are applied to @emph{anyone} who
has access to the file; the owner of the file is irrelevant. Also,
@emph{anyone} who has write access to the file through the @sc{ACL} will
be allowed to change the protection bits using @samp{chmod}.
@node Protection groups, , Unix bits in AFS, Access control lists
@comment node-name, next, previous, up
@section Protection groups
An @sc{AFS} @dfn{protection group} is a somewhat similar concept to a
@sc{Unix} user group, except that it is used exclusively for file
protection in access control lists. Another difference is that @sc{AFS}
protection groups are managed by the distributed database component of
@sc{AFS}, and therefore is always up to date and may be modified from
any @sc{AFS} client in the cell.
@sc{AFS} provides a number of predefined protection groups that may be
used in any @sc{ACL}:
@table @code
@item system:anyuser
This is similar to world permissions in @sc{Unix}. Any @sc{AFS} user
(@emph{anywhere} in the world) can access files or directories made
accessible using this @sc{ACL}.
@item system:authuser
This is a more restrictive version of @samp{system:anyuser}: only users
who have authenticated within the local cell may access files made
accessible using this @sc{ACL}.
@end table
Within @sc{DSG}, a number of predefined system groups are also available:
@table @code
@item dsg
All @sc{DSG} staff, research assistants, and post-grads.
@item dsgstaff
All @sc{DSG} staff.
@item summer_students
Students working here during the summer.
@item undergrad
All undergraduate students using @sc{DSG} machines.
@item external
Non-@sc{DSG} people using @sc{DSG} hardware.
@item iona
Iona Technologies people.
@item amadeus
Members of the Amadeus development team.
@item ithaca
Ithaca project.
@item chorus
People working on Chorus related software.
@item mach
People working on Mach related software.
@item eiffel
Eiffel related stuff
@end table
In addition, users may create or manage their own protection groups,
that can be used by any user in any @sc{ACL}. See the @sc{AFS} User's
Guide for more details.
@node Where to find AFS commands, , Access control lists, Top
@comment node-name, next, previous, up
@chapter Where to find AFS commands
In order to be able to run the commands given in this manual directly,
you will need to add @file{/usr/afsws/bin} to your path. Generally,
@file{/usr/afsws} is a link into @sc{AFS}.
@contents
@bye
