blob: 2f4237dfb8c70b8d95a7b657c89e8eac3e33f98a [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001 kAFS: AFS FILESYSTEM
2 ====================
3
4ABOUT
5=====
6
7This filesystem provides a fairly simple AFS filesystem driver. It is under
8development and only provides very basic facilities. It does not yet support
9the 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
18USAGE
19=====
20
21When inserting the driver modules the root cell must be specified along with a
22list 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
27The first module is a driver for the RxRPC remote operation protocol, and the
28second is the actual filesystem driver for the AFS filesystem.
29
30Once the module has been loaded, more modules can be added by the following
31procedure:
32
33 echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells
34
35Where the parameters to the "add" command are the name of a cell and a list of
36volume location servers within that cell.
37
38Filesystems 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
50Where the initial character is either a hash or a percent symbol depending on
51whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
52volume, but are willing to use a R/W volume instead (percent).
53
54The name of the volume can be suffixes with ".backup" or ".readonly" to
55specify connection to only volumes of those types.
56
57The name of the cell is optional, and if not given during a mount, then the
58named volume will be looked up in the cell specified during insmod.
59
60Additional cells can be added through /proc (see later section).
61
62
63MOUNTPOINTS
64===========
65
66AFS 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
68to 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
83PROC FILESYSTEM
84===============
85
86The rxrpc module creates a number of files in various places in the /proc
87filesystem:
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
97The 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
105THE CELL DATABASE
106=================
107
108The filesystem maintains an internal database of all the cells it knows and
109the IP addresses of the volume location servers for those cells. The cell to
110which the computer belongs is added to the database when insmod is performed
111by the "rootcell=" argument.
112
113Further 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
118No other cell database operations are available at this time.
119
120
121EXAMPLES
122========
123
124Here's what I use to test this. Some of the names and IP addresses are local
125to my internal DNS. My "root.afs" partition has a mount point within it for
126some public volumes volumes.
127
128insmod -S /tmp/rxrpc.o
129insmod -S /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
130
131mount -t afs \%root.afs. /afs
132mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
133
134echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells
135mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
136mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
137mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
138mount -t afs "#grand.central.org:root.doc." /afs/grand.central.org/doc
139mount -t afs "#grand.central.org:root.project." /afs/grand.central.org/project
140mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
141mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
142mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
143
144umount /afs/grand.central.org/user
145umount /afs/grand.central.org/software
146umount /afs/grand.central.org/service
147umount /afs/grand.central.org/project
148umount /afs/grand.central.org/doc
149umount /afs/grand.central.org/contrib
150umount /afs/grand.central.org/archive
151umount /afs/grand.central.org
152umount /afs/cambridge.redhat.com
153umount /afs
154rmmod kafs
155rmmod rxrpc