(no commit message)
[openafs-wiki.git] / archive / LinuxAFSInstall / openafs-tools-cmd.README
1 ## OpenAFS Tools Documentation ##
2 ## A collection of open source programs and interfaces designed ##
3 ## to ease the configuration and maintenance of OpenAFS. ##
4 ##
5 ## Copyright 2001, International Business Machines Corporation and others.
6 ## All Rights Reserved.
7 ## 
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
11 ##
12 ## openafs-tools, Version 1.2.5 ##
13
14 ####################### TABLE OF CONTENTS ###########################
15
16 1) Overview
17 2) System configuration requirements
18  a) OS
19  b) OpenAFS
20  c) OpenAFS Tools
21 3) Usage
22  a) OpenAFS Installation
23  b) OpenAFS Uninstallation 
24 4) Implementation
25  a) OpenAFS Installation
26  b) OpenAFS Uninstallation
27 5) Known Problems
28 6) Future Expansion
29
30 ######################## 1) OVERVIEW ################################
31
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.  
40
41 ############# 2) SYSTEM CONFIGURATION REQUIREMENTS ##################
42
43 a) OS
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.  
48
49 b) OpenAFS
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 
52 are:
53     Red Hat 6.2:
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
58     Red Hat 7.1:
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
64 command).
65
66 c) OpenAFS Tools
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.
74
75 ########################## 3) USAGE #################################
76
77 a) OpenAFS Installation
78
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
85
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.
103
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.
107
108 b) OpenAFS Uninstallation 
109
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
117 installations.
118
119 ##################### 4) IMPLEMENTATION #############################
120
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.
126
127 a) OpenAFS Installation
128
129     The files involved in OpenAFS installation are:
130
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
139   - Perl scripts:
140     /usr/afs/tools/install/check_udebug.pl
141     /usr/afs/tools/install/write_fstab.pl
142     /usr/afs/tools/install/write_pam.pl
143
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 
150 OpenAFS.
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
161 server in the cell.
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, 
175 and vlserver).  
176   - The file server, volume server, and salvager processes are now 
177 started for servers.  
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.
201
202 b) OpenAFS Uninstallation
203
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 
208 begun.
209   - Then it kills whatever bos server processes may be running.  
210   - Next, it deletes everything stored in an AFS partition directory
211 ( i.e. vicep*).
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
217 /usr/afs.
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 
221 complete.
222
223 ##################### 5) KNOWN PROBLEMS #############################
224
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
234
235 #################### 6) FUTURE EXPANSION ############################
236
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
248 widely useful.
249   - Resolve all "Known Problems" (see section 5).
250   - Test, test, test.