src/README.md

   1 Guide to the OpenAFS source tree
   2 ================================
   3
   4 This is a guide to the various directories in the OpenAFS source code tree.
   5 Some directories contain source code for components of the OpenAFS system,
   6 while other directories are used by the build system to build libraries, kernel
   7 modules, and program variations. See the `Makefile` at the top of the project
   8 tree for build order and inter-dependencies.
   9
  10 RPC interface definitions (IDL)
  11 -------------------------------
  12
  13 The following directory contains interface definitions (IDL) files for the
  14 OpenAFS file server and cache manager.
  15
  16 | directory | description |
  17 | --------- | ----------- |
  18 | fsint     | File server and cache manager RPC interface definitions |
  19
  20 Cache Managers
  21 --------------
  22
  23 The following directories contain the source code of OpenAFS cache manager and
  24 related programs.
  25
  26 | directory | description |
  27 | --------- | ----------- |
  28 | afs       | The OpenAFS cache manager as a kernel-module for unix-like systems |
  29 | afsd      | The `afsd` user-space program to start the cache manager on unix-like systems |
  30 | aklog     | The Kerberos 5 login programs: `aklog`, `asetkey`, `akeyconvert` |
  31 | sys       | NFS translator local and remote system call interfaces |
  32 | venus     | The `fs` program and other cache manager related utilities |
  33 | WINNT     | The OpenAFS cache manager and installer for MS Windows |
  34 | export    | Symbol exports for AIX kernel module |
  35
  36 Servers
  37 -------
  38
  39 The following directories contain the source code of the OpenAFS servers and
  40 administrative command suites.
  41
  42 | directory | description |
  43 | --------- | ----------- |
  44 | bozo      | The basic overseer server and `bos` command suite |
  45 | ptserver  | The protection server and `pts` command suite |
  46 | update    | The update server and client for maintaining server software and configuration (deprecated) |
  47 | viced     | The file server |
  48 | vlserver  | The volume location server |
  49 | volser    | The volume server and `vos` command suite |
  50
  51 Backup system
  52 -------------
  53
  54 The following directories contain the source code of the OpenAFS backup system.
  55
  56 | directory | description |
  57 | --------- | ----------- |
  58 | bubasics  | Backup related RPC interface definitions |
  59 | bucoord   | Backup coordinator and support library |
  60 | budb      | Backup database server `buserver` |
  61 | butc      | Backup tape coordinator, and `read_tape` restoration client |
  62 | butm      | Backup tape manager library |
  63 | `bu_utils` | Backup utilities to estimate tape capacity and file mark sizes |
  64 | tsm41     | Tivoli storage manager support |
  65
  66
  67 Rx subsystem
  68 ------------
  69
  70 The following directories contain the source code of the Rx subsystem. Rx
  71 provides Remote Procedure Calls (RPC) over UDP/IP in user-space and kernel-mode,
  72 and includes an XDR implementation to encode and decode binary data.
  73
  74 | directory | description |
  75 | --------- | ----------- |
  76 | rx        | The Rx library for kernel and user-space |
  77 | rxdebug   | Debugging tool for rx |
  78 | rxgen     | The `rxgen` program to generate AFS RPC stubs from IDL (i.e., `*.xg`) |
  79 | rxgk      | Rxgk security class for rx |
  80 | rxkad     | Kerberos security module for rx |
  81 | rxosd     | Rx object storage device extensions IDL files |
  82 | rxstat    | Rx statistics package |
  83
  84 Libraries
  85 ---------
  86
  87 The following directories contain the source code for the various libraries
  88 used by OpenAFS.
  89
  90 | directory | description |
  91 | --------- | ----------- |
  92 | opr       | General purpose library for user-space and headers for kernel mode |
  93 | audit     | The `libaudit` event auditing support library |
  94 | auth      | The `libauth` library to manage key and cell configuration files |
  95 | cmd       | The `libcmd` library to parse command line arguments |
  96 | comerr    | The `com_err` library to provide error table lookup |
  97 | dir       | Modules to lookup, add, and remove entries in directory objects |
  98 | gtx       | A curses-based graphics library for terminal-based programs |
  99 | kopenafs  | The `libkopenafs` library for setting up stand-alone setpag() function for Heimdal/KTH libkafs |
 100 | libacl    | The `libacl` library for access control lists |
 101 | libadmin  | The `libadmin` administration API |
 102 | libafscp  | The `libafscp` library; client operations without a cache manager |
 103 | libafsrpc | The `libafsrpc` library; basic rx functionality for programs which do not require authentication |
 104 | libafsauthent | The `libafsauthent` library; for AFS-aware utilities |
 105 | procmgmt  | Process management library |
 106 | ubik      | Ubik replicated database library |
 107 | usd       | User-space device input/output library |
 108 | util      | Utility library (deprecated in favor of opr) |
 109 | vol       | Volume library for managing volumes on-disk |
 110
 111 Utilities
 112 ---------
 113
 114 The following directories contain source code for utilities and libraries for
 115 OpenAFS administrators.
 116
 117 | directory | description |
 118 | --------- | ----------- |
 119 | afsmonitor | Terminal-based file server and cache manager monitoring tool |
 120 | fsprobe   | File Server probe library and program |
 121 | scout     | Terminal-based file server monitoring tool |
 122 | tools     | Contributed configuration and maintenance tools |
 123 | xstat     | Command line tools and libraries for gathering file server and cache manager statistics |
 124
 125 Other
 126 -----
 127
 128 | directory | description |
 129 | --------- | ----------- |
 130 | external  | Contains imported code which is maintained in other open source projects |
 131 | platform  | Code for platform-specific programs and build specs. |
 132
 133
 134 Build system
 135 ------------
 136
 137 The following directories are build directories or contain components
 138 for the build system.
 139
 140 | directory | description |
 141 | --------- | ----------- |
 142 | cf        | OpenAFS specific M4 macros for `autoconf`  |
 143 | config    | Build system OS-specific configuration |
 144 | crypto    | `libhcrypto` library build directory |
 145 | dviced    | Demand Attach File Server (DAFS) build directory |
 146 | dvolser   | Demand Attach Volume Server build directory  |
 147 | finale    | Final stage build directory; includes `translate_et` which translates error codes to descriptive messages |
 148 | libafs    | OpenAFS kernel modules build directory |
 149 | libuafs   | OpenAFS user-space cache manager build directory |
 150 | packaging | Contributed packaging files for various platforms |
 151 | roken     | Build directory for `libroken`, a set of os-independent functions|
 152 | tbudb     | Pthreaded Backup Server (`budb`) build directory |
 153 | tbutc     | Pthreaded Backup Tape Coordinator (`butc`) build directory |
 154 | tptserver | Pthreaded Protection Server (`ptserver`) build directory |
 155 | tsalvaged | Pthreaded Salvage Server build directory; Used by Demand Attach File Server |
 156 | tubik     | Pthreaded ubik build directory |
 157 | tvlserver | Pthreaded Volume Location `vlserver` build directory |
 158 | tvolser   | Pthreaded Volume Server build directory |
 159
 160
 161 Not Maintained
 162 --------------
 163
 164 The following directories contain code of obsolete components which are no
 165 longer actively maintained.
 166
 167 | directory | description |
 168 | --------- | ----------- |
 169 | afsweb    | Authenticated AFS access for older versions of Apache |
 170 | JAVA      | Java API library for OpenAFS development |
 171 | kauth     | Obsolete Kerberos-4 server (`kaserver`) and related programs |
 172 | log       | Obsolete programs to show and forget Kerberos-4 tokens |
 173 | lwp       | Lightweight user-level non-preemptive cooperative threading library |
 174 | pam       | Pluggable authentication modules (PAM) for kauth authentication |
 175 | tests     | Legacy test scripts; new unit tests should be added to the top level `tests` directory |
 176 | uss       | Tool for managing users; limited to kauth |
 177 | vfsck     | OpenAFS specific `fsck` for obsolete inode-based file server partitions |