Difference between revisions of "Afs"

From KGB Wiki
Jump to: navigation, search
m
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Some useful unix commands (because CSW doesn't teach you anything anymore). Please add more!
+
The '''A'''ndrew '''F'''ile '''S'''ystem is a networked filesystem implementation developed at CMU and later commercialized by Transarc.  It is one of the pillars of CMU's Andrew computing environment. Like many things bearing his name, the Andrew File System was developed by a team of Andrews, including the founder of our institution and the city of Pittsburgh: Andrew Carnegie. Largely developed in a decade between the 70s and 80s, AFS was originally used to share merry anecdotes of the adventures and mishaps of a certain Texas Ranger whose name has been stricken from these records. Over time it evolved into a giant monster capable of sustaining itself by consuming undergrads and grad students alike by issuing them 'tickets' (detailed below) in exchange for a small part of their soul.
  
 +
Recent developments made possible by [[jboning|jboning, hero and blanket of the people]] allow us to now [[rntz]] quite liberally on any given night.
  
pwd - 'present working directory', gives you the path to your current directory
+
== Tickets ==
  
fs la <directory> - Lists the access control list for a particular directory
+
Authentication under AFS (in fact, under Andrew more generally) is accomplished using the [[Kerberos]] protocol, which means we have to talk about tickets.  The entire world (not just CMU) is divided into Kerberos ''realms'', which are named in a way which closely tracks DNS.  CMU has (at least) four separate realms:  <tt>andrew.cmu.edu</tt> (the campus-wide Andrew network), <tt>cs.cmu.edu</tt> (SCS), <tt>ece.cmu.edu</tt> (the ECE department), and <tt>club.cc.cmu.edu</tt> (the computer club).  Normally, when you login to a Unix machine, you are just logging in to the local machine;  your account information is stored locally, and successfully logging in accomplishes nothing more than granting access to the local machine.  Most of the public machines on campus, however, use a special login service which authenticates to a particular Kerberos realm (usually Andrew, but school-specific clusters often authenticate to their own realms);  logging in to one of these machines grants you ''tickets'' associated with a particular ''principal'' --- usually, this is <tt>username@realm</tt>.  If you need to switch your principal, or if you need to re-authenticate, or if you're just not on a machine whose login service automatically acquires tickets for you, then you can always login using the <tt>kinit</tt> command.
fs sa <directory> <user> <options> - Sets the access control list for a particular directory
 
  
ACL options.  
+
An AFS filesystem associated with a Kerberos realm is called a ''cell''.  All of the public AFS cells in the world should be mounted in the directory <tt>/afs</tt> under the same name as their associated realm;  sometimes this list needs to be updated.
  
r - read
+
Logging in to a Kerberos realm grants you a ticket-granting ticket;  when you try to connect to most Kerberos-enabled services (e.g. Cyrus), the system attempts to use your ticket-granting tickets to grant you a more specific ticket for that service.  AFS cells, however, can be accessed anonymously, so you will sometimes need to instruct the filesystem to acquire AFS tickets when accessing a particular cell;  this can be done with the <tt>cklog</tt>, <tt>aklog</tt>, or <tt>afslog</tt> command (depending on your local configuration).
  
l - list (show directory contents)
+
AFS is much like a normal Unix filesystem, except:
 +
* File permissions do not use POSIX file modes;  instead, AFS uses an arbitrary access control list (see below).
 +
* File permissions are held on the immediately-containing directory;  files themselves only keep track of whether they're executable.
 +
* Hard links and named pipes are not supported.
 +
* Arbitrary device mount points are not supported;  however, pointers to other AFS volumes can be mounted within an arbitrary directory.
  
i - insert files
+
== Access Control Lists (ACLs) ==
  
d - delete files
+
An access control list consists of two sets of (principal, permissions) lists:  a '''normal''' rights section, which grants rights to those principals, and a '''negative''' rights section, which denies those rights.  Negative rights take precedence over normal rights.  Principals may either be users (written <tt>username@cell</tt>, or just abbreviated as <tt>username</tt> in the default cell) or groups (<tt>username:groupname@cell</tt>, or abbreviated as <tt>username:groupname</tt>).  There are two special groups:  <tt>system:authuser</tt> applies to any authenticated user, while <tt>system:anyuser</tt> applies to any user (authenticated or not);  note if a user has been denied access to a file, but the <tt>system:anyuser</tt> group has access to it, the user can simply clear his/her tickets to the cell and gain the denied permission.
  
w - write to files
+
The <tt>system:administrators</tt> group always has an implicit <tt>a</tt> (administrate) privilege on a directory.  The same applies to a  directory's owner, so if you ever accidentally deny yourself privileges to your own directory, know that you can simply change those privileges back.
  
k - ?
+
=== Privileges ===
  
a - administrator (able to set ACLs)
+
;a: administrate this directory by changing the entries of its ACL (implicitly granted to the file's owner and the <tt>system:administrators</tt> group)
 +
;l: list the files in this directory, <tt>stat(2)</tt> the directory itself, and list its ACL
 +
;r: read or <tt>stat(2)</tt> the files in this directory
 +
;w: modify files in this directory and change their Unix mode bits
 +
;d: delete files from this directory (either directly or by moving them out)
 +
;i: insert files into this directory (whether by creating them, copying them in, or moving them in)
 +
;k: set read/write locks on files in this directory
 +
;all: shorthand for all privileges
 +
;none: shorthand for no privileges
 +
;read: shorthand for <tt>rl</tt>
 +
;write: shorthand for <tt>rlidwk</tt>
  
To get more help, type fs help.
+
Privileges can be listed with the <tt>fs la</tt> command and modified with the <tt>fs sa</tt> command.
 +
 
 +
In general, you can only add entries to an ACL for principals registered with the cell's protection servers.  It '''is''' possible to register a "foreign" principal with that server, but I don't remember how to do it.
 +
 
 +
Negative privileges should generally be avoided.
 +
 
 +
== Useful Commands ==
 +
 
 +
;pwd: gives the canonical path to the current directory (by chasing '..' pointers up to the filesystem root).  This is not at all specific to AFS.
 +
;fs help: provides simple usage help for the <tt>fs</tt> commands
 +
;fs la ''directory'': lists the ACL for a directory
 +
;fs sa ''directory'' ''principal1'' ''privileges1'' ''principal2'' ''privileges2'' ...: grants the given privileges for the given principals (clearing any privileges those principals might already have)
 +
;fs sa -clear ''directory'' ''principal1'' ''privileges1'' ''principal2'' ''privileges2'' ...: sets the ACL for a directory to exactly the given list
 +
;fs sa -negative ''directory'' ''principal1'' ''privileges1'' ''principal2'' ''privileges2'' ...: denies the given privileges for the given principals
 +
;fs lq ''directory'': shows quota information for the volume containing the given directory
 +
;fs mkmount ''directory'' ''volume'': mounts a particular AFS volume at the given filename
 +
;fs lv ''directory'': shows volume information about the given directory
 +
;pts help: provides simple usage help for the <tt>pts</tt> commands
 +
;pts cg ''groupname'': creates a group with yourself as owner;  there are limits on how many groups you can have at once (it used to be 10)
 +
;pts mem ''groupname'': lists the membership of a group
 +
;pts adduser ''groupname'' ''user1'' ''user2'' ... : adds users to a group
 +
;pts removeuser ''groupname'' ''user1'' ''user2'' ... : removes users from a group

Latest revision as of 17:42, 17 August 2009

The Andrew File System is a networked filesystem implementation developed at CMU and later commercialized by Transarc. It is one of the pillars of CMU's Andrew computing environment. Like many things bearing his name, the Andrew File System was developed by a team of Andrews, including the founder of our institution and the city of Pittsburgh: Andrew Carnegie. Largely developed in a decade between the 70s and 80s, AFS was originally used to share merry anecdotes of the adventures and mishaps of a certain Texas Ranger whose name has been stricken from these records. Over time it evolved into a giant monster capable of sustaining itself by consuming undergrads and grad students alike by issuing them 'tickets' (detailed below) in exchange for a small part of their soul.

Recent developments made possible by jboning, hero and blanket of the people allow us to now rntz quite liberally on any given night.

Tickets

Authentication under AFS (in fact, under Andrew more generally) is accomplished using the Kerberos protocol, which means we have to talk about tickets. The entire world (not just CMU) is divided into Kerberos realms, which are named in a way which closely tracks DNS. CMU has (at least) four separate realms: andrew.cmu.edu (the campus-wide Andrew network), cs.cmu.edu (SCS), ece.cmu.edu (the ECE department), and club.cc.cmu.edu (the computer club). Normally, when you login to a Unix machine, you are just logging in to the local machine; your account information is stored locally, and successfully logging in accomplishes nothing more than granting access to the local machine. Most of the public machines on campus, however, use a special login service which authenticates to a particular Kerberos realm (usually Andrew, but school-specific clusters often authenticate to their own realms); logging in to one of these machines grants you tickets associated with a particular principal --- usually, this is username@realm. If you need to switch your principal, or if you need to re-authenticate, or if you're just not on a machine whose login service automatically acquires tickets for you, then you can always login using the kinit command.

An AFS filesystem associated with a Kerberos realm is called a cell. All of the public AFS cells in the world should be mounted in the directory /afs under the same name as their associated realm; sometimes this list needs to be updated.

Logging in to a Kerberos realm grants you a ticket-granting ticket; when you try to connect to most Kerberos-enabled services (e.g. Cyrus), the system attempts to use your ticket-granting tickets to grant you a more specific ticket for that service. AFS cells, however, can be accessed anonymously, so you will sometimes need to instruct the filesystem to acquire AFS tickets when accessing a particular cell; this can be done with the cklog, aklog, or afslog command (depending on your local configuration).

AFS is much like a normal Unix filesystem, except:

  • File permissions do not use POSIX file modes; instead, AFS uses an arbitrary access control list (see below).
  • File permissions are held on the immediately-containing directory; files themselves only keep track of whether they're executable.
  • Hard links and named pipes are not supported.
  • Arbitrary device mount points are not supported; however, pointers to other AFS volumes can be mounted within an arbitrary directory.

Access Control Lists (ACLs)

An access control list consists of two sets of (principal, permissions) lists: a normal rights section, which grants rights to those principals, and a negative rights section, which denies those rights. Negative rights take precedence over normal rights. Principals may either be users (written username@cell, or just abbreviated as username in the default cell) or groups (username:groupname@cell, or abbreviated as username:groupname). There are two special groups: system:authuser applies to any authenticated user, while system:anyuser applies to any user (authenticated or not); note if a user has been denied access to a file, but the system:anyuser group has access to it, the user can simply clear his/her tickets to the cell and gain the denied permission.

The system:administrators group always has an implicit a (administrate) privilege on a directory. The same applies to a directory's owner, so if you ever accidentally deny yourself privileges to your own directory, know that you can simply change those privileges back.

Privileges

a
administrate this directory by changing the entries of its ACL (implicitly granted to the file's owner and the system:administrators group)
l
list the files in this directory, stat(2) the directory itself, and list its ACL
r
read or stat(2) the files in this directory
w
modify files in this directory and change their Unix mode bits
d
delete files from this directory (either directly or by moving them out)
i
insert files into this directory (whether by creating them, copying them in, or moving them in)
k
set read/write locks on files in this directory
all
shorthand for all privileges
none
shorthand for no privileges
read
shorthand for rl
write
shorthand for rlidwk

Privileges can be listed with the fs la command and modified with the fs sa command.

In general, you can only add entries to an ACL for principals registered with the cell's protection servers. It is possible to register a "foreign" principal with that server, but I don't remember how to do it.

Negative privileges should generally be avoided.

Useful Commands

pwd
gives the canonical path to the current directory (by chasing '..' pointers up to the filesystem root). This is not at all specific to AFS.
fs help
provides simple usage help for the fs commands
fs la directory
lists the ACL for a directory
fs sa directory principal1 privileges1 principal2 privileges2 ...
grants the given privileges for the given principals (clearing any privileges those principals might already have)
fs sa -clear directory principal1 privileges1 principal2 privileges2 ...
sets the ACL for a directory to exactly the given list
fs sa -negative directory principal1 privileges1 principal2 privileges2 ...
denies the given privileges for the given principals
fs lq directory
shows quota information for the volume containing the given directory
fs mkmount directory volume
mounts a particular AFS volume at the given filename
fs lv directory
shows volume information about the given directory
pts help
provides simple usage help for the pts commands
pts cg groupname
creates a group with yourself as owner; there are limits on how many groups you can have at once (it used to be 10)
pts mem groupname
lists the membership of a group
pts adduser groupname user1 user2 ... 
adds users to a group
pts removeuser groupname user1 user2 ... 
removes users from a group