1 ## OpenAFS Tools Documentation ##
2 ## A collection of open source programs and interfaces designed ##
3 ## to ease the configuration and maintenance of OpenAFS. ##
5 ## Copyright 2001, International Business Machines Corporation and others.
6 ## All Rights Reserved.
8 ## This software has been released under the terms of the IBM Public
9 ## License. For details, see the LICENSE file in the top-level source
10 ## directory or online at http://www.openafs.org/dl/license10.html
12 ## openafs-tools, Version 1.2.5 ##
14 ####################### TABLE OF CONTENTS ###########################
17 2) System configuration requirements
22 a) OpenAFS Installation
23 b) OpenAFS Uninstallation
25 a) OpenAFS Installation
26 b) OpenAFS Uninstallation
30 ######################## 1) OVERVIEW ################################
32 The Tools use shell and Perl scripts. So far, they has been tested
33 only on Red Hat Linux 6.2 and 7.1 machines, running kernels 2.2 or 2.4.
34 As of this version, OpenAFS Tools has two functions:
35 installing OpenAFS, and uninstalling OpenAFS.
36 We hope that you enjoy using and developing these tools, and
37 that they enhance the popularity and use of OpenAFS. If you have
38 any questions, comments or suggestions, please send them to the
39 OpenAFS mailing lists.
41 ############# 2) SYSTEM CONFIGURATION REQUIREMENTS ##################
44 OpenAFS Tools has been developed and tested on machines running
45 Red Hat Linux 6.2 and 7.1, with kernel version 2.2 or 2.4. It may
46 or may not run well on other versions of Linux or other kernel
47 versions -- use caution when using them with other setups.
50 Finally, you need to download and install the OpenAFS 1.2.2 RPMs
51 for Red Hat Linux from http://www.openafs.org. The files you need
54 openafs-kernel-1.2.2-rh6.2.1.i386.rpm
55 openafs-1.2.2-rh6.2.1.i386.rpm
56 openafs-client-1.2.2-rh6.2.1.i386.rpm
57 openafs-server-1.2.2-rh6.2.1.i386.rpm
59 openafs-kernel-1.2.2-rh7.1.1.i386.rpm
60 openafs-1.2.2-rh7.1.1.i386.rpm
61 openafs-client-1.2.2-rh7.1.1.i386.rpm
62 openafs-server-1.2.2-rh7.1.1.i386.rpm
63 Once these are downloaded, install them (using an rpm -i or rpm -U
67 Now all that's left to do is install the OpenAFS Tools rpm. The
68 file you need is openafs-tools-1.2.2-1.i386.rpm. Install it using
69 an rpm -i or rpm -U command. This will create several directories
70 and populate your system with necessary files. The main directories
71 created and populated is:
72 /usr/afs/tools/install/
73 Now you should be ready to get started.
75 ########################## 3) USAGE #################################
77 a) OpenAFS Installation
79 Execute the /usr/afs/tools/install/install_afs command.
80 It can take a variety of arguments to specify how you would like
81 to set the machine up. If you do not specify needed arguments
82 on the command line, you will be prompted for them interactively.
83 To get a rundown on how to use install_afs, execute:
84 /usr/afs/tools/install/install_afs help
86 If you are creating an additional server or not a server, OpenAFS
87 Tools will ensure that you have all the required files on your
88 system. These are files needed by the OpenAFS installation program
89 to connect you to cells that already exist. You must get these files
90 manually from an existing server, as we have not yet implemented
91 a secure way of doing this automatically. For additional servers,
92 the files you need to copy are:
93 - Copy the /usr/afs/etc/ThisCell file from the existing server
94 to /usr/afs/tools/install/afs/ThisCell on your machine.
95 - Copy the /usr/afs/etc/CellServDB file from the existing server
96 to /usr/afs/tools/install/afs/CellServDB on your machine.
97 - Copy the /usr/afs/etc/KeyFile file from the existing server
98 to /usr/afs/tools/install/afs/KeyFile on your machine.
99 - Copy the /usr/afs/etc/UserList file from the existing server
100 to /usr/afs/tools/install/afs/UserList on your machine.
101 - Copy the /usr/vice/etc/CellServDB file from the existing server
102 to /usr/afs/tools/install/vice/CellServDB on your machine.
104 For client-only installation, you need the following file:
105 - Copy the /usr/vice/etc/CellServDB file from the existing server
106 to /usr/afs/tools/install/vice/CellServDB on your machine.
108 b) OpenAFS Uninstallation
110 The uninstallation program is very simple. Just run
111 /usr/afs/tools/install/afs_uninstall
112 It does not accept any arguments and will not prompt you for
113 anything. Be forewarned, however: this will uninstall OpenAFS from
114 your system and delete any information served from that machine in
115 OpenAFS filespace. You should also restart your machine after
116 running the command, to avoid potential problems with future OpenAFS
119 ##################### 4) IMPLEMENTATION #############################
121 This section will focus on the details of the implementation of
122 OpenAFS tools. It will outline the code and file structure of the
123 package, and will document the choices made during implementation, so
124 that someone working on the code can have a better understanding for
125 what's there already.
127 a) OpenAFS Installation
129 The files involved in OpenAFS installation are:
131 - Possible AFS configuration files (/etc/sysconfig/afs):
132 /usr/afs/tools/install/afsinit_both
133 /usr/afs/tools/install/afsinit_server
134 /usr/afs/tools/install/afsinit_client
135 - Checking the state of OpenAFS on the system:
136 /usr/afs/tools/install/.afs_state
137 - Command line installation:
138 /usr/afs/tools/install/install_afs
140 /usr/afs/tools/install/check_udebug.pl
141 /usr/afs/tools/install/write_fstab.pl
142 /usr/afs/tools/install/write_pam.pl
144 What follows is a brief summary of the installation process.
145 - Installation starts with the script install_afs. The first thing
146 it does is ensure that the files needed for setting up additional
147 servers and/or clients exist in the appropriate places (see section
148 3.a for a description of these files). Then, after indicating to
149 the state file that installation has begun, it begins installing
151 - For clients, it then enables Pam Login Authentication using
152 the write_pam.pl program to change the /etc/pam.d/login file.
153 - For servers, it will alter the /etc/fstab file via the
154 write_fstab.pl program, mounting the user-specified hard drive to
155 the /vicepa directory.
156 - For additional servers, it now copies the required
157 files from the /usr/afs/tools/install/afs directory to the
158 /usr/afs/etc directory, and defines the upclient processes,
159 which will periodically update the server's /usr/afs/bin and
160 /usr/afs/etc directories based on those directories on the first
162 - A first server must then briefly start up a bosserver with
163 the noauth flag in order to create the keyfile and set the cell
164 name. It immediately shuts down the bosserver when this is down.
165 Next, it uses a kaserver with noauth to initialize cell security.
166 This involves creating two user accounts: afs and admin. afs is an
167 account for the server processes and will not be needed by the user.
168 Currently we use the administrative password for the afs account
169 password. The admin account is now added to the bos server database
170 and a pts entry is created as well. Also, the afs account password
171 is added as a key for the server. The kaserver process is terminated.
172 The pts database is then bootstrapped to add the administrator to it.
173 - For first servers, a normal bosserver is started. It then
174 creates the database server processes (kaserver, buserver, ptserver,
176 - The file server, volume server, and salvager processes are now
178 - Next the root.afs volume is created for first servers, and on
179 additional servers the vldb is synced up.
180 - On a first server, the upserver process is then defined.
181 - Next the /usr/vice/etc/ThisCell file is created on a non-server
182 machine, and for non-first-servers the /usr/vice/etc/CellServDB file
183 is copied from its location at /usr/afs/tools/install/vice.
184 - The correct AFS setup file is copied to /etc/sysconfig/.
185 - Now the bosserver process is killed for server machines.
186 - The next thing it does is initialize afs (/etc/rc.d/init.d/afs),
187 and for servers it klogs in as admin.
188 - Then it activates the OpenAFS initialization script by running
189 /sbin/chkconfig --add afs.
190 - Next a first server will configure the OpenAFS file space.
191 Before doing this, however, it must first wait until a quorum has
192 been elected. After the check, the root.cell volume is created,
193 it is mounted at /afs/<cell_name>, and the permissions are set
194 on both it and /afs as read and lookup for any user. A read-write
195 version of root.cell is mounted at /afs/.<cell_name>. Replication
196 sites for both root.afs and root.cell are added.
197 - If necessary, client functionality is removed.
198 - Lastly, a done.txt file is written explaining what has been done
199 and what comes next, for use by the web interface. The state file
200 is notified that installation is complete, and then the script ends.
202 b) OpenAFS Uninstallation
204 Uninstallation has only one file:
205 /usr/afs/tools/install/afs_uninstall
206 Here is a brief summary of what it does to uninstall OpenAFS:
207 - First it indicates to the state file that uninstallation has
209 - Then it kills whatever bos server processes may be running.
210 - Next, it deletes everything stored in an AFS partition directory
212 - It deletes the links to any initialization scripts in the startup
213 directories (/etc/rc.d/rc*.d/*afs*)
214 - It removes the PAM afs file, and reconfigures the PAM login file
215 to not have integrated AFS logon.
216 - It deletes the db, etc, local, and logs directories from
218 - Next it removes unnecessary files from /usr/vice/etc.
219 - Then it deletes everything from the cache (/usr/vice/cache).
220 - Finally, it informs the state file that uninstallation is
223 ##################### 5) KNOWN PROBLEMS #############################
225 We have encountered a few problems along the way, and wanted to
226 document them as such.
227 - Be careful when installing something without client
228 functionality. This seems to require an extra reboot of the
229 machine. After installing OpenAFS, restart your machine again,
230 and that should get it working properly.
231 There very well be some other problems that we haven't
232 yet encountered. If you encounted such a problem, please send a
233 description to openafs-devel@openafs.org
235 #################### 6) FUTURE EXPANSION ############################
237 There is a lot of room for developing this package into something
238 very useful, and we would like to make a few suggestions for future
239 additions/fixes to the code.
240 - Allow ways to authenticate other than the kaserver, such as krb5.
241 - Find a secure, automatic way to transfer files from a server
242 machine to a machine that is to be set up as an additional server or
243 a client, rather then require the manual tranferral of those files.
244 - Agree on a standard way to set up the filespace of a cell, as in
245 where to put the user volumes, etc., so that this can all be done
246 automatically by the scripts.
247 - Port this code to other operating systems to make it more
249 - Resolve all "Known Problems" (see section 5).