Linux-2.6.12-rc2
[linux-2.6.git] / Documentation / filesystems / afs.txt
1                              kAFS: AFS FILESYSTEM
2                              ====================
3
4 ABOUT
5 =====
6
7 This filesystem provides a fairly simple AFS filesystem driver. It is under
8 development and only provides very basic facilities. It does not yet support
9 the following AFS features:
10
11         (*) Write support.
12         (*) Communications security.
13         (*) Local caching.
14         (*) pioctl() system call.
15         (*) Automatic mounting of embedded mountpoints.
16
17
18 USAGE
19 =====
20
21 When inserting the driver modules the root cell must be specified along with a
22 list of volume location server IP addresses:
23
24         insmod rxrpc.o
25         insmod kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
26
27 The first module is a driver for the RxRPC remote operation protocol, and the
28 second is the actual filesystem driver for the AFS filesystem.
29
30 Once the module has been loaded, more modules can be added by the following
31 procedure:
32
33         echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells
34
35 Where the parameters to the "add" command are the name of a cell and a list of
36 volume location servers within that cell.
37
38 Filesystems can be mounted anywhere by commands similar to the following:
39
40         mount -t afs "%cambridge.redhat.com:root.afs." /afs
41         mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
42         mount -t afs "#root.afs." /afs
43         mount -t afs "#root.cell." /afs/cambridge
44
45   NB: When using this on Linux 2.4, the mount command has to be different,
46       since the filesystem doesn't have access to the device name argument:
47
48         mount -t afs none /afs -ovol="#root.afs."
49
50 Where the initial character is either a hash or a percent symbol depending on
51 whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
52 volume, but are willing to use a R/W volume instead (percent).
53
54 The name of the volume can be suffixes with ".backup" or ".readonly" to
55 specify connection to only volumes of those types.
56
57 The name of the cell is optional, and if not given during a mount, then the
58 named volume will be looked up in the cell specified during insmod.
59
60 Additional cells can be added through /proc (see later section).
61
62
63 MOUNTPOINTS
64 ===========
65
66 AFS has a concept of mountpoints. These are specially formatted symbolic links
67 (of the same form as the "device name" passed to mount). kAFS presents these
68 to the user as directories that have special properties:
69
70   (*) They cannot be listed. Running a program like "ls" on them will incur an
71       EREMOTE error (Object is remote).
72
73   (*) Other objects can't be looked up inside of them. This also incurs an
74       EREMOTE error.
75
76   (*) They can be queried with the readlink() system call, which will return
77       the name of the mountpoint to which they point. The "readlink" program
78       will also work.
79
80   (*) They can be mounted on (which symbolic links can't).
81
82
83 PROC FILESYSTEM
84 ===============
85
86 The rxrpc module creates a number of files in various places in the /proc
87 filesystem:
88
89   (*) Firstly, some information files are made available in a directory called
90       "/proc/net/rxrpc/". These list the extant transport endpoint, peer,
91       connection and call records.
92
93   (*) Secondly, some control files are made available in a directory called
94       "/proc/sys/rxrpc/". Currently, all these files can be used for is to
95       turn on various levels of tracing.
96
97 The AFS modules creates a "/proc/fs/afs/" directory and populates it:
98
99   (*) A "cells" file that lists cells currently known to the afs module.
100
101   (*) A directory per cell that contains files that list volume location
102       servers, volumes, and active servers known within that cell.
103
104
105 THE CELL DATABASE
106 =================
107
108 The filesystem maintains an internal database of all the cells it knows and
109 the IP addresses of the volume location servers for those cells. The cell to
110 which the computer belongs is added to the database when insmod is performed
111 by the "rootcell=" argument.
112
113 Further cells can be added by commands similar to the following:
114
115         echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
116         echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells
117
118 No other cell database operations are available at this time.
119
120
121 EXAMPLES
122 ========
123
124 Here's what I use to test this. Some of the names and IP addresses are local
125 to my internal DNS. My "root.afs" partition has a mount point within it for
126 some public volumes volumes.
127
128 insmod -S /tmp/rxrpc.o 
129 insmod -S /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
130
131 mount -t afs \%root.afs. /afs
132 mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
133
134 echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells 
135 mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
136 mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
137 mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
138 mount -t afs "#grand.central.org:root.doc." /afs/grand.central.org/doc
139 mount -t afs "#grand.central.org:root.project." /afs/grand.central.org/project
140 mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
141 mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
142 mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
143
144 umount /afs/grand.central.org/user
145 umount /afs/grand.central.org/software
146 umount /afs/grand.central.org/service
147 umount /afs/grand.central.org/project
148 umount /afs/grand.central.org/doc
149 umount /afs/grand.central.org/contrib
150 umount /afs/grand.central.org/archive
151 umount /afs/grand.central.org
152 umount /afs/cambridge.redhat.com
153 umount /afs
154 rmmod kafs
155 rmmod rxrpc