afs.txt 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258
  1. ====================
  2. kAFS: AFS FILESYSTEM
  3. ====================
  4. Contents:
  5. - Overview.
  6. - Usage.
  7. - Mountpoints.
  8. - Dynamic root.
  9. - Proc filesystem.
  10. - The cell database.
  11. - Security.
  12. - The @sys substitution.
  13. ========
  14. OVERVIEW
  15. ========
  16. This filesystem provides a fairly simple secure AFS filesystem driver. It is
  17. under development and does not yet provide the full feature set. The features
  18. it does support include:
  19. (*) Security (currently only AFS kaserver and KerberosIV tickets).
  20. (*) File reading and writing.
  21. (*) Automounting.
  22. (*) Local caching (via fscache).
  23. It does not yet support the following AFS features:
  24. (*) pioctl() system call.
  25. ===========
  26. COMPILATION
  27. ===========
  28. The filesystem should be enabled by turning on the kernel configuration
  29. options:
  30. CONFIG_AF_RXRPC - The RxRPC protocol transport
  31. CONFIG_RXKAD - The RxRPC Kerberos security handler
  32. CONFIG_AFS - The AFS filesystem
  33. Additionally, the following can be turned on to aid debugging:
  34. CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled
  35. CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled
  36. They permit the debugging messages to be turned on dynamically by manipulating
  37. the masks in the following files:
  38. /sys/module/af_rxrpc/parameters/debug
  39. /sys/module/kafs/parameters/debug
  40. =====
  41. USAGE
  42. =====
  43. When inserting the driver modules the root cell must be specified along with a
  44. list of volume location server IP addresses:
  45. modprobe rxrpc
  46. modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
  47. The first module is the AF_RXRPC network protocol driver. This provides the
  48. RxRPC remote operation protocol and may also be accessed from userspace. See:
  49. Documentation/networking/rxrpc.txt
  50. The second module is the kerberos RxRPC security driver, and the third module
  51. is the actual filesystem driver for the AFS filesystem.
  52. Once the module has been loaded, more modules can be added by the following
  53. procedure:
  54. echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
  55. Where the parameters to the "add" command are the name of a cell and a list of
  56. volume location servers within that cell, with the latter separated by colons.
  57. Filesystems can be mounted anywhere by commands similar to the following:
  58. mount -t afs "%cambridge.redhat.com:root.afs." /afs
  59. mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
  60. mount -t afs "#root.afs." /afs
  61. mount -t afs "#root.cell." /afs/cambridge
  62. Where the initial character is either a hash or a percent symbol depending on
  63. whether you definitely want a R/W volume (percent) or whether you'd prefer a
  64. R/O volume, but are willing to use a R/W volume instead (hash).
  65. The name of the volume can be suffixes with ".backup" or ".readonly" to
  66. specify connection to only volumes of those types.
  67. The name of the cell is optional, and if not given during a mount, then the
  68. named volume will be looked up in the cell specified during modprobe.
  69. Additional cells can be added through /proc (see later section).
  70. ===========
  71. MOUNTPOINTS
  72. ===========
  73. AFS has a concept of mountpoints. In AFS terms, these are specially formatted
  74. symbolic links (of the same form as the "device name" passed to mount). kAFS
  75. presents these to the user as directories that have a follow-link capability
  76. (ie: symbolic link semantics). If anyone attempts to access them, they will
  77. automatically cause the target volume to be mounted (if possible) on that site.
  78. Automatically mounted filesystems will be automatically unmounted approximately
  79. twenty minutes after they were last used. Alternatively they can be unmounted
  80. directly with the umount() system call.
  81. Manually unmounting an AFS volume will cause any idle submounts upon it to be
  82. culled first. If all are culled, then the requested volume will also be
  83. unmounted, otherwise error EBUSY will be returned.
  84. This can be used by the administrator to attempt to unmount the whole AFS tree
  85. mounted on /afs in one go by doing:
  86. umount /afs
  87. ============
  88. DYNAMIC ROOT
  89. ============
  90. A mount option is available to create a serverless mount that is only usable
  91. for dynamic lookup. Creating such a mount can be done by, for example:
  92. mount -t afs none /afs -o dyn
  93. This creates a mount that just has an empty directory at the root. Attempting
  94. to look up a name in this directory will cause a mountpoint to be created that
  95. looks up a cell of the same name, for example:
  96. ls /afs/grand.central.org/
  97. ===============
  98. PROC FILESYSTEM
  99. ===============
  100. The AFS modules creates a "/proc/fs/afs/" directory and populates it:
  101. (*) A "cells" file that lists cells currently known to the afs module and
  102. their usage counts:
  103. [root@andromeda ~]# cat /proc/fs/afs/cells
  104. USE NAME
  105. 3 cambridge.redhat.com
  106. (*) A directory per cell that contains files that list volume location
  107. servers, volumes, and active servers known within that cell.
  108. [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
  109. USE ADDR STATE
  110. 4 172.16.18.91 0
  111. [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
  112. ADDRESS
  113. 172.16.18.91
  114. [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
  115. USE STT VLID[0] VLID[1] VLID[2] NAME
  116. 1 Val 20000000 20000001 20000002 root.afs
  117. =================
  118. THE CELL DATABASE
  119. =================
  120. The filesystem maintains an internal database of all the cells it knows and the
  121. IP addresses of the volume location servers for those cells. The cell to which
  122. the system belongs is added to the database when modprobe is performed by the
  123. "rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
  124. the kernel command line.
  125. Further cells can be added by commands similar to the following:
  126. echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
  127. echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
  128. No other cell database operations are available at this time.
  129. ========
  130. SECURITY
  131. ========
  132. Secure operations are initiated by acquiring a key using the klog program. A
  133. very primitive klog program is available at:
  134. http://people.redhat.com/~dhowells/rxrpc/klog.c
  135. This should be compiled by:
  136. make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
  137. And then run as:
  138. ./klog
  139. Assuming it's successful, this adds a key of type RxRPC, named for the service
  140. and cell, eg: "afs@<cellname>". This can be viewed with the keyctl program or
  141. by cat'ing /proc/keys:
  142. [root@andromeda ~]# keyctl show
  143. Session Keyring
  144. -3 --alswrv 0 0 keyring: _ses.3268
  145. 2 --alswrv 0 0 \_ keyring: _uid.0
  146. 111416553 --als--v 0 0 \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM
  147. Currently the username, realm, password and proposed ticket lifetime are
  148. compiled in to the program.
  149. It is not required to acquire a key before using AFS facilities, but if one is
  150. not acquired then all operations will be governed by the anonymous user parts
  151. of the ACLs.
  152. If a key is acquired, then all AFS operations, including mounts and automounts,
  153. made by a possessor of that key will be secured with that key.
  154. If a file is opened with a particular key and then the file descriptor is
  155. passed to a process that doesn't have that key (perhaps over an AF_UNIX
  156. socket), then the operations on the file will be made with key that was used to
  157. open the file.
  158. =====================
  159. THE @SYS SUBSTITUTION
  160. =====================
  161. The list of up to 16 @sys substitutions for the current network namespace can
  162. be configured by writing a list to /proc/fs/afs/sysname:
  163. [root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname
  164. or cleared entirely by writing an empty list:
  165. [root@andromeda ~]# echo >/proc/fs/afs/sysname
  166. The current list for current network namespace can be retrieved by:
  167. [root@andromeda ~]# cat /proc/fs/afs/sysname
  168. foo
  169. amd64_linux_26
  170. When @sys is being substituted for, each element of the list is tried in the
  171. order given.
  172. By default, the list will contain one item that conforms to the pattern
  173. "<arch>_linux_26", amd64 being the name for x86_64.