doc: Replace src/SOURCE-MAP with src/README.md
[openafs.git] / 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 | afsinstall | Installation scripts and notes from IBM AFS |
170 | afsweb    | Authenticated AFS access for older versions of Apache |
171 | JAVA      | Java API library for OpenAFS development |
172 | kauth     | Obsolete Kerberos-4 server (`kaserver`) and related programs |
173 | log       | Obsolete programs to show and forget Kerberos-4 tokens |
174 | lwp       | Lightweight user-level non-preemptive cooperative threading library |
175 | pam       | Pluggable authentication modules (PAM) for kauth authentication |
176 | tests     | Legacy test scripts; new unit tests should be added to the top level `tests` directory |
177 | uss       | Tool for managing users; limited to kauth |
178 | vfsck     | OpenAFS specific `fsck` for obsolete inode-based file server partitions |