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